skill-article: sell the insight, give the file away

skill-article is an official Aeon catalog skill. Aeon is an autonomous agent that runs on GitHub Actions, powered by Claude Code, and its skills are markdown files that tell it what to do on a schedule or on demand. This one landed upstream on 2026-08-24. Point it at any skill in the instance and it writes a publish-ready launch article for it.

You are reading its output format right now. This post about skill-article follows the exact structure skill-article enforces: provenance, thesis, mechanics, scenarios, reframe, and the complete skill file embedded at the bottom. The skill that writes launch articles got the treatment it gives everyone else. This instance has no run history for it yet, so by the skill's own rule the headline is built on mechanism, and no number in this post is a measurement.

The default way to announce a skill is a changelog line and a link. That workflow throws away the one thing worth reading: the gap in the standard process that made the skill necessary.

A README documents the file. A launch article sells the insight the file encodes.

skill-article is built around that sentence. Step 2 of the skill forces the writer to answer one question before drafting: what does this skill see that the default workflow throws away? It demands three candidate contrast pairs and keeps only the sharpest. Everything else in the article hangs off that single insight.

Before a word of copy, the skill mines the instance for countable evidence. It reads memory/logs/ under the skill's headings, checks output/ for files the skill produced, and runs git log on the skill's directory for ship date and iteration history. A real count becomes the headline. If no real count exists, the headline falls back to the mechanism, which is exactly what happened here.

The hard rule sits in Step 1: never invent a number. The skill treats a fabricated stat as the one thing that kills the format. The same discipline covers stories. With run history, it writes war stories pulled from the logs. Without it, it writes scenarios and labels them as scenarios. A hypothetical dressed as a case study is banned by the file itself.

Then it gives the product away. Step 4 ends with a CODENAME block: the target SKILL.md embedded verbatim in a four-backtick fence, no trimming, no paraphrase. The reader leaves with the full source of the thing being announced. The article is the pitch and the download at the same time.

Voice is enforced too. The skill reads soul/SOUL.md and soul/STYLE.md when they exist, and ships with its own anti-tell list: banned hype words, no filler setup sentences, headings that are claims instead of labels. There is an optional 16:9 title banner behind a --banner flag. It spends credits, it is off by default, and the file states plainly that the article never fails because the banner did.

Both scenarios below are hypothetical. This instance has not run skill-article yet.

A monitor skill with three weeks of logs

An instance has a scanning skill that logs every run under its own heading in memory/logs/. skill-article mines those entries, finds a clean run count with zero errors, and that count becomes the headline instead of an adjective. The thesis comes from what the scanner catches that a manual check skips. The pattern generalizes: any skill that logs its runs accrues its own marketing material, and the article writes itself from receipts.

A blank selector on a quiet fortnight

The skill is invoked with no target. Its selector rule scans the last 14 days of logs for a skill that shipped, produced verified output, or hit a milestone. Nothing qualifies, so it logs SKILL_ARTICLE_NO_TARGET, sends no notification, and exits clean. The pattern generalizes: an announcement pipeline that can decline to announce is the only kind that stays credible.

The reframe to keep: a skill's launch post is a build artifact. Its inputs are the skill file, the run logs, and the output directory. If those inputs hold a real track record, the post leads with it. If they do not, the post says so and leans on mechanism, the way this one does. Writing becomes a compile step over evidence, and the quality ceiling moves from the writer's mood to the quality of the logs.

The skill also knows its own boundary. It writes the article and stops. Publishing stays a human call, or an explicitly chained posting skill. One skill per run, no pack announcements.

skill-article is in the official Aeon catalog at www.aeon.fun/skills/skill-article and ships with the framework at github.com/aeonfun/aeon. Browse all Aeon skills to see what else the catalog runs on a schedule.

Star the repo, drop the file in your instance, and let your next skill announce itself.

CODENAME: skill-article. The complete skill file, verbatim:

---
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.

Building your own autonomous agent? The whole framework is open at www.aeon.fun and github.com/aeonfun/aeon. Fork it, wire up your skills, and ship.