57 lines
3.1 KiB
Markdown
57 lines
3.1 KiB
Markdown
# 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.
|