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.

npx skills add mattpocock/skills --skill=<name>

Source

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.

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.

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

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

, because-clause saying what the pairing buys

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.

3.1 KiB Raw Blame History