diff --git a/.agents/writing-docs.md b/.agents/writing-docs.md index a11f920..d24058b 100644 --- a/.agents/writing-docs.md +++ b/.agents/writing-docs.md @@ -12,7 +12,9 @@ There is no H1 — the published page takes its title from the slug. ## Page structure -Fill the template below. The **fixed frame** (`## What it does`, `## When to reach for it`, `## Where it fits`) appears on every page. The **adaptable middle** — `## Prerequisites` and the free-form substance sections — carries only what this particular skill earns; delete the rest. +Fill the template below, keeping its order. The **fixed frame** (`## What it does`, `## When to reach for it`, `## Where it fits`) appears on every page. `## Prerequisites` and the free-form substance sections carry only what this particular skill needs; delete the rest. + +Four sections make a page worth reading: `What it does`, `When to reach for it`, `Common questions`, `It's working if`. The first two orient the reader; the last two are where the page stops summarising the skill and starts answering the reader's own situation. Each of the last two has a bar to clear, below — but treat a page that clears neither as unfinished, not as finished-and-short. **A page carries no install commands.** The ai-hero page template renders the install widget itself — a copy button, the single-skill command, the whole-set command, and the update line — above the body. A page that also writes them out shows the reader the same command twice, and the two copies drift: the hand-written pair on every page went stale against the widget beside it. Install wording is a property of the site, not of the page. If it needs changing, change it in ai-hero; the canonical wording lives in [the install block](./install-block.md). @@ -39,9 +41,21 @@ One to three short sections, in the skill's *own vocabulary*, that make it click The single non-negotiable: **surface the skill's leading word / defining idea** — `tight` feedback loop, `deep module`, throwaway-code-answers-a-question, red-green. It pays off twice: the reader learns what the skill *is*, and learns the word they'll later think with to *reach for* it. +## Common questions + +The questions readers really ask about this skill, each in bold with the answer in the lines beneath it — no sub-headings. + +Every question here is one someone asked. That is the section's whole value: a page with three observed questions beats one with eight plausible ones, because an invented question teaches the reader nothing and reads as filler. So go and find them before you write any: + +- **The wiki.** If `~/repos/matt/personal-wiki` exists on this machine, it is the richest source there is. Its `wiki/audience/` area is organised around what the audience wants, discusses, and **is confused by** — read `wiki/index.md` first for the registry of pages, then the pages bearing on this skill. Every page carries `sources:` linkbacks to the original X, Discord, GitHub, and email threads; the wiki is a secondary source, so quote the asker's own question rather than the wiki's summary of it. Skip this bullet where the directory does not exist. +- **This repo's issues.** `gh issue list --repo mattpocock/skills --search "" --state all`. A question filed twice is a question the page owes an answer to. +- **`CHANGELOG.md`.** Anything renamed, moved, or behaviourally changed generates a "where did it go?" that the page has to answer. + +Order them by how often each comes up, sharpest first, and say the unflattering thing where it is true — a very long grilling session usually means the scope was too big; a model asked to write its own skill produces something verbose. Omit the heading where the hunt turns up nothing. + ## It's working if -Optional. A short, checkable list of the observable signals that tell the reader the skill is actually doing its job — what they should see when it fires, and by absence when it hasn't. Include it when a skill has crisp tells (e.g. `to-spec` writes without re-interviewing you; a leading word reappearing in the trace); omit the heading when the signals are vague. A few bullets, no more. +A few bullets naming what the reader sees when the skill is doing its job. The bar on each is that the reader can check it without opening `SKILL.md` — a signal in their own work, or in the trace in front of them. "The document gets shorter as it gets better" passes; "the library section is byte-identical to `template.sh`" is a compliance check on the skill's internals wearing this section's name. Include it wherever the tells are crisp; omit the heading where they stay vague. ## Where it fits @@ -68,4 +82,7 @@ Always present. Situate the skill in the system in a sentence or two: - `## Where it fits` names the role and links to `ask-matt`. - A prerequisite (workspace, prior setup, tooling) is stated where one exists, and the section is absent where none does. - The middle surfaces the leading word. +- Every `## Common questions` entry traces to a question someone asked — found in the wiki, the issues, or the changelog — and the heading is absent where the hunt found none. +- Every `## It's working if` bullet is checkable without opening `SKILL.md`. +- The sections appear in the template's order. - Every link is absolute, and every one resolves. diff --git a/.changeset/docs-page-four-section-spine.md b/.changeset/docs-page-four-section-spine.md new file mode 100644 index 0000000..d300772 --- /dev/null +++ b/.changeset/docs-page-four-section-spine.md @@ -0,0 +1,15 @@ +--- +"mattpocock-skills": patch +--- + +Make `Common questions` and `It's working if` part of the docs-page standard, and say where the questions come from. + +An audit of all 25 docs pages found the two sections that carry the most weight are the two the standard treated as optional. Only `grill-me` has a `Common questions` section; `writing-for-agents` gains one in #758. Twelve pages have no `It's working if` at all, and several that do use it for compliance checks on the skill's internals rather than for signals the reader can see. + +`.agents/writing-docs.md` now: + +- **Names the four-section spine** — `What it does`, `When to reach for it`, `Common questions`, `It's working if`. A page missing the last two is unfinished, not finished-and-short. The template's order is now the page's order. +- **Gates `Common questions` on evidence.** Every question has to be one someone asked, and three observed questions beat eight plausible ones. The hunt runs over three sources: the personal wiki at `~/repos/matt/personal-wiki` where it exists on the machine (its `wiki/audience/` area is organised around what the audience is confused by, with `sources:` linkbacks to the original threads), this repo's issues, and `CHANGELOG.md` for anything renamed or moved. +- **Raises the bar on `It's working if`** — each bullet must be checkable without opening `SKILL.md`. + +`CLAUDE.md` names the four sections in the pointer, so the spine is visible without reading `writing-docs.md` first. diff --git a/CLAUDE.md b/CLAUDE.md index b2f5c36..2dfb777 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,7 +14,7 @@ Each skill entry in the top-level `README.md` must link the skill name to its `S Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. The promoted buckets' `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**; non-promoted bucket `README.md`s (`misc/`, `in-progress/`) use a flat list. -Skills in `engineering/` and `productivity/` also have a human-facing docs page at `docs//.md` (the docs tree mirrors those two bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-` regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in `engineering/` or `productivity/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md). Skills in the non-promoted buckets (`misc/`, `in-progress/`, `deprecated/`) get **no** docs page. +Skills in `engineering/` and `productivity/` also have a human-facing docs page at `docs//.md` (the docs tree mirrors those two bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-` regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in `engineering/` or `productivity/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md). A finished page carries four sections — **What it does**, **When to reach for it**, **Common questions**, **It's working if** — and `writing-docs.md` holds the template, the section order, and where to hunt for the questions. Skills in the non-promoted buckets (`misc/`, `in-progress/`, `deprecated/`) get **no** docs page. Every `SKILL.md` is either user-invoked (`disable-model-invocation: true` plus `policy.allow_implicit_invocation: false` in `agents/openai.yaml`, reachable only by the human) or model-invoked (model- or user-reachable). See [.agents/invocation.md](./.agents/invocation.md).