docs: rework the skill docs-page template

Reframe docs pages around cognitive-load relief: most skills are
user-invoked, so the human is the index that must remember when to
reach for each one. Each page's job is to make one skill memorable
and situate it in the system.

Template changes (.agents/writing-docs.md):
- Quickstart block: install + `npx skills update`, install-first
- New `## When to reach for it` (invocation mode + trigger boundary)
- New optional `## Prerequisites` (workspace/state, prior setup, tooling)
- Free-form middle with one firm rule: surface the leading word
  (also an observability signal in the agent's output)
- `## Where it fits`: role-based, absorbs "Pairs well with", links ask-matt
- No H1; every cross-link absolute

Nest docs under bucket folders (docs/<bucket>/<name>.md); the
published URL stays skills-<name> regardless. Re-sync to-prd as the
worked exemplar.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.agents/writing-docs.md

@@ -1,57 +1,77 @@
 # Writing docs pages
 
-Every promoted skill (`engineering/`, `productivity/`, `misc/`) has a human-facing **docs page** at `docs/<skill-name>.md`, published at `https://aihero.dev/skills-<skill-name>`. The page is not the skill and not a copy of `SKILL.md` — it is the explainer a human reads to decide whether to reach for the skill. Skills in `personal/`, `in-progress/`, and `deprecated/` get no page, mirroring the README rule.
+Every promoted skill (`engineering/`, `productivity/`, `misc/`) has a human-facing **docs page** at `docs/<bucket>/<skill-name>.md` — the docs tree mirrors the bucket folders under `skills/`. It is published at `https://aihero.dev/skills-<skill-name>`; the URL is always `skills-<skill-name>` regardless of bucket, so the docs path is repo organisation only. The page is not the skill and not a copy of `SKILL.md`.
 
-Act whenever a promoted skill is added, renamed, or has its behaviour changed: create or re-sync its docs page. A rename moves the file too (`docs/<old>.md` → `docs/<new>.md`), because the published URL tracks the name.
+Most of these skills are **user-invoked**: the agent will never fire them for you, so *you* are the index that has to remember they exist and when to reach for them. That memory is **cognitive load**. The job of a docs page is to relieve it — to orient one reader around one skill so they can hold it in their head, know when to reach for it, and see where it sits in the system. The pages are collectively a distributed router; each is a node.
+
+Act whenever a promoted skill is added, renamed, or has its behaviour changed: create or re-sync its docs page. A rename moves the file too (`docs/<bucket>/<old>.md` → `docs/<bucket>/<new>.md`), because the published URL tracks the name; a skill that moves buckets moves its docs file to the matching folder. Skills in `personal/`, `in-progress/`, and `deprecated/` get no page, mirroring the README rule.
 
 Because these pages are published on `aihero.dev`, **every link is absolute** — never a repo-relative path. A link to another skill points at `https://aihero.dev/skills-<name>`; a link into the repo points at its full `https://github.com/mattpocock/skills/...` URL. A relative link that works in the repo breaks once published.
 
+There is no H1 — the published page takes its title from the slug.
+
 ## Page structure
 
-Fill the template below. The **fixed frame** (install block, source link, `## What it does`) appears on every page. The **adaptable middle** carries only the sections this particular skill earns — delete the ones it doesn't.
+Fill the template below. The **fixed frame** (Quickstart block, source link, `## 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.
 
 <page-template>
 
+Quickstart:
+
 ```bash
 npx skills add mattpocock/skills --skill=<name>
 ```
 
+```bash
+npx skills update <name>
+```
+
 [Source](https://github.com/mattpocock/skills/tree/main/skills/<bucket>/<name>)
 
 ## What it does
 
 One or two plain-language paragraphs. Lead with the skill's one-sentence job, then state the **load-bearing constraint** — the single fact that makes this skill behave differently from the obvious default (for `to-prd`: it does not interview the user again, it synthesises what is already known). This line is the most valuable on the page; never omit it.
 
-## <Substance heading>
+## When to reach for it
 
-Unpack what the skill produces or how it moves — e.g. a list of the artifact's parts, or a description of the loop it runs. Use as many of these sections as the skill needs; omit if it needs none.
+How and when you reach for the skill — two beats, both effectively always present:
 
-## <Concept highlight>
+- **Invocation mode.** State whether you type it or the agent fires it. A user-invoked skill: "You invoke this by typing `/<name>` — the agent won't reach for it on its own." A model-invoked skill: "Type `/<name>`, or the agent reaches for it automatically when a task fits."
+- **Trigger boundary.** The index entry: "reach for this when …". Where the skill is confusable with a sibling, add the other half — "for <X> instead, use [<sibling>](https://aihero.dev/skills-<sibling>)."
 
-Name the one idea worth calling out, in the skill's own vocabulary, and say why it matters (`to-prd`'s `## Deep modules` explains what a deep module is and why it helps agentic testing). Omit if there is none.
+## Prerequisites
 
-## How it fits the workflow
+Optional — include only when the skill needs something in place to be functional; omit the heading entirely otherwise. Covers: a **workspace it writes into** (a stateful skill like `grill-with-docs` writes `CONTEXT.md` and ADRs; `teach` builds a whole directory — say what it writes and where), **prior setup** (`triage`/`to-prd`/`to-issues` need `setup-matt-pocock-skills` to have configured an issue tracker), or **repo-specific tooling**. A stateless skill that runs anywhere has no prerequisites — drop the section.
 
-```txt
+## <free-form middle>
-grill-with-docs → to-prd → to-issues → tdd
-```
 
-A sentence on where in that chain to reach for the skill. Include only when the skill belongs to a chain.
+One to three short sections, in the skill's *own vocabulary*, that make it click — choose whatever headings fit the skill: the loop it runs, the artifact it produces, the fork it makes, the one anti-pattern it kills. There is no prescribed heading; the skills are too heterogeneous for one.
 
-## Pairs well with
+The single non-negotiable: **surface the skill's leading word / load-bearing idea** — `tight` feedback loop, `deep module`, throwaway-code-answers-a-question, red-green. It pays off three ways: the reader learns what the skill *is*, learns the word they'll later think with to *reach for* it, and learns the word to *watch for in the agent's output* — if the leading words come out, the skill fired and is thinking in its own frame; if they don't, that's the tell something is off.
 
-- [<sibling>](https://aihero.dev/skills-<sibling>), because-clause saying what the pairing buys
+## Where it fits
+
+Always present. Situate the skill in the system in a sentence or two:
+
+- **Role.** Name it: a **chain step** (`grill-with-docs → to-prd → to-issues → tdd`), a **run-once setup** (`setup-matt-pocock-skills`), **periodic maintenance** (`improve-codebase-architecture`, "every few days"), or a **reach-for-it-anytime standalone** (`diagnosing-bugs`, `prototype`, `handoff`). A standalone's map is one honest sentence — far better than omitting the section.
+- **Neighbours.** The one or two siblings that matter, each with a because-clause, linked absolutely.
+- **The map.** Point to [ask-matt](https://aihero.dev/skills-ask-matt), the router over the whole set, so this page stays a node and never has to redraw the graph.
 
 </page-template>
 
 ## Conventions
 
-- Explain the **why**, not the process. The page sells and situates the skill; it never reproduces the `SKILL.md` steps or template dumps — a human choosing a tool does not need the runbook.
+- Explain the **why**, not the process. The page orients and situates the skill; it never reproduces the `SKILL.md` steps or template dumps — a human choosing a tool does not need the runbook.
 - Use the skill's **leading words** (_seam_, _deep module_, _tracer bullet_) so the page and the skill speak one language.
+- Keep the page itself low-load. It is documentation *about* low-cognitive-load skills; furniture (spare headings, restated links) is the thing it is arguing against.
 
 ## Done when
 
-- The page exists at `docs/<name>.md`, and no stale page survives a rename.
+- The page exists at `docs/<bucket>/<name>.md`, and no stale page survives a rename or bucket move.
-- The install command and source link name the correct bucket and skill.
+- The Quickstart block and source link name the correct bucket and skill; the update line names the skill.
-- The load-bearing constraint is stated in `## What it does`.
+- `## What it does` states the load-bearing constraint.
+- `## When to reach for it` states invocation mode and the trigger boundary.
+- `## 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 link is absolute, and every one resolves.

CLAUDE.md

@@ -13,7 +13,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`. Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**.
 
-Every promoted skill also has a human-facing docs page at `docs/<skill-name>.md`. When you add, rename, or change the behaviour of a skill in `engineering/`, `productivity/`, or `misc/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md).
+Every promoted skill also has a human-facing docs page at `docs/<bucket>/<skill-name>.md` (the docs tree mirrors the bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-<skill-name>` regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in `engineering/`, `productivity/`, or `misc/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md).
 
 Every `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). See [.agents/invocation.md](./.agents/invocation.md).
 

docs/engineering/to-prd.md

@@ -0,0 +1,53 @@
+Quickstart:
+
+```bash
+npx skills add mattpocock/skills --skill=to-prd
+```
+
+```bash
+npx skills update to-prd
+```
+
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-prd)
+
+## What it does
+
+`to-prd` turns the current conversation and your codebase understanding into a product requirements document, then publishes it to your issue tracker.
+
+The load-bearing constraint: it does **not** interview you again. By the time you reach for it, the alignment work is done — `to-prd` synthesises what is already known rather than asking a fresh round of questions.
+
+## When to reach for it
+
+You invoke this by typing `/to-prd` — the agent won't reach for it on its own.
+
+Reach for it once a change has been talked through and the domain language is settled, and you want that shared understanding written down as a spec before any code is written. If you *haven't* aligned yet, grill first — for that, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs). To split the finished PRD into tickets, use [to-issues](https://aihero.dev/skills-to-issues).
+
+## Prerequisites
+
+`to-prd` publishes into your issue tracker, so [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills) must have configured the tracker and triage labels for this repo first. It applies the `ready-for-agent` label itself — no separate triage pass needed.
+
+## What the PRD includes
+
+- problem statement
+- solution
+- extensive numbered user stories
+- implementation decisions
+- testing decisions
+- out-of-scope items
+- further notes
+
+## Deep modules
+
+Before writing the PRD, `to-prd` sketches the **seams** at which the feature will be tested and looks for **deep module** opportunities — a lot of functionality hidden behind a small, stable interface. It prefers existing seams to new ones and the highest seam possible, ideally just one across the whole change.
+
+That matters for agentic development: a good interface gives tests something durable to target, so the code underneath can change without the tests moving. If you see the words _seam_ and _deep module_ coming back at you as it works, the skill is doing its job.
+
+## Where it fits
+
+`to-prd` is a step in the main build chain:
+
+```txt
+grill-with-docs → to-prd → to-issues → tdd
+```
+
+Reach for it after the plan and domain language are resolved, and before you break the work into implementation tickets. Its key neighbours are [grill-with-docs](https://aihero.dev/skills-grill-with-docs), which sharpens the context so the PRD is precise, and [to-issues](https://aihero.dev/skills-to-issues), which turns the PRD into independently-grabbable issues for [tdd](https://aihero.dev/skills-tdd) to implement. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.

docs/to-prd.md

@@ -1,47 +0,0 @@
-Install this skill:
-
-```bash
-npx skills add mattpocock/skills --skill=to-prd
-```
-
-[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-prd)
-
-## What it does
-
-`to-prd` turns the current conversation context and codebase understanding into a product requirements document.
-
-The important constraint is that it does not interview the user again. It synthesizes what is already known.
-
-## What the PRD includes
-
-The generated PRD includes:
-
-- problem statement
-- solution
-- extensive numbered user stories
-- implementation decisions
-- testing decisions
-- out-of-scope items
-- further notes
-
-The skill also asks the agent to sketch the major modules that need to be built or modified.
-
-## Deep modules
-
-`to-prd` actively looks for deep module opportunities.
-
-A deep module hides meaningful complexity behind a small, stable, testable interface. That matters for agentic development because a good interface gives tests something durable to target.
-
-## How it fits the workflow
-
-```txt
-grill-with-docs → to-prd → to-issues → tdd
-```
-
-Use `to-prd` after the plan and domain language have been resolved. Then use `to-issues` to break the PRD into tracer-bullet implementation issues.
-
-## Pairs well with
-
-- [grill-with-docs](https://aihero.dev/skills-grill-with-docs), to make sure the context is precise before the PRD is written
-- [to-issues](https://aihero.dev/skills-to-issues), to turn the PRD into implementation tickets
-- [tdd](https://aihero.dev/skills-tdd), to implement the resulting issues one behavior at a time