From 77d207ef03219cc603e2832e1159cbdd1c91818e Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 5 Aug 2026 13:07:04 +0100 Subject: [PATCH 1/2] chore: condense changesets and drop docs-only entries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removes the five docs-page-only changesets (quickstart drop, grill-me pass, four-section spine, rewrite-to-standard, writing-for-agents pass) — the changelog reports on the shipped skills, not on the site pages. Merges the clusters that describe one change each: ask-matt routing, the grilling round-by-round rework, prototype, wayfinder, wizard and writing-for-agents. 27 changesets become 15. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/ask-matt-phase-boundaries.md | 13 ------------ .changeset/ask-matt-router.md | 20 +++++++++++++++++++ .changeset/ask-matt-wayfinder-guidance.md | 10 ---------- .changeset/docs-drop-quickstart.md | 11 ---------- .changeset/docs-grill-me-pass.md | 17 ---------------- .changeset/docs-page-four-section-spine.md | 15 -------------- .changeset/docs-rewrite-to-standard.md | 7 ------- .changeset/docs-writing-for-agents-pass.md | 15 -------------- .changeset/graduate-wizard.md | 6 ++++-- .changeset/grilling-question-format.md | 5 ----- .changeset/grilling-round-by-round.md | 4 ++++ .changeset/grilling-rounds-docs-sync.md | 5 ----- .changeset/prototype-logic-shareable-html.md | 5 ----- .changeset/prototype-primary-source.md | 5 ----- .../prototype-shareable-primary-source.md | 9 +++++++++ ...wayfinder-decision-and-research-tickets.md | 9 +++++++++ .changeset/wayfinder-decision-tickets.md | 7 ------- .changeset/wayfinder-research-subagents.md | 7 ------- .changeset/wizard-model-invoked.md | 9 --------- .../writing-for-agents-environment-cache.md | 5 ----- .changeset/writing-for-agents-rename.md | 5 ----- .changeset/writing-for-agents.md | 9 +++++++++ 22 files changed, 55 insertions(+), 143 deletions(-) delete mode 100644 .changeset/ask-matt-phase-boundaries.md create mode 100644 .changeset/ask-matt-router.md delete mode 100644 .changeset/ask-matt-wayfinder-guidance.md delete mode 100644 .changeset/docs-drop-quickstart.md delete mode 100644 .changeset/docs-grill-me-pass.md delete mode 100644 .changeset/docs-page-four-section-spine.md delete mode 100644 .changeset/docs-rewrite-to-standard.md delete mode 100644 .changeset/docs-writing-for-agents-pass.md delete mode 100644 .changeset/grilling-question-format.md delete mode 100644 .changeset/grilling-rounds-docs-sync.md delete mode 100644 .changeset/prototype-logic-shareable-html.md delete mode 100644 .changeset/prototype-primary-source.md create mode 100644 .changeset/prototype-shareable-primary-source.md create mode 100644 .changeset/wayfinder-decision-and-research-tickets.md delete mode 100644 .changeset/wayfinder-decision-tickets.md delete mode 100644 .changeset/wayfinder-research-subagents.md delete mode 100644 .changeset/wizard-model-invoked.md delete mode 100644 .changeset/writing-for-agents-environment-cache.md delete mode 100644 .changeset/writing-for-agents-rename.md create mode 100644 .changeset/writing-for-agents.md diff --git a/.changeset/ask-matt-phase-boundaries.md b/.changeset/ask-matt-phase-boundaries.md deleted file mode 100644 index 3b7249e..0000000 --- a/.changeset/ask-matt-phase-boundaries.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Give `/ask-matt` the **phase boundary** decision tree, replacing the two-bullet `Crossing sessions` section. - -A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA — and the boundary between two of them is where you decide what to do with the context you've built. The router now carries all five options in order (**continue**, `/clear`, `/handoff`, **subagent**, `/compact`), with the ordered tree and its reasoning disclosed in a new `PHASE-BOUNDARIES.md`. Three fixes come with it: - -- **`/handoff` was oversold.** It read as the general bridge between context windows. It's narrow: you need it only when something has to *travel* — a new harness, a new directory, a colleague, or a side task forked mid-phase. What it buys is portability. -- **`/compact` is the default, not the first reach.** It sits at the bottom of the tree, after the four cheaper or more precise questions above it. Starting there produces a session that's confidently wrong about whatever the summary flattened. -- **Two branches were missing entirely.** **Continue** is the one to rule out first — it's the only move that keeps the conversation as a primary source rather than a summary of one — and a **subagent** handles anything scoped tightly enough to run AFK. - -Context hygiene's escape hatch now says `/compact` rather than `/handoff` (same harness, same directory, at a boundary — the handoff clause doesn't apply), and the smart zone figure is updated from ~120k to ~150k tokens. diff --git a/.changeset/ask-matt-router.md b/.changeset/ask-matt-router.md new file mode 100644 index 0000000..0b3c8b3 --- /dev/null +++ b/.changeset/ask-matt-router.md @@ -0,0 +1,20 @@ +--- +"mattpocock-skills": patch +--- + +Sharpen `/ask-matt` — the router now covers phase boundaries, the two wayfinder mistakes, and two skills it never mentioned. + +**Phase boundaries.** A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA — and the boundary between two of them is where you decide what to do with the context you've built. The two-bullet `Crossing sessions` section is replaced by a decision tree carrying all five options in order (**continue**, `/clear`, `/handoff`, **subagent**, `/compact`), with the reasoning disclosed in a new `PHASE-BOUNDARIES.md`. Three fixes come with it: + +- **`/handoff` was oversold.** It read as the general bridge between context windows. It's narrow: you need it only when something has to *travel* — a new harness, a new directory, a colleague, or a side task forked mid-phase. What it buys is portability. +- **`/compact` is the default, not the first reach.** It sits at the bottom of the tree, after the four cheaper or more precise questions above it. Starting there produces a session that's confidently wrong about whatever the summary flattened. +- **Two branches were missing entirely.** **Continue** is the one to rule out first — it's the only move that keeps the conversation as a primary source rather than a summary of one — and a **subagent** handles anything scoped tightly enough to run AFK. + +Context hygiene's escape hatch now says `/compact` rather than `/handoff` (same harness, same directory, at a boundary — the handoff clause doesn't apply), and the smart zone figure is updated from ~120k to ~150k tokens. + +**Wayfinder routing.** The two mistakes people most often make with the heaviest, most cognitively demanding flow: + +- **Over-reaching for it.** It's slower and denser than a single grill, so it's flagged as the heaviest flow and reserved for the idea that genuinely won't fit one session — a well-scoped feature belongs on `/grill-with-docs`, not here. +- **Losing the way at the handoff.** When the map clears, wayfinder hands off, it doesn't build: merge onto the main flow at `/to-spec` (which collapses the map's linked decisions into a buildable plan) rather than looping the map straight into `/implement`. Straight-to-`/implement` is only for efforts that turned out genuinely small. + +**Missing routes.** `/grilling` and `/resolving-merge-conflicts` were absent from the router altogether and are now in it, and `grill-me` splits from `grill-with-docs` on whether you are in a working directory. diff --git a/.changeset/ask-matt-wayfinder-guidance.md b/.changeset/ask-matt-wayfinder-guidance.md deleted file mode 100644 index 2a6b124..0000000 --- a/.changeset/ask-matt-wayfinder-guidance.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Make `/ask-matt` clued-up about `/wayfinder` — the heaviest, most cognitively demanding flow. - -The router now sharpens the two routing mistakes people most often make with wayfinder: - -- **Over-reaching for it.** It's slower and denser than a single grill, so it's flagged as the heaviest flow and reserved for the idea that genuinely won't fit one session — a well-scoped feature belongs on `/grill-with-docs`, not here. -- **Losing the way at the handoff.** When the map clears, wayfinder hands off, it doesn't build: merge onto the main flow at `/to-spec` (which collapses the map's linked decisions into a buildable plan) rather than looping the map straight into `/implement`. Straight-to-`/implement` is only for efforts that turned out genuinely small. diff --git a/.changeset/docs-drop-quickstart.md b/.changeset/docs-drop-quickstart.md deleted file mode 100644 index cbb1404..0000000 --- a/.changeset/docs-drop-quickstart.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -"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/.changeset/docs-grill-me-pass.md b/.changeset/docs-grill-me-pass.md deleted file mode 100644 index 57def85..0000000 --- a/.changeset/docs-grill-me-pass.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Rewrite the `grill-me` docs page around what people actually get wrong. - -The old page explained the mechanism — rounds, the frontier, the decision tree — and stopped there. Every recurring question from the last few months went unanswered on it: which of the three grilling skills to reach for, how many questions is normal, what to do when a question can't be answered by talking, and whether to start a fresh session before writing the spec. - -The rewrite keeps the mechanism short and spends the page on the judgement calls instead: - -- **Sibling routing** is now a three-way list keyed on what you have in front of you — no codebase, a codebase, or too big for one session — rather than a paragraph. -- **"It's a conversation, not an interview"** names passivity as the main failure mode. A session where you answer "agreed" forty times produces a plan you didn't write and can't defend. -- **"Grillable and ungrillable"** gives readers the move for a question that talking cannot settle: stop, prototype, come back. This is where long sessions come from. -- **A "Common questions" section** answers the six highest-volume ones directly, including how to restore one-question-at-a-time and why you should not clear context before `to-spec`. -- **"It's working if"** added, led by the sharpest signal: if you never disagreed, you didn't need the session. - -Also drops the "plan mode" ambiguity by saying plainly to leave it off. diff --git a/.changeset/docs-page-four-section-spine.md b/.changeset/docs-page-four-section-spine.md deleted file mode 100644 index d300772..0000000 --- a/.changeset/docs-page-four-section-spine.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Make `Common questions` and `It's working if` part of the docs-page standard, and say where the questions come from. - -An audit of all 25 docs pages found the two sections that carry the most weight are the two the standard treated as optional. Only `grill-me` has a `Common questions` section; `writing-for-agents` gains one in #758. Twelve pages have no `It's working if` at all, and several that do use it for compliance checks on the skill's internals rather than for signals the reader can see. - -`.agents/writing-docs.md` now: - -- **Names the four-section spine** — `What it does`, `When to reach for it`, `Common questions`, `It's working if`. A page missing the last two is unfinished, not finished-and-short. The template's order is now the page's order. -- **Gates `Common questions` on evidence.** Every question has to be one someone asked, and three observed questions beat eight plausible ones. The hunt runs over three sources: the personal wiki at `~/repos/matt/personal-wiki` where it exists on the machine (its `wiki/audience/` area is organised around what the audience is confused by, with `sources:` linkbacks to the original threads), this repo's issues, and `CHANGELOG.md` for anything renamed or moved. -- **Raises the bar on `It's working if`** — each bullet must be checkable without opening `SKILL.md`. - -`CLAUDE.md` names the four sections in the pointer, so the spine is visible without reading `writing-docs.md` first. diff --git a/.changeset/docs-rewrite-to-standard.md b/.changeset/docs-rewrite-to-standard.md deleted file mode 100644 index 0523b6a..0000000 --- a/.changeset/docs-rewrite-to-standard.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Rewrite every human-facing docs page to the four-section standard. Each page now states the skill's defining constraint, says when to reach for it and when to reach for something else, answers the questions people actually ask, and names what you see when it is working. The questions were found rather than invented — in the issue tracker, in the community threads, and in the changesets — so a well-discussed skill like `wayfinder` carries ten and a quiet one like `resolving-merge-conflicts` carries three. - -Writing them surfaced claims elsewhere that were no longer true. `tdd` now points at `/codebase-design` for interface vocabulary, which the v1.0 changelog said had already happened but which was never wired up. `ask-matt` gains `/grilling` and `/resolving-merge-conflicts`, both previously missing from the router altogether, and splits `grill-me` from `grill-with-docs` on whether you are in a working directory. The READMEs stop calling wayfinder's map one of investigation tickets, stop dropping the first phase from the `diagnosing-bugs` loop, and stop promising that `improve-codebase-architecture` will rescue a ball of mud when what it does is survey one. diff --git a/.changeset/docs-writing-for-agents-pass.md b/.changeset/docs-writing-for-agents-pass.md deleted file mode 100644 index d598a7a..0000000 --- a/.changeset/docs-writing-for-agents-pass.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Rewrite the `writing-for-agents` docs page around what people actually get wrong. - -The old page was a table of contents for the skill: the two loads, then a bullet per lever. It answered none of the questions the rename and the AMA threads have been generating for months — where `writing-great-skills` went, whether the agent or the human is doing the writing, why you shouldn't just ask Claude to write the skill for you, and how you know when a document is done. - -The rewrite keeps the levers to one compact list and spends the page on the judgement calls instead: - -- **The defining constraint is now stated up front** — the default move is deletion, not explanation, because the reader has already read everything. This is also the answer to "why not let the model write it", so it leads. -- **The scope is stated as a test**, not a list: does an agent read this document and act? Skills, `AGENTS.md`, specs, tickets and runtime prompts all pass it. -- **A "Common questions" section** answers the nine highest-volume ones directly, including the rename, the "streamline" failure where an agent trims for length and cuts behaviour, whether to rewrite documents per model, the skill that only works on the one task it was built from, and the leading-word question from non-native English speakers. -- **"It's working if"** added, led by the sharpest signal: the document gets shorter as it gets better, and duplication is the most reliable sign it was never tested. -- **`Where it fits`** says plainly that it has no chain neighbour: it sits underneath the set rather than beside one skill, and the documents the other skills leave behind are the text it governs. diff --git a/.changeset/graduate-wizard.md b/.changeset/graduate-wizard.md index c51bd3b..111203f 100644 --- a/.changeset/graduate-wizard.md +++ b/.changeset/graduate-wizard.md @@ -2,10 +2,12 @@ "mattpocock-skills": minor --- -Graduate **`wizard`** out of `in-progress/` into the **Engineering** bucket, so it ships in the plugin. It generates an interactive bash script that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening each URL, saying what to click, capturing the values, and writing them into `.env` files and GitHub Actions secrets. +Graduate **`wizard`** out of `in-progress/` into the **Engineering** bucket, so it ships in the plugin — and make it model-invoked. It generates an interactive bash script that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening each URL, saying what to click, capturing the values, and writing them into `.env` files and GitHub Actions secrets. The delightful UX is pre-solved by the bundled `template.sh` (progress with time-remaining, confirmation gates, cross-platform URL opening including WSL, hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes with graceful degradation, closing skip summary). Everything above the `STAGES` marker is a fixed library that's never hand-edited — the skill's job is only to scope the procedure and author its **stages**. Engineering rather than Productivity: it reads `.env*`, `docker-compose*`, framework config and every `secrets.*`/`vars.*` reference in `.github/workflows/` to scope itself, writes CI secrets, and verifies its output with `bash -n` and `shellcheck`. -Now wired as a promoted skill — plugin entry, top-level + Engineering READMEs under **Model-invoked**, a docs page at `docs/engineering/wizard.md`, and a Standalone route in `ask-matt` for the steps only a human can take. +Because it is model-invoked, the agent can reach for it the moment it hits a step only a human can perform, instead of dumping numbered instructions into the chat and hoping you follow them. Typing `/wizard` works exactly as before — model-invocation only ever *adds* the agent's reach. The description is written as the pointer that decides when it fires: what it produces, four trigger branches (provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, a one-off migration or cutover), and an explicit non-trigger — don't invoke it for steps the agent can perform itself. Work an agent can do, an agent should do; the wizard is for the clicks, approvals and dashboard trips you would not hand to one. The stage-list confirmation before a line is written now doubles as the proposal when the agent fires it mid-build. + +Now wired as a promoted skill — plugin entry, top-level + Engineering READMEs under **Model-invoked**, a docs page at `docs/engineering/wizard.md`, and a Standalone route in `ask-matt` for the steps only a human can take. Model-invocation also puts it out of the reach of [#693](https://github.com/mattpocock/skills/issues/693), which drops user-invoked skills from the listing on Claude's desktop and web surfaces. diff --git a/.changeset/grilling-question-format.md b/.changeset/grilling-question-format.md deleted file mode 100644 index 6101ce9..0000000 --- a/.changeset/grilling-question-format.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Pin the question format in **`grilling`**. Every question in a round is now emitted in one fixed shape — `❓ **Q1** - ****`, then the body (prose or multiple choices), then the recommendation on its own `➡️` line. A round reads as a scannable numbered list with each recommendation visually separated from the question, so you can answer by number instead of quoting questions back. diff --git a/.changeset/grilling-round-by-round.md b/.changeset/grilling-round-by-round.md index 2a57f17..5ea1249 100644 --- a/.changeset/grilling-round-by-round.md +++ b/.changeset/grilling-round-by-round.md @@ -3,3 +3,7 @@ --- Rework **`grilling`** from one-question-at-a-time to round-by-round. It now maps the decision tree and asks the whole **frontier** — every question whose prerequisites are already settled — in a single numbered round, then recomputes the frontier from the user's answers and asks the next round. Same 13 questions land in ~3 rounds instead of 13. Facts the environment can answer are dispatched to background sub-agents so research never blocks the round: only questions downstream of a running exploration wait for it. The session ends when the frontier is empty. + +Every question in a round is emitted in one fixed shape — `❓ **Q1** - **<title>**`, then the body (prose or multiple choices), then the recommendation on its own `➡️` line. A round reads as a scannable numbered list with each recommendation visually separated from the question, so you can answer by number instead of quoting questions back. + +`grill-me`, `grill-with-docs` and `triage` run the frontier a round at a time as well — `triage`'s grill step and `grilling`'s Codex `short_description` now say so instead of describing the old rhythm. The opt-out for one-question-at-a-time (a line in your global `CLAUDE.md`) is unchanged. diff --git a/.changeset/grilling-rounds-docs-sync.md b/.changeset/grilling-rounds-docs-sync.md deleted file mode 100644 index c914fa5..0000000 --- a/.changeset/grilling-rounds-docs-sync.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Sync the skills and docs that still described grilling as a **one-question-at-a-time** interview. Since the round-by-round rework, `grill-me`, `grill-with-docs` and `triage` all run the frontier a round at a time — their pages, `triage`'s grill step and `grilling`'s Codex `short_description` now say so. The opt-out for the old rhythm (a line in your global `CLAUDE.md`) is unchanged. diff --git a/.changeset/prototype-logic-shareable-html.md b/.changeset/prototype-logic-shareable-html.md deleted file mode 100644 index df8d197..0000000 --- a/.changeset/prototype-logic-shareable-html.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Reshape the **`prototype`** skill's logic branch to produce a **single shareable HTML file** instead of a terminal app. The demo is one self-contained file (plain HTML/CSS/JS, no build, no server) a non-developer can open by double-click and drive in their own domain language: a labelled state panel, always-available free-play buttons, and a set of tabbed **guided walkthroughs** — each a scenario with the ordered buttons to press underneath it. The portable pure-logic module still lifts into the real code; the HTML shell is the throwaway primary source. diff --git a/.changeset/prototype-primary-source.md b/.changeset/prototype-primary-source.md deleted file mode 100644 index 4e97b19..0000000 --- a/.changeset/prototype-primary-source.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Reword how the **`prototype`** skill handles its artifacts around a single idea: **the prototype is a primary source**. Rather than being deleted once it's answered its question, the prototype is captured as runnable evidence on a throwaway branch (`prototype/<name>`) out of main, with a context pointer to it left on the implementation issue — so the main branch keeps only the validated decision while the exploration stays findable. The answer (verdict + question) is still captured durably in an issue/ADR/commit. diff --git a/.changeset/prototype-shareable-primary-source.md b/.changeset/prototype-shareable-primary-source.md new file mode 100644 index 0000000..cf46856 --- /dev/null +++ b/.changeset/prototype-shareable-primary-source.md @@ -0,0 +1,9 @@ +--- +"mattpocock-skills": minor +--- + +Reshape the **`prototype`** skill around two ideas: the demo is **a single shareable HTML file**, and the prototype is **a primary source**. + +The logic branch now produces one self-contained file (plain HTML/CSS/JS, no build, no server) instead of a terminal app — a non-developer can open it by double-click and drive it in their own domain language: a labelled state panel, always-available free-play buttons, and a set of tabbed **guided walkthroughs**, each a scenario with the ordered buttons to press underneath it. The portable pure-logic module still lifts into the real code; the HTML shell is the throwaway. + +Throwaway no longer means deleted. Rather than being removed once it has answered its question, the prototype is captured as runnable evidence on a throwaway branch (`prototype/<name>`) out of main, with a context pointer to it left on the implementation issue — so the main branch keeps only the validated decision while the exploration stays findable. The answer (verdict + question) is still captured durably in an issue/ADR/commit. diff --git a/.changeset/wayfinder-decision-and-research-tickets.md b/.changeset/wayfinder-decision-and-research-tickets.md new file mode 100644 index 0000000..b36eac0 --- /dev/null +++ b/.changeset/wayfinder-decision-and-research-tickets.md @@ -0,0 +1,9 @@ +--- +"mattpocock-skills": minor +--- + +Name the `/wayfinder` unit a **decision ticket**, and burn research tickets down with subagents. + +People kept reading a wayfinder ticket as an ordinary *implementation* ticket — a slice of a build to execute — when wayfinder uses them as **decision tickets**: questions whose resolution is a decision. The skill description and its opening line now introduce the term (and say what makes it one), with the `ask-matt` / engineering README blurbs and the docs page matching — while "ticket" stays the everyday word once the term is established. `CONTEXT.md` records **Decision ticket** as a domain term, so the "avoid: ticket" guidance no longer contradicts wayfinder's deliberate use of the word. + +Research tickets are no longer parked for a separately-launched session. Research stays a real ticket type — it's a genuine shared blocker that downstream decisions hang on, and that dependency is exactly what the frontier's blocking edges exist to render. What changes is how it's resolved: because research is AFK, charting doesn't stop and read it. After creating the tickets, the charting session fires a `/research` subagent for each research ticket to burn it down in parallel, capturing the findings on a throwaway `research/<name>` branch with a context pointer. Research tickets are the one exception to *one ticket per session*. diff --git a/.changeset/wayfinder-decision-tickets.md b/.changeset/wayfinder-decision-tickets.md deleted file mode 100644 index a311c45..0000000 --- a/.changeset/wayfinder-decision-tickets.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Name the `/wayfinder` unit a **decision ticket**. - -People kept reading a wayfinder ticket as an ordinary *implementation* ticket — a slice of a build to execute — when wayfinder uses them as **decision tickets**: questions whose resolution is a decision. The skill description and its opening line now introduce "decision ticket" (and say what makes it one), and the `ask-matt` / engineering README wayfinder blurbs and the docs page match — while "ticket" stays the everyday word once the term is established. `CONTEXT.md` records **Decision ticket** as a domain term so the "avoid: ticket" guidance no longer contradicts wayfinder's deliberate use of the word. diff --git a/.changeset/wayfinder-research-subagents.md b/.changeset/wayfinder-research-subagents.md deleted file mode 100644 index dd7b2cd..0000000 --- a/.changeset/wayfinder-research-subagents.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Wayfinder now burns research tickets down with subagents instead of leaving them parked for a separately-launched session. - -Research stays a real ticket type — it's a genuine shared blocker that downstream decisions hang on, and that dependency is exactly what the frontier's blocking edges exist to render. What changes is how it's resolved: because research is AFK, charting doesn't stop and read it. After creating the tickets, the charting session fires a `/research` subagent for each research ticket to burn it down in parallel, capturing the findings on a throwaway `research/<name>` branch with a context pointer. Research tickets are the one exception to *one ticket per session*. diff --git a/.changeset/wizard-model-invoked.md b/.changeset/wizard-model-invoked.md deleted file mode 100644 index bef1d3f..0000000 --- a/.changeset/wizard-model-invoked.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Make **`wizard`** model-invoked. The agent can now reach for it the moment it hits a step only a human can perform, instead of dumping numbered instructions into the chat and hoping you follow them. Typing `/wizard` works exactly as before — model-invocation only ever *adds* the agent's reach. - -The description is rewritten as the pointer that decides when it fires: a short statement of what it produces, four trigger branches (provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, a one-off migration or cutover), and an explicit non-trigger — don't invoke it for steps the agent can perform itself. Work an agent can do, an agent should do; the wizard is for the clicks, approvals and dashboard trips you would not hand to one. - -Nothing else changed. Same name, same `template.sh`, same four process steps, same stage-list confirmation before a line is written — which now doubles as the proposal when the agent fires it mid-build. Also moved to **Model-invoked** in both READMEs, and out of the reach of [#693](https://github.com/mattpocock/skills/issues/693), which drops user-invoked skills from the listing on Claude's desktop and web surfaces. diff --git a/.changeset/writing-for-agents-environment-cache.md b/.changeset/writing-for-agents-environment-cache.md deleted file mode 100644 index fedfbc9..0000000 --- a/.changeset/writing-for-agents-environment-cache.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Extend **`writing-for-agents`**' pruning section with a new leading word: **cache**. Single source of truth now reaches past the document into the environment — `package.json` scripts, config files, directory layout, `--help` output are themselves authoritative, so a doc that restates them is a cache of a lookup, earning its load only when the lookup is expensive. The positive target: cache what the agent cannot find by looking (unwritten conventions, the reason behind a choice, gotchas no config confesses), and leave one-file, one-command lookups to the environment, where they cannot go stale. diff --git a/.changeset/writing-for-agents-rename.md b/.changeset/writing-for-agents-rename.md deleted file mode 100644 index e1f7b2f..0000000 --- a/.changeset/writing-for-agents-rename.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -**Breaking:** rename **`writing-great-skills`** → **`writing-for-agents`** and restructure it. The reference now covers any document an agent consumes — skills, `AGENTS.md` / `CLAUDE.md`, docs reached by a pointer — not just skills. `GLOSSARY.md` is merged into `SKILL.md` (one authoritative treatment per term; the `_Avoid_` synonym lists and the standalone Predictability definition are gone); the skill-only mechanics (frontmatter, model- vs user-invoked, router skills, the invocation cut of splitting) are disclosed to a new `SKILL-MECHANICS.md`. The skill is now **model-invoked**: it fires when creating or editing skills or modifying `AGENTS.md`/`CLAUDE.md`. `ask-matt`'s pointer updated. Reinstall under the new name; the old name is gone (no alias). diff --git a/.changeset/writing-for-agents.md b/.changeset/writing-for-agents.md new file mode 100644 index 0000000..6db29b4 --- /dev/null +++ b/.changeset/writing-for-agents.md @@ -0,0 +1,9 @@ +--- +"mattpocock-skills": minor +--- + +**Breaking:** rename **`writing-great-skills`** → **`writing-for-agents`**, restructure it, and add a new leading word. + +The reference now covers any document an agent consumes — skills, `AGENTS.md` / `CLAUDE.md`, docs reached by a pointer — not just skills. `GLOSSARY.md` is merged into `SKILL.md` (one authoritative treatment per term; the `_Avoid_` synonym lists and the standalone Predictability definition are gone); the skill-only mechanics (frontmatter, model- vs user-invoked, router skills, the invocation cut of splitting) are disclosed to a new `SKILL-MECHANICS.md`. The skill is now **model-invoked**: it fires when creating or editing skills or modifying `AGENTS.md`/`CLAUDE.md`. `ask-matt`'s pointer updated. Reinstall under the new name; the old name is gone (no alias). + +The pruning section gains **cache**. Single source of truth now reaches past the document into the environment — `package.json` scripts, config files, directory layout, `--help` output are themselves authoritative, so a doc that restates them is a cache of a lookup, earning its load only when the lookup is expensive. The positive target: cache what the agent cannot find by looking (unwritten conventions, the reason behind a choice, gotchas no config confesses), and leave one-file, one-command lookups to the environment, where they cannot go stale. From 394f48438919487dce7c26d43691899c8ac0ea69 Mon Sep 17 00:00:00 2001 From: Matt Pocock <mattpocockvoice@gmail.com> Date: Wed, 5 Aug 2026 13:10:09 +0100 Subject: [PATCH 2/2] docs: drop the human-in-the-loop lecture from the wizard page The intro spent a paragraph arguing when not to use the skill. Replace it with what the skill actually is: the agent writes the script, you run it. Cut the agent-browser question and the closing guard for the same reason, and plain up the densest sentences. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --- docs/engineering/wizard.md | 36 +++++++++++++++--------------------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/docs/engineering/wizard.md b/docs/engineering/wizard.md index 1c645c7..16f1aa6 100644 --- a/docs/engineering/wizard.md +++ b/docs/engineering/wizard.md @@ -2,34 +2,34 @@ `wizard` generates an interactive bash script that walks a human, step by step, through a manual procedure — wiring up third-party services, running a one-off migration, moving a project from state A to state B. It opens each URL, says what to click and copy, captures what comes back, and writes it into `.env` files and GitHub Actions secrets. -You reach for it only where a human is genuinely in the loop. If the agent could just do the step itself, it should do it, and a wizard for that step is a worse version of a tool call. Matt's reason for keeping the human there is provisioning: asked why an agent-browser doesn't do the whole setup unattended, his answer was "because it requires HITL to stop it provisioning stupid things." A wizard is for the clicks, approvals and dashboard trips you would not hand to an agent, packaged so you stop re-explaining them to one every time. +The agent writes the script; it never runs it. You do, on your own machine. So a wizard is not a list of instructions you follow — it is a program that drives the procedure and holds the state, and your part is to click, paste, and press Enter. ## When to reach for it -You can type `/wizard`, and the agent can also reach for it on its own. When it hits a step only you can perform — a key it can't mint, a dashboard it can't click — it builds you a wizard instead of writing the instructions into the chat, where they scroll away. +You can type `/wizard`, and the agent can also reach for it on its own. When it hits a step you have to take — a key it can't mint, a dashboard it can't click — it builds you a wizard instead of writing the instructions into the chat, where they scroll away. -Reach for it when the next thing blocking you is a human clicking through a dashboard: +Reach for it when the next thing blocking you is a trip through a dashboard: | Situation | What the wizard does | | --- | --- | | A new dev needs six services configured before the app boots | Opens each dashboard in order, captures the keys, writes them to `.env` and CI | | A one-off migration needs switches flipped in a specific order | Sequences the irreversible steps behind confirmation gates | | A project has to move from state A to state B once | Walks the transition and reports what it could not do | -| You are about to write those steps into a README | Writes an executable version instead, which cannot rot as quietly | +| You are about to write those steps into a README | Writes an executable version instead, which can't rot as quietly | -Don't reach for it when the procedure is scriptable end to end — that is a script, and the agent should write and run it. Don't reach for it to *decide* what to build; for that, [grill-with-docs](https://aihero.dev/skills-grill-with-docs) and [to-spec](https://aihero.dev/skills-to-spec) are the tools. +Don't reach for it to *decide* what to build; for that, [grill-with-docs](https://aihero.dev/skills-grill-with-docs) and [to-spec](https://aihero.dev/skills-to-spec) are the tools. ## Prerequisites -None to generate one. The wizard it writes runs on bash, and reaches for `gh` when a stage sets a GitHub secret or variable. If `gh` is missing or unauthenticated, that stage degrades to a warning and the closing summary tells the human what to set by hand, rather than failing the run. +None to generate one. The wizard it writes runs on bash, and uses `gh` when a stage sets a GitHub secret or variable. If `gh` is missing or unauthenticated, that stage becomes a warning and the closing summary tells you what to set by hand, instead of failing the run. ## Stages -A **stage** is the unit of authoring and the unit of attention: one focused task, one screen. The script clears the terminal between stages, so anything that doesn't fit the screen is anything the human loses. You author them in dependency order and set an honest `TOTAL_STAGES` and `TOTAL_MINUTES`, which is what drives the time-remaining display. That estimate is a promise to the person running it. +A **stage** is one focused task on one screen. The script clears the terminal between stages, so a stage that overflows the screen loses the part that scrolled away. You author stages in dependency order and set `TOTAL_STAGES` and `TOTAL_MINUTES`, which drive the time-remaining display — make the estimate honest, because the person running it will hold you to it. -Scoping happens before a line is written. The skill reads the repo rather than asking cold — `.env*`, `docker-compose*`, framework config, and every `secrets.*` / `vars.*` reference in `.github/workflows/`, each of which is a value the wizard must produce. Then it shows you the ordered stage list to confirm, and only then maps each stage to the precise path a human follows ("Dashboard → Developers → API keys → Reveal test key → copy"). Where it doesn't know the current UI, it asks or checks the docs; it doesn't invent clicks that may not exist. +Scoping happens before a line is written. The skill reads the repo instead of asking cold: `.env*`, `docker-compose*`, framework config, and every `secrets.*` / `vars.*` reference in `.github/workflows/` — each of those is a value the wizard has to produce. It then shows you the ordered stage list to confirm, and only after that maps each stage to the exact path a human follows ("Dashboard → Developers → API keys → Reveal test key → copy"). Where it doesn't know the current UI, it asks you or checks the docs rather than inventing clicks. -For each captured value, scoping has to settle where it lands: +For each captured value, scoping settles where it lands: | Destination | When | | --- | --- | @@ -39,11 +39,11 @@ For each captured value, scoping has to settle where it lands: | Both `.env` and a secret | Local dev and CI both need it | | Nowhere | The stage is a pure action — a switch flipped, a plan upgraded | -## The UX is not yours to design +## The template already solves the UX -A [template](https://github.com/mattpocock/skills/blob/main/skills/engineering/wizard/template.sh) already solves it: progress with time remaining, confirmation gates, cross-platform URL opening including WSL, hidden entry for secrets, idempotent `.env` upserts, `gh secret` / `gh variable` writes, and a closing summary of everything it had to skip. Everything above the `STAGES` marker is a fixed library, identical in every wizard, never hand-edited. The consistency is the point. Your job is only to scope the procedure and author its stages. +The [template](https://github.com/mattpocock/skills/blob/main/skills/engineering/wizard/template.sh) ships the whole experience: progress with time remaining, confirmation gates, cross-platform URL opening including WSL, hidden entry for secrets, idempotent `.env` upserts, `gh secret` / `gh variable` writes, and a closing summary of everything it had to skip. Everything above the `STAGES` marker is a fixed library, identical in every wizard and never hand-edited. The consistency is the point. Your job is only to scope the procedure and author its stages. -The agent that writes a wizard never runs it end to end — it opens browsers and blocks on human input. Verification is static instead: `bash -n`, `shellcheck` where available, and a trace that every value lands where scoping said it would, with every `set_secret` name matching a real `secrets.*` reference in CI. That is worth knowing because it sets your expectations honestly. The first person to run the wizard is you, and you are the test. +The agent that writes a wizard never runs it end to end, because it opens browsers and waits for human input. It verifies statically instead: `bash -n`, `shellcheck` where available, and a trace that every value lands where scoping said it would, with every `set_secret` name matching a real `secrets.*` reference in CI. Set your expectations accordingly — the first run is yours, and that run is the test. ## Ephemeral by default @@ -56,7 +56,7 @@ The agent that writes a wizard never runs it end to end — it opens browsers an **Do my API keys end up in the model's context?** -No. The agent writes a script; it doesn't run it. You run the script yourself, and it captures the key with hidden terminal entry and writes it straight to `.env` or `gh secret`. Matt's answer to this on launch day was "No, because it's a CLI — the LLM is not connected to it." The caveat worth stating: that holds for values the wizard captures at runtime. If you paste a key into the chat while scoping the procedure, it's in the context like any other pasted text. +No. The agent writes a script; it doesn't run it. You run the script yourself, and it captures the key with hidden terminal entry and writes it straight to `.env` or `gh secret`. Matt's answer to this on launch day was "No, because it's a CLI — the LLM is not connected to it." One caveat: that holds for values the wizard captures at runtime. If you paste a key into the chat while scoping the procedure, it's in the context like any other pasted text. **Can I go back and fix a value I mistyped?** @@ -68,13 +68,9 @@ There's a related open bug. Arrow keys in an `ask` prompt insert `^[[D` / `^[[C` Partly, and less than the launch reactions assumed. It reads the repo before it asks — your `.env` files, `docker-compose`, framework config, the `secrets.*` references in CI — so it scopes to values that are genuinely missing rather than starting from zero the way a README does. What it doesn't do is check the third-party service. If a key exists in your `.env` the wizard offers it back and Enter keeps it; if you already created the Stripe account but never saved the key, the wizard still sends you to the dashboard for it. -**Why not let an agent-browser do the whole setup automatically?** - -Because provisioning is where an unattended agent spends your money and creates things you didn't want. The human in the loop is the point of the skill, not a limitation of it. Where a step genuinely is safe to automate, the agent should do it directly and the wizard shouldn't carry it at all. - **Where does it sit in the workflow — after grilling and the spec?** -Nowhere in particular. It's a standalone, not a chain step. The common guess is `/grill-with-docs → /to-spec → /wizard`, and that sequence is fine, but the trigger is a human-only procedure showing up, which can happen at any point: before you start, mid-build, or long after ship. It also works as a discovery tool — scoping surfaces the hidden prerequisites of a task, like the three API keys you hadn't thought about, before you commit to the work. +Nowhere in particular. It's a standalone, not a chain step. The common guess is `/grill-with-docs → /to-spec → /wizard`, and that sequence is fine, but the trigger is a manual procedure showing up, which can happen at any point: before you start, mid-build, or long after ship. It also works as a discovery tool — scoping surfaces the hidden prerequisites of a task, like the three API keys you hadn't thought about, before you commit to the work. **Does it work outside Claude Code?** @@ -82,9 +78,7 @@ The artifact does, unconditionally: it's a plain bash script and it doesn't care **Didn't this used to be user-invoked?** -It did. It's now model-invoked, so the agent reaches for it unprompted when it hits a step only you can take. Nothing you could do before stopped working — model-invocation *adds* the agent's reach, it never removes yours, so `/wizard` behaves exactly as it did. What changed is the failure mode it retires: the agent hitting a credentials wall mid-build and dumping six numbered steps into the chat for you to follow by hand. - -The guard against the opposite failure is in the description itself — don't invoke it for steps the agent can perform itself. Work an agent can do, an agent should do. +It did. It's now model-invoked, so the agent reaches for it unprompted when it hits a step you have to take. Nothing you could do before stopped working — model-invocation *adds* the agent's reach, it never removes yours, so `/wizard` behaves exactly as it did. What changed is the failure mode it retires: the agent hitting a credentials wall mid-build and dumping six numbered steps into the chat for you to follow by hand. **It used to be in `in-progress/` — where is it now?**