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,4 +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

scripts/link-skills.sh

@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# NOTE: This is a dev-only script, intended for use by maintainers of this repo.
+# It is not a supported installer. Modifications to it — or requests for
+# modifications — will not be approved.
+#
 # Links all skills in the repository into the local skill directories used by
 # each agent harness:
 #   - ~/.claude/skills  — Claude Code

skills/in-progress/decision-mapping/SKILL.md

@@ -4,7 +4,7 @@ description: Turn a loose idea into a sequenced map of investigation tickets, th
 disable-model-invocation: true
 ---
 
-This skill is invoked when a loose idea requires more than one agent session to turn into a plan. It creates a stateful decision map in a markdown file, and drives the user through a sequence of tickets to resolve the open questions - which may require either prototyping, research or grilling.
+This skill is invoked when a loose idea requires more than one agent session to turn into a plan. It creates a stateful decision map in a markdown file, and drives the user through a sequence of tickets to resolve the open questions - which may require either prototyping, research or grilling. The map is domain-agnostic: it plans engineering work, course content, or anything else that fits the same shape.
 
 ## The Decision Map
 
@@ -47,9 +47,11 @@ Each ticket must be sized to one 100K token agent session.
 There are three types of tickets:
 
 - **Research**: Reading documentation, third-party API's, or local resources like knowledge bases. Creates a markdown summary as an asset. Use this when knowledge outside the current working directory is required.
-- **Prototype**: Writing UI or logic code to test a hypothesis, or to explore a design space. Uses the /prototype skill. Creates a prototype as an asset. Use this when "how should it look" or "how should it behave" is the key question.
+- **Prototype**: Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Creates the prototype as an asset. Use this when "how should it look" or "how should it behave" is the key question.
 - **Grilling**: Conversation with the agent. Uses the /grilling and /domain-modeling skills. Asks one question at a time. The default case.
 
+Validation isn't a fourth type — it's the thread running through all three.
+
 ## Fog of war
 
 The map is _deliberately_ incomplete beyond the frontier. Your job is to investigate the frontier, and to resolve tickets in order to push the frontier forward. Push back the fog of war, one node at a time — until the path to the finish line is clear and no tickets remain.
@@ -72,7 +74,7 @@ User invokes with a path to an existing map. A ticket slug is **optional** — w
 
 1. Load the **whole map** as context.
 2. Choose the ticket. If the user named one, use it. Otherwise pick the first `open` ticket in document order that is [unblocked](#structure). [Claim it](#structure): set `Status: in-progress` and save before any work.
-3. Resolve it, invoking skills as needed. If in doubt, use `/grilling` and `/domain-modeling`.
+3. Resolve it, invoking skills as needed — including any the `## Notes` block names. If in doubt, use `/grilling` and `/domain-modeling`.
 4. Record the answer in the ticket's body and set `Status: resolved`.
 5. Add newly-discovered tickets with correct `Blocked by` edges. If the decisions made invalidate other parts of the map, update or delete those nodes.
 6. Handoff.
@@ -101,3 +103,7 @@ End every session by clearing the context and opening one or more fresh sessions
 > ```
 
 **No open tickets remain.** The fog is pushed back far enough that the path to the finish line is clear — the map is done. (The initial grilling may also surface no fog at all, in which case there was never a map to build.) Recommend implementing directly, or using `/to-prd` to schedule a multi-session implementation.
+
+## Notes
+
+An optional block declaring the **domain**, any skills every session should `consult`, and freeform standing preferences the planning surfaces.