Add documentation guidelines for skill pages and update CLAUDE.md references

Relocate this repo's ADRs and invocation.md from docs/ to .agents/,
and update the CLAUDE.md reference.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.agents/writing-docs.md

@@ -0,0 +1,57 @@
+# 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.
+
+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.
+
+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.
+
+## 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.
+
+<page-template>
+
+```bash
+npx skills add mattpocock/skills --skill=<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>
+
+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.
+
+## <Concept highlight>
+
+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.
+
+## How it fits the workflow
+
+```txt
+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.
+
+## Pairs well with
+
+- [<sibling>](https://aihero.dev/skills-<sibling>), because-clause saying what the pairing buys
+
+</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.
+- Use the skill's **leading words** (_seam_, _deep module_, _tracer bullet_) so the page and the skill speak one language.
+
+## Done when
+
+- The page exists at `docs/<name>.md`, and no stale page survives a rename.
+- The install command and source link name the correct bucket and skill.
+- The load-bearing constraint is stated in `## What it does`.
+- Every link is absolute, and every one resolves.

CLAUDE.md

@@ -13,6 +13,8 @@ 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 `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). For the full definitions, description conventions, and why a user-invoked skill can invoke model-invoked skills but never another user-invoked one, see [docs/invocation.md](./docs/invocation.md).
+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 `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).
 
 To (re)link every skill into the local harness skill directories (`~/.claude/skills`, `~/.agents/skills`), run `scripts/link-skills.sh`. Each entry is a symlink into this repo, so a `git pull` keeps installed skills current; re-run the script after adding, removing, or renaming a skill.

docs/to-prd.md

@@ -0,0 +1,47 @@
+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