From 33142574662bc87b3c3f3b3e6473e135ca7b5309 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 5 Aug 2026 11:22:19 +0100 Subject: [PATCH] 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. --- .agents/install-block.md | 4 ++-- .agents/writing-docs.md | 16 +++------------- .changeset/docs-drop-quickstart.md | 11 +++++++++++ docs/engineering/ask-matt.md | 10 ---------- docs/engineering/code-review.md | 10 ---------- docs/engineering/codebase-design.md | 10 ---------- docs/engineering/diagnosing-bugs.md | 10 ---------- docs/engineering/domain-modeling.md | 10 ---------- docs/engineering/grill-with-docs.md | 10 ---------- docs/engineering/implement.md | 10 ---------- .../engineering/improve-codebase-architecture.md | 10 ---------- docs/engineering/prototype.md | 10 ---------- docs/engineering/research.md | 10 ---------- docs/engineering/resolving-merge-conflicts.md | 10 ---------- docs/engineering/setup-matt-pocock-skills.md | 10 ---------- docs/engineering/tdd.md | 10 ---------- docs/engineering/to-spec.md | 10 ---------- docs/engineering/to-tickets.md | 10 ---------- docs/engineering/triage.md | 10 ---------- docs/engineering/wayfinder.md | 10 ---------- docs/engineering/wizard.md | 10 ---------- docs/productivity/grill-me.md | 10 ---------- docs/productivity/grilling.md | 10 ---------- docs/productivity/handoff.md | 10 ---------- docs/productivity/teach.md | 10 ---------- docs/productivity/to-questionnaire.md | 10 ---------- docs/productivity/wait-what.md | 10 ---------- docs/productivity/writing-for-agents.md | 10 ---------- 28 files changed, 16 insertions(+), 265 deletions(-) create mode 100644 .changeset/docs-drop-quickstart.md diff --git a/.agents/install-block.md b/.agents/install-block.md index 26f511e..8971bde 100644 --- a/.agents/install-block.md +++ b/.agents/install-block.md @@ -36,7 +36,7 @@ Pick the skills you want, and which coding agents to install them on. **The inst -…and the single-skill form on a `docs/` page, where the page already names one skill: +…and the single-skill form wherever one skill is named on its own. Note that **`docs/` pages are not a consumer of this block**: ai-hero renders the install widget above the body, so a page that writes the commands out duplicates it. See [writing-docs.md](./writing-docs.md). @@ -50,7 +50,7 @@ npx skills@latest update -`skills@latest` is the pinned spelling in all three. The Quickstart template in [writing-docs.md](./writing-docs.md), and the 24 pages under `docs/`, still carry the older bare `npx skills …`; the docs pass brings them into line. +`skills@latest` is the pinned spelling in all three. The pages under `docs/` used to carry their own copy of these commands; those blocks are now deleted rather than corrected, because the site renders the install commands itself. ## The two routes are exclusive diff --git a/.agents/writing-docs.md b/.agents/writing-docs.md index 6b81791..fd0a8e1 100644 --- a/.agents/writing-docs.md +++ b/.agents/writing-docs.md @@ -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). -Quickstart: - -```bash -npx skills add mattpocock/skills --skill= -``` - -```bash -npx skills update -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills//) ## 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//.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`. diff --git a/.changeset/docs-drop-quickstart.md b/.changeset/docs-drop-quickstart.md new file mode 100644 index 0000000..cbb1404 --- /dev/null +++ b/.changeset/docs-drop-quickstart.md @@ -0,0 +1,11 @@ +--- +"mattpocock-skills": patch +--- + +Drop the hand-written Quickstart block from all 25 docs pages. + +aihero.dev already renders an install widget above every skill page — a copy button, the single-skill command, the whole-set command, and the update line. Each page then wrote the same two commands out again immediately below it. The reader saw the install command twice. + +The two copies had also drifted apart. The widget renders the current `npx skills@latest …` wording; the hand-written blocks still carried the older bare `npx skills …`, so most pages showed the correct command and a stale one, one after the other. + +Deleting the block removes those stale copies and leaves the site's own. `.agents/writing-docs.md` now states the rule directly — install wording is a property of the site, not of the page — and its template no longer carries a Quickstart to copy. diff --git a/docs/engineering/ask-matt.md b/docs/engineering/ask-matt.md index 6fa0c66..3974d06 100644 --- a/docs/engineering/ask-matt.md +++ b/docs/engineering/ask-matt.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=ask-matt -``` - -```bash -npx skills update ask-matt -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/ask-matt) ## What it does diff --git a/docs/engineering/code-review.md b/docs/engineering/code-review.md index ac48f2b..28e463a 100644 --- a/docs/engineering/code-review.md +++ b/docs/engineering/code-review.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=code-review -``` - -```bash -npx skills update code-review -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/code-review) ## What it does diff --git a/docs/engineering/codebase-design.md b/docs/engineering/codebase-design.md index 2240e74..1405d32 100644 --- a/docs/engineering/codebase-design.md +++ b/docs/engineering/codebase-design.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=codebase-design -``` - -```bash -npx skills update codebase-design -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design) ## What it does diff --git a/docs/engineering/diagnosing-bugs.md b/docs/engineering/diagnosing-bugs.md index a4f5ca4..b8f6fd8 100644 --- a/docs/engineering/diagnosing-bugs.md +++ b/docs/engineering/diagnosing-bugs.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=diagnosing-bugs -``` - -```bash -npx skills update diagnosing-bugs -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnosing-bugs) ## What it does diff --git a/docs/engineering/domain-modeling.md b/docs/engineering/domain-modeling.md index 273cfde..8a27e03 100644 --- a/docs/engineering/domain-modeling.md +++ b/docs/engineering/domain-modeling.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=domain-modeling -``` - -```bash -npx skills update domain-modeling -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/domain-modeling) ## What it does diff --git a/docs/engineering/grill-with-docs.md b/docs/engineering/grill-with-docs.md index b7cfd75..e2cb815 100644 --- a/docs/engineering/grill-with-docs.md +++ b/docs/engineering/grill-with-docs.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=grill-with-docs -``` - -```bash -npx skills update grill-with-docs -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs) ## What it does diff --git a/docs/engineering/implement.md b/docs/engineering/implement.md index e079af8..2862785 100644 --- a/docs/engineering/implement.md +++ b/docs/engineering/implement.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=implement -``` - -```bash -npx skills update implement -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/implement) ## What it does diff --git a/docs/engineering/improve-codebase-architecture.md b/docs/engineering/improve-codebase-architecture.md index f8a9150..7e97d7d 100644 --- a/docs/engineering/improve-codebase-architecture.md +++ b/docs/engineering/improve-codebase-architecture.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=improve-codebase-architecture -``` - -```bash -npx skills update improve-codebase-architecture -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture) ## What it does diff --git a/docs/engineering/prototype.md b/docs/engineering/prototype.md index e8cdf6a..dbb3801 100644 --- a/docs/engineering/prototype.md +++ b/docs/engineering/prototype.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=prototype -``` - -```bash -npx skills update prototype -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/prototype) ## What it does diff --git a/docs/engineering/research.md b/docs/engineering/research.md index 5254b41..908bacf 100644 --- a/docs/engineering/research.md +++ b/docs/engineering/research.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=research -``` - -```bash -npx skills update research -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/research) ## What it does diff --git a/docs/engineering/resolving-merge-conflicts.md b/docs/engineering/resolving-merge-conflicts.md index 463dea8..c518fd8 100644 --- a/docs/engineering/resolving-merge-conflicts.md +++ b/docs/engineering/resolving-merge-conflicts.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=resolving-merge-conflicts -``` - -```bash -npx skills update resolving-merge-conflicts -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/resolving-merge-conflicts) ## What it does diff --git a/docs/engineering/setup-matt-pocock-skills.md b/docs/engineering/setup-matt-pocock-skills.md index 003b8b6..d026673 100644 --- a/docs/engineering/setup-matt-pocock-skills.md +++ b/docs/engineering/setup-matt-pocock-skills.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=setup-matt-pocock-skills -``` - -```bash -npx skills update setup-matt-pocock-skills -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/setup-matt-pocock-skills) ## What it does diff --git a/docs/engineering/tdd.md b/docs/engineering/tdd.md index 46b636e..d90a0ef 100644 --- a/docs/engineering/tdd.md +++ b/docs/engineering/tdd.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=tdd -``` - -```bash -npx skills update tdd -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/tdd) ## What it does diff --git a/docs/engineering/to-spec.md b/docs/engineering/to-spec.md index 1f9b23f..7758c89 100644 --- a/docs/engineering/to-spec.md +++ b/docs/engineering/to-spec.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=to-spec -``` - -```bash -npx skills update to-spec -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-spec) ## What it does diff --git a/docs/engineering/to-tickets.md b/docs/engineering/to-tickets.md index 1e4dca7..9c21502 100644 --- a/docs/engineering/to-tickets.md +++ b/docs/engineering/to-tickets.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=to-tickets -``` - -```bash -npx skills update to-tickets -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-tickets) ## What it does diff --git a/docs/engineering/triage.md b/docs/engineering/triage.md index 5ef6dfa..18e9e9c 100644 --- a/docs/engineering/triage.md +++ b/docs/engineering/triage.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=triage -``` - -```bash -npx skills update triage -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/triage) ## What it does diff --git a/docs/engineering/wayfinder.md b/docs/engineering/wayfinder.md index 5ececb1..b7137c2 100644 --- a/docs/engineering/wayfinder.md +++ b/docs/engineering/wayfinder.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=wayfinder -``` - -```bash -npx skills update wayfinder -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/wayfinder) ## What it does diff --git a/docs/engineering/wizard.md b/docs/engineering/wizard.md index 24a33e4..c1f9413 100644 --- a/docs/engineering/wizard.md +++ b/docs/engineering/wizard.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=wizard -``` - -```bash -npx skills update wizard -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/wizard) ## What it does diff --git a/docs/productivity/grill-me.md b/docs/productivity/grill-me.md index abe214c..c6e87ec 100644 --- a/docs/productivity/grill-me.md +++ b/docs/productivity/grill-me.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=grill-me -``` - -```bash -npx skills update grill-me -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me) ## What it does diff --git a/docs/productivity/grilling.md b/docs/productivity/grilling.md index efb2d15..d7bd5e2 100644 --- a/docs/productivity/grilling.md +++ b/docs/productivity/grilling.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=grilling -``` - -```bash -npx skills update grilling -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling) ## What it does diff --git a/docs/productivity/handoff.md b/docs/productivity/handoff.md index 25901a0..3e38066 100644 --- a/docs/productivity/handoff.md +++ b/docs/productivity/handoff.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=handoff -``` - -```bash -npx skills update handoff -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff) ## What it does diff --git a/docs/productivity/teach.md b/docs/productivity/teach.md index 9fd2b96..dffccde 100644 --- a/docs/productivity/teach.md +++ b/docs/productivity/teach.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=teach -``` - -```bash -npx skills update teach -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/teach) ## What it does diff --git a/docs/productivity/to-questionnaire.md b/docs/productivity/to-questionnaire.md index 2bd8def..de89c61 100644 --- a/docs/productivity/to-questionnaire.md +++ b/docs/productivity/to-questionnaire.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=to-questionnaire -``` - -```bash -npx skills update to-questionnaire -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/to-questionnaire) ## What it does diff --git a/docs/productivity/wait-what.md b/docs/productivity/wait-what.md index 9dfb863..22e9cff 100644 --- a/docs/productivity/wait-what.md +++ b/docs/productivity/wait-what.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills@latest add mattpocock/skills --skill=wait-what -``` - -```bash -npx skills@latest update wait-what -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/wait-what) ## What it does diff --git a/docs/productivity/writing-for-agents.md b/docs/productivity/writing-for-agents.md index b338109..dda4208 100644 --- a/docs/productivity/writing-for-agents.md +++ b/docs/productivity/writing-for-agents.md @@ -1,13 +1,3 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=writing-for-agents -``` - -```bash -npx skills update writing-for-agents -``` - [Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/writing-for-agents) ## What it does