docs: drop the Quickstart block from all 25 pages

aihero.dev renders an install widget above every skill page. Each page
then repeated the same commands in its body, and the two copies had
drifted: the widget uses the current `npx skills@latest ...` wording
while the hand-written blocks mostly carried the older bare `npx skills
...`. Pages showed the right command and a stale one together.

Delete the block from all 25 pages and record the rule in
.agents/writing-docs.md: install wording belongs to the site, not the
page. The template no longer carries a Quickstart, and
.agents/install-block.md notes that docs pages are not one of its
consumers.
This commit is contained in:
Matt Pocock
2026-08-05 11:22:19 +01:00
parent c64fa7ecf6
commit 3314257466
28 changed files with 16 additions and 265 deletions
+3 -13
View File
@@ -12,22 +12,12 @@ There is no H1 — the published page takes its title from the slug.
## Page structure
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.
Fill the template below. The **fixed frame** (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.
Install commands are not written per page. Copy them verbatim from [the canonical install block](./install-block.md) — it is the single source for how anyone installs these skills, and a page that words it differently is a page that tells a second story. The Quickstart block in the template below is the older wording and does not yet match; the docs pass replaces it from the canonical block.
**A page carries no install commands.** The ai-hero page template renders the install widget itself — a copy button, the single-skill command, the whole-set command, and the update line — above the body. A page that also writes them out shows the reader the same command twice, and the two copies drift: the hand-written pair on every page went stale against the widget beside it. Install wording is a property of the site, not of the page. If it needs changing, change it in ai-hero; the canonical wording lives in [the install block](./install-block.md).
<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
@@ -74,7 +64,7 @@ Always present. Situate the skill in the system in a sentence or two:
## Done when
- The page exists at `docs/<bucket>/<name>.md`, and no stale page survives a rename or bucket move.
- The Quickstart block and source link name the correct bucket and skill; the update line names the skill.
- The source link names the correct bucket and skill, and the page writes no install command of its own.
- `## What it does` states the defining constraint, as plain prose rather than a labelled aside.
- `## When to reach for it` states invocation mode and the trigger boundary.
- `## Where it fits` names the role and links to `ask-matt`.