Skill Article

---
name: skill-article
description: Turn any skill in this instance into a publish-ready launch article - proof-stat headline, one contrarian thesis, mechanics, war stories from real run history, a mental-model reframe, and the full SKILL.md embedded verbatim so readers can steal it. Optional Higgsfield title banner with --banner.
metadata:
  title: Skill Article
  category: basics
  var: ""
  tags:
    - content
    - meta
---

> **${var}** — Selector: `<skill-name> [--brand <handle>] [--banner]`.
>
> - **`<skill-name>`** → announce that skill (must exist under `skills/<skill-name>/`).
> - **empty** → pick the most article-worthy skill from the last 14 days of `memory/logs/`: prefer a skill that shipped recently, produced verified output, or hit a milestone. If nothing qualifies, log `SKILL_ARTICLE_NO_TARGET`, send no notification, and exit clean.
> - **`--brand <handle>`** anywhere → byline/handle for the outreach footer (default: this instance's public identity from `soul/`, else the repo's org).
> - **`--banner`** anywhere → also generate one 16:9 title banner through the Higgsfield MCP (spends credits; see Step 5). Off by default - a blank run never spends.
>
> Examples: `"aeon-update"`, `"rug-scan --brand @myproject --banner"`.

Today is ${today}. Write a launch article for one skill, modeled on the security-industry "skill announcement" format: the article sells the *insight* the skill encodes, not the file - and then gives the file away.

## Shared preamble

1. Read `memory/MEMORY.md` and the last 14 days of `memory/logs/` - know what this skill has actually done.
2. If a `soul/` directory exists, read `soul/SOUL.md` and `soul/STYLE.md` for voice. Default voice: terse, declarative, builder-wrote-this-fast.
3. Read the target's full `skills/<name>/SKILL.md`. Every claim in the article must trace to a line in it.

## Step 1 — Mine the track record (real numbers only)

Hunt for countable proof before writing a word:

- `memory/logs/` entries under the skill's `### <name>` headings: runs, OK/error statuses, notable outcomes.
- `output/` files the skill produced; PRs or issues it opened (`gh pr list --search`).
- `git log -- skills/<name>/` for ship date and iteration history.

A real stat ("84 verified findings", "31 runs, 0 false alarms") becomes the headline. **If no real count exists, the headline uses the mechanism instead.** Never invent a number - a fabricated stat is the one thing that kills this format.

## Step 2 — Find the thesis

Answer: **what does this skill see that the default workflow throws away?** That gap is the thesis.

Write 3 candidate contrast pairs (two-sided sentences like "production code shows what the system does; tests show what its developers thought it did") and keep the sharpest. Everything in the article hangs on this one insight.

## Step 3 — Collect war stories

1-3 concrete moments where the skill caught or produced something a naive approach would miss - pulled from `memory/logs/` and `output/`, anonymized where needed, mechanism kept visible.

If the skill has no run history yet, write "how it plays out" scenarios and **label them as scenarios**. Never dress a hypothetical as a case study.

## Step 4 — Write the article

Structure, in order:

1. **Headline**: `<Skill Name>: <proof stat or mechanism claim>`. Bold claim, not a setup.
2. **Provenance** (2 short paragraphs): what it is, where it runs, ship date, track record if real.
3. **Thesis section** with a punchy heading (a claim, never a label): what everyone else's workflow misses.
4. **Mechanics** (2-4 short paragraphs) built around the contrast pair.
5. **War stories**: one mini-heading per story, 2-4 sentences each, ending with the generalized pattern ("The same blind spot appears when...").
6. **Reframe section**: the mental-model shift the reader keeps even if they never run the skill.
7. **Ship it**: where it lives + one-line CTA (star the upstream repo).
8. **`CODENAME: <Skill Name>`**: the target SKILL.md embedded verbatim in a fenced block (use a 4-backtick fence - skill files contain 3-backtick fences). Do not paraphrase or trim it.
9. **Outreach footer**: 1-2 sentences, DMs-open style, pointing at the brand handle.

## Voice rules (the anti-tells)

- Short declarative sentences. Cut every sentence that only sets up the next one.
- Banned: "revolutionary", "game-changing", "unleash", "delve", "Let's dive in".
- No parallel-structure trios, no "not X, but Y" scaffolding.
- Section headings are claims or scenes ("There is an alpha in the test folder"), never labels ("Overview").
- Verify the repo/link in the CTA exists this run before naming it.
- Never reference private forks or internal accounts - describe this instance generically and point at the upstream/public repo.

## Step 5 — Title banner (only with `--banner`)

Skip this step entirely unless `--banner` was passed. When it was:

1. **Check the connection first.** If no `mcp__higgsfield__*` tool is callable, the banner is skipped, not the article: note `banner: HIGGS_NOT_CONNECTED` for the log, point the operator at the dashboard → MCP → Connect Higgsfield in the notify, and continue to Step 6. Same on 401/stale auth (`banner: HIGGS_AUTH_STALE`) or insufficient credits (`banner: HIGGS_NO_CREDITS`). The article never fails because the banner did.
2. **Build the prompt from the thesis, not the feature list.** The banner is a visual metaphor for the Step 2 contrast pair - the scene that makes the insight visible. Image models garble long text, so the only text allowed in the prompt is the skill's short name (or none); the headline lives in the article, not the pixels. Match `soul/` aesthetic if it defines one; otherwise: clean, high-contrast, one focal object, no collage.
3. **Generate exactly one image**, `--ar 16:9`, following the `higgsfield` skill's spend rules: one generation per run, one retry at most on a transient error, never re-submit a job that already succeeded. Poll to completion with a bounded number of polls; on timeout record `banner: HIGGS_FAILED` and move on.
4. **Capture the asset URL verbatim.** Never fabricate one. Banner asset URLs may be time-limited signed URLs - flag that in the notify so the operator saves it.

Embed the result at the top of the article file, next to the alts block:

```markdown
<!-- banner: <asset-url> · model: <model> · job: <id> -->
```

## Step 6 — Deliver

1. Write the article to `output/skill-articles/${today}-<skill-name>.md` (shell redirection; `mkdir -p` first). Include an `<!-- alts -->` comment block at the top with 2 alternative headline + thesis-heading pairs so the operator can iterate without a rewrite.
2. Notify with `./notify -f /tmp/skill-article-notify.md` (write the body under `/tmp/`): the headline, the thesis in one line, whether the stats are real or the headline fell back to mechanism, the banner URL when one was generated (with a save-it note if the URL is signed/expiring), and a **clickable** link built from the run's environment:

   ```bash
   ARTICLE_URL="${GITHUB_SERVER_URL:-https://github.com}/${GITHUB_REPOSITORY}/blob/main/output/skill-articles/<file>.md"
   ```

3. Log to `memory/logs/${today}.md` under a `### skill-article` heading: target skill, headline, thesis pair, stats-real-or-mechanism, output path, and - when `--banner` was passed - a `banner:` line (`HIGGS_OK <url>` | `HIGGS_NOT_CONNECTED` | `HIGGS_AUTH_STALE` | `HIGGS_NO_CREDITS` | `HIGGS_FAILED` | `skipped`). Status codes: `SKILL_ARTICLE_OK` on success, `SKILL_ARTICLE_NO_TARGET` when `${var}` was empty and nothing article-worthy exists, `SKILL_ARTICLE_NOT_FOUND` when the named skill has no `SKILL.md`.

## Limits

- This writes the article; it does not post it. Publishing is the operator's call (or a posting skill's, explicitly chained).
- The banner is opt-in and spends real Higgsfield credits - one image per run, hard cap, and its failure never blocks the article.
- Track-record mining is only as good as `memory/logs/` - a skill that runs but never logs will read as unproven, and the article will say so rather than guess.
- One skill per run. Announcing a pack is a different article; run once per skill instead.