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/adr/0002-ship-as-a-claude-code-plugin.md

@@ -26,3 +26,16 @@ The only robust ways to give Codex a single promoted-only path are (a) **restruc
 
 - Every promoted skill has an entry in `.claude-plugin/plugin.json`'s `skills` array (this already stood as a `CLAUDE.md` rule; it now also gates the plugin's contents).
 - `.claude-plugin/plugin.json`'s `version` tracks `package.json`'s version — bump both together on release. Claude uses the plugin `version` to decide when installed users see an update.
+
+## Update, 2026-08-05
+
+`mattpocock-skills` was accepted into **Claude Code's official marketplace** — configured name `claude-plugins-official`, source repo `anthropics/claude-plugins-official` — which every Claude Code install has by default. `claude plugins install mattpocock-skills` is now the documented route, and the `marketplace add` → `install` path above is superseded. The install wording lives in [.agents/install-block.md](../install-block.md).
+
+The official listing points at this repo's git URL and reads `.claude-plugin/plugin.json` directly, so it does not depend on `.claude-plugin/marketplace.json`. That file is retained only as a fallback for installing the repo directly (an unreleased commit, or a fork).
+
+Verified 2026-08-05, on Claude Code 2.1.222, against the live listing:
+
+- `claude plugins install mattpocock-skills` resolves with no marketplace added first, and reports `mattpocock-skills@claude-plugins-official`.
+- `claude plugin details mattpocock-skills` then reports version 1.2.0 and loads the promoted skills.
+- The listing's `source` is `{"source": "url", "url": "https://github.com/mattpocock/skills.git", "sha": …}` — the **sha is pinned**, so a release reaches installed users when that pin moves, not the moment we tag. At the time of writing the pin sits two commits behind `main`, which is why it lists 22 skills rather than the 24 in `plugin.json`.
+- The in-session `/plugin install mattpocock-skills` was **not** exercised — `/plugin` is unavailable in headless (`claude -p`) sessions. It runs the same resolver as the CLI, and the documented example form is `/plugin install <name>@claude-plugins-official`.

.agents/install-block.md

@@ -0,0 +1,61 @@
+# The canonical install block
+
+One install story, one wording. `README.md`, `.changeset/*`, and every page under `docs/` must say **this** and nothing else. Change it here first, then propagate.
+
+`mattpocock-skills` is listed in **Claude Code's official marketplace** — configured name `claude-plugins-official`, source repo `anthropics/claude-plugins-official` — which every Claude Code install has out of the box. There is no marketplace to add first. Official Anthropic marketplaces have auto-update enabled by default ([discover-plugins](https://code.claude.com/docs/en/discover-plugins)), so "updates arrive automatically" is a true claim, not a hope.
+
+## Claude Code — the plugin
+
+<canonical-block name="claude-code">
+
+```bash
+claude plugins install mattpocock-skills
+```
+
+Or, from inside a session:
+
+```
+/plugin install mattpocock-skills
+```
+
+It's in Claude Code's official marketplace, so there's nothing to add first, and updates arrive automatically.
+
+</canonical-block>
+
+## Codex, and other agents — skills.sh
+
+The plugin is Claude Code only. Everywhere else, [skills.sh](https://skills.sh/mattpocock/skills) copies editable skill files into the project. Use the whole-set form on `README.md`:
+
+<canonical-block name="skills-sh-whole-set">
+
+```bash
+npx skills@latest add mattpocock/skills
+```
+
+Pick the skills you want, and which coding agents to install them on. **The installer lets you choose which skills to take — make sure `setup-matt-pocock-skills` is one of them.**
+
+</canonical-block>
+
+…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).
+
+<canonical-block name="skills-sh-one-skill">
+
+```bash
+npx skills@latest add mattpocock/skills --skill=<name>
+```
+
+```bash
+npx skills@latest update <name>
+```
+
+</canonical-block>
+
+`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
+
+The plugin is a managed, read-only bundle you subscribe to. skills.sh writes files you own and edit. Installing both leaves the user with every skill twice — always say "pick one".
+
+## Not the install story
+
+`.claude-plugin/marketplace.json` makes the repo its own single-plugin marketplace (`/plugin marketplace add mattpocock/skills`, then `/plugin install mattpocock-skills@mattpocock`). The official listing supersedes it. It is kept as a fallback for installing the repo directly — an unreleased commit, or a fork — and is **not** documented to users.

.agents/writing-docs.md

@@ -1,10 +1,10 @@
 # Writing docs pages
 
-Every skill in `engineering/` and `productivity/` has a human-facing **docs page** at `docs/<bucket>/<skill-name>.md` — the docs tree mirrors those two bucket folders under `skills/`. It is published at `https://aihero.dev/skills-<skill-name>`; the URL is always `skills-<skill-name>` regardless of bucket, so the docs path is repo organisation only. The page is not the skill and not a copy of `SKILL.md`. Only these two buckets are promoted; the rest (`misc/`, `personal/`, `in-progress/`, `deprecated/`) ship no docs page.
+Every skill in `engineering/` and `productivity/` has a human-facing **docs page** at `docs/<bucket>/<skill-name>.md` — the docs tree mirrors those two bucket folders under `skills/`. It is published at `https://aihero.dev/skills-<skill-name>`; the URL is always `skills-<skill-name>` regardless of bucket, so the docs path is repo organisation only. The page is not the skill and not a copy of `SKILL.md`. Only these two buckets are promoted; the rest (`misc/`, `in-progress/`, `deprecated/`) ship no docs page.
 
 Most of these skills are **user-invoked**: the agent will never fire them for you, so *you* are the index that has to remember they exist and when to reach for them. That memory is **cognitive load**. The job of a docs page is to relieve it — to orient one reader around one skill so they can hold it in their head, know when to reach for it, and see where it sits in the system. The pages are collectively a distributed router; each is a node.
 
-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/<bucket>/<old>.md` → `docs/<bucket>/<new>.md`), because the published URL tracks the name; a skill that moves between `engineering/` and `productivity/` moves its docs file to the matching folder. Skills in `misc/`, `personal/`, `in-progress/`, and `deprecated/` get no page — none of those buckets is promoted. A skill moving *out* of one of them into `engineering/` or `productivity/` gains a page; one moving the other way loses it.
+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/<bucket>/<old>.md` → `docs/<bucket>/<new>.md`), because the published URL tracks the name; a skill that moves between `engineering/` and `productivity/` moves its docs file to the matching folder. Skills in `misc/`, `in-progress/`, and `deprecated/` get no page — none of those buckets is promoted. A skill moving *out* of one of them into `engineering/` or `productivity/` gains a page; one moving the other way loses it.
 
 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.
 
@@ -12,20 +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.
+
+**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
@@ -72,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`.

.changeset/ask-matt-phase-boundaries.md

@@ -0,0 +1,13 @@
+---
+"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.

.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.

.changeset/graduate-wizard.md

@@ -0,0 +1,11 @@
+---
+"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.
+
+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 **User-invoked**, a docs page at `docs/engineering/wizard.md`, and a Standalone route in `ask-matt` for the steps only a human can take.

.changeset/remove-deprecated-and-personal.md

@@ -0,0 +1,19 @@
+---
+"mattpocock-skills": patch
+---
+
+Remove six skills from the repo. None of them was in the Claude Code plugin, but all six were installable through [skills.sh](https://skills.sh/mattpocock/skills), which serves every skill in the repo — so this is what leaves that listing, and where each one went.
+
+Four retired skills, each already absorbed by a skill that does the job better:
+
+- **`ubiquitous-language`** → **`/domain-modeling`**, which builds and maintains the whole domain model rather than dumping a glossary from one conversation.
+- **`design-an-interface`** → **`/codebase-design`**. Nothing is lost: the "design it twice" technique — parallel sub-agents generating radically different designs, from Ousterhout — ships inside that skill as `DESIGN-IT-TWICE.md`.
+- **`qa`** → **`/triage`** and **`/to-tickets`**.
+- **`request-refactor-plan`** → **`/to-spec`** and **`/improve-codebase-architecture`**.
+
+And two that were only ever mine — tied to my own machine and never meant for anyone else. The `personal/` bucket goes with them:
+
+- **`edit-article`**
+- **`obsidian-vault`**, which hardcoded a path to my own Obsidian vault.
+
+`skills/deprecated/` stays as a bucket, now empty. `skills/in-progress/` is unchanged and is now described for what it actually is: a beta channel, published on purpose, installable one skill at a time through skills.sh.

.changeset/ship-as-claude-plugin.md

@@ -2,11 +2,18 @@
 "mattpocock-skills": minor
 ---
 
-Ship the skill set as a native **Claude Code plugin**. The repo is now its own single-plugin marketplace, so you can subscribe to the promoted skills as a managed, read-only bundle instead of copying editable files:
+Ship the skill set as a native **Claude Code plugin**, listed in Claude Code's official marketplace. You can now subscribe to the promoted skills as a managed, read-only bundle instead of copying editable files:
 
-```
+```bash
-/plugin marketplace add mattpocock/skills
+claude plugins install mattpocock-skills
-/plugin install mattpocock-skills@mattpocock
 ```
 
-`.claude-plugin/plugin.json` gains full marketplace metadata (version, description, author, license, keywords) and a sibling `.claude-plugin/marketplace.json` lists the plugin. `skills.sh` remains the universal installer (and the path for Codex and other harnesses today); a native Codex plugin is deferred — see `.agents/adr/0002-ship-as-a-claude-code-plugin.md` for why.
+Or, from inside a session:
+
+```
+/plugin install mattpocock-skills
+```
+
+There is no marketplace to add first — the official marketplace is configured by default.
+
+`.claude-plugin/plugin.json` carries the full plugin metadata (version, description, author, license, keywords) and the explicit list of promoted skills. `skills.sh` remains the universal installer (and the path for Codex and other harnesses today); a native Codex plugin is deferred — see `.agents/adr/0002-ship-as-a-claude-code-plugin.md` for why.

.changeset/wait-what.md

@@ -0,0 +1,9 @@
+---
+"mattpocock-skills": minor
+---
+
+Add **`wait-what`** — a fire extinguisher for model verbosity. Fire it the moment a message doesn't land, and the agent re-pitches it: a little context, ASD-STE100 Simplified Technical English, and the ubiquitous language from your `CONTEXT.md`. User-invoked, three lines long.
+
+The mechanism is the name. Concision skills fail by growing — a 400-line skill still leaves the model verbose — so this one is a single precise leading word and nothing else. Names that describe the *output* (`/tldr`, `/no-fluff`) make the model clip words and lose you further; naming the *listener's* state asks for both halves at once, fewer words **and** the context you were missing. It also reuses the leading words already in your global `CLAUDE.md`, so the skill, `CLAUDE.md` and every `CONTEXT.md` reach for the same tokens.
+
+It's the extinguisher, not the sprinkler. The cure for jargon is a shared language built upfront with `/grill-with-docs`; this is the in-the-moment corrective for when you don't have one yet.

.claude-plugin/plugin.json

@@ -36,11 +36,13 @@
     "./skills/engineering/codebase-design",
     "./skills/engineering/code-review",
     "./skills/engineering/resolving-merge-conflicts",
+    "./skills/engineering/wizard",
     "./skills/productivity/grill-me",
     "./skills/productivity/grilling",
     "./skills/productivity/handoff",
     "./skills/productivity/teach",
     "./skills/productivity/to-questionnaire",
+    "./skills/productivity/wait-what",
     "./skills/productivity/writing-for-agents"
   ]
 }

CLAUDE.md

@@ -3,19 +3,18 @@ Skills are organized into bucket folders under `skills/`:
 - `engineering/` — daily code work
 - `productivity/` — daily non-code workflow tools
 - `misc/` — kept around but rarely used, not promoted
-- `personal/` — tied to my own setup, not promoted
+- `in-progress/` — beta: public on purpose, feedback wanted, not shipped in the plugin
-- `in-progress/` — drafts not yet ready to ship
 - `deprecated/` — no longer used
 
-Every skill in `engineering/` or `productivity/` (the **promoted** buckets) must have a reference in the top-level `README.md` and an entry in `.claude-plugin/plugin.json`'s `skills` array (the Claude Code plugin ships exactly the promoted set). Skills in `misc/`, `personal/`, `in-progress/`, and `deprecated/` must not appear in either.
+Every skill in `engineering/` or `productivity/` (the **promoted** buckets) must have a reference in the top-level `README.md` and an entry in `.claude-plugin/plugin.json`'s `skills` array (the Claude Code plugin ships exactly the promoted set). Skills in `misc/`, `in-progress/`, and `deprecated/` must not appear in either.
 
-The repo is also its own single-plugin Claude Code marketplace: `.claude-plugin/marketplace.json` lists the one `mattpocock-skills` plugin. When bumping the release version, keep `.claude-plugin/plugin.json`'s `version` in sync with `package.json`'s — Claude uses the plugin `version` to decide when installed users see an update. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md).
+Install commands are copied verbatim from [.agents/install-block.md](./.agents/install-block.md). `.claude-plugin/marketplace.json` makes the repo its own single-plugin marketplace — a fallback the install block explains, not the documented route. When bumping the release version, keep `.claude-plugin/plugin.json`'s `version` in sync with `package.json`'s — Claude uses the plugin `version` to decide when installed users see an update. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md).
 
 Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`.
 
-Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. The promoted buckets' `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**; non-promoted bucket `README.md`s (`misc/`, `personal/`) use a flat list.
+Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. The promoted buckets' `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**; non-promoted bucket `README.md`s (`misc/`, `in-progress/`) use a flat list.
 
-Skills in `engineering/` and `productivity/` also have a human-facing docs page at `docs/<bucket>/<skill-name>.md` (the docs tree mirrors those two bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-<skill-name>` regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in `engineering/` or `productivity/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md). Skills in the non-promoted buckets (`misc/`, `personal/`, `in-progress/`, `deprecated/`) get **no** docs page.
+Skills in `engineering/` and `productivity/` also have a human-facing docs page at `docs/<bucket>/<skill-name>.md` (the docs tree mirrors those two bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-<skill-name>` regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in `engineering/` or `productivity/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md). Skills in the non-promoted buckets (`misc/`, `in-progress/`, `deprecated/`) get **no** docs page.
 
 Every `SKILL.md` is either user-invoked (`disable-model-invocation: true` plus `policy.allow_implicit_invocation: false` in `agents/openai.yaml`, reachable only by the human) or model-invoked (model- or user-reachable). See [.agents/invocation.md](./.agents/invocation.md).
 

CONTEXT.md

@@ -5,7 +5,7 @@ A collection of agent skills (slash commands and behaviors) loaded by Claude Cod
 ## Language
 
 **Issue tracker**:
-The tool that hosts a repo's issues — GitHub Issues, Linear, a local `.scratch/` markdown convention, or similar. Skills like `to-tickets`, `to-spec`, `triage`, and `qa` read from and write to it.
+The tool that hosts a repo's issues — GitHub Issues, Linear, a local `.scratch/` markdown convention, or similar. Skills like `to-tickets`, `to-spec`, and `triage` read from and write to it.
 _Avoid_: backlog manager, backlog backend, issue host
 
 **Issue**:

README.md

@@ -200,6 +200,7 @@ Skills I use daily for code work.
 - **[to-tickets](./skills/engineering/to-tickets/SKILL.md)** — Break any plan, spec, or conversation into a set of tracer-bullet tickets, each declaring its blocking edges — written as text in a local file, or as native blocking links on a real tracker.
 - **[implement](./skills/engineering/implement/SKILL.md)** — Build the work described by a spec or set of tickets, driving `/tdd` at pre-agreed seams and closing out with `/code-review` before committing.
 - **[wayfinder](./skills/engineering/wayfinder/SKILL.md)** — Plan a huge chunk of work, more than one agent session can hold, as a shared map of investigation tickets on the issue tracker — resolve them one at a time until the way to the destination is clear.
+- **[wizard](./skills/engineering/wizard/SKILL.md)** — Generate an interactive bash wizard that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening each URL, capturing values, confirming every step, and writing `.env` files and GitHub Actions secrets.
 
 **Model-invoked**
 
@@ -222,6 +223,7 @@ General workflow tools, not code-specific.
 - **[handoff](./skills/productivity/handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work.
 - **[teach](./skills/productivity/teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace.
 - **[to-questionnaire](./skills/productivity/to-questionnaire/SKILL.md)** — Turn a decision you can't answer alone into a Markdown questionnaire for the one person who can — filled in async, or together over a meeting. It grills you about the send (who it's for, what you need back), not the subject.
+- **[wait-what](./skills/productivity/wait-what/SKILL.md)** — Fire this the moment a message doesn't land. The agent re-pitches it with the context you're missing, in plain English, using your `CONTEXT.md` vocabulary.
 - **[writing-for-agents](./skills/productivity/writing-for-agents/SKILL.md)** — Writing documents for agents: skills, AGENTS.md/CLAUDE.md, and any doc an agent reaches by a pointer.
 
 **Model-invoked**

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
@@ -26,6 +16,10 @@ Reach for it whenever you're unsure which skill or flow a situation calls for: y
 
 The idea `ask-matt` gives you to think with is the **flow** — a path *through* the skills rather than a single one. Most work runs along one **main flow** (idea → ship: grill → spec → tickets → implement → review), two **on-ramps** merge onto it (a triage lane for incoming bugs and requests; a codebase-health lane that generates ideas), and everything else is a **standalone** you reach for on its own. Ask a question and you get placed on the right flow, at the right step — not just handed a tool.
 
+## Phase boundaries
+
+The other idea it hands you is the **phase boundary**. 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 up. You have five options: **continue**, **`/clear`**, **`/handoff`**, a **subagent**, or **`/compact`**. `ask-matt` carries the decision tree that orders them, and the two corrections most people need: `/handoff` is narrow — it earns its keep only when something has to *travel* (a new harness, a new directory, a colleague, a side task forked mid-phase) — and `/compact` is the tree's default at the bottom, not its first reach. Reach for the tree at a boundary; mid-phase there's nothing to decide.
+
 ## Where it fits
 
 `ask-matt` is the **router** — the standalone map that sits over the whole set. It is the node every other docs page links back to as [ask-matt](https://aihero.dev/skills-ask-matt), so it never sits *in* a chain; it points *into* every chain. From here you'll most often land on [grill-with-docs](https://aihero.dev/skills-grill-with-docs), the head of the main flow, or [triage](https://aihero.dev/skills-triage), the on-ramp for work you didn't create. When even the router's own picture is stale, its [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/ask-matt) is the map of record.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

docs/engineering/wizard.md

@@ -0,0 +1,39 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/wizard)
+
+## What it does
+
+`wizard` generates an interactive bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an agent every time — 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 where it belongs.
+
+The UX is not yours to design. 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 (WSL included), hidden entry for secrets, idempotent `.env` upserts, `gh secret` / `gh variable` writes, and a closing summary of anything it had to skip. Everything above the `STAGES` marker is a fixed library that is identical in every wizard and never hand-edited. Your job is only to scope the procedure and author its **stages**.
+
+## When to reach for it
+
+You invoke this by typing `/wizard` — the agent won't reach for it on its own.
+
+Reach for this when the next thing blocking you is a human clicking through a dashboard: a new dev needs six services configured before the app boots, a migration needs someone to flip switches in the right order, or you're about to write those steps into a README that will rot. If the procedure is something the *agent* can just do, it should do it — a wizard is specifically for the steps only a human can take.
+
+## 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.
+
+## Stages
+
+A **stage** is the unit of authoring and the unit of attention: one focused task, one screen. The script clears between stages, so anything that doesn't fit 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 — the estimate is a promise to the person running it.
+
+Getting there is three steps of scoping before a line is written. The skill reads the repo first 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 shows you the ordered stage list to confirm, 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 does not invent clicks that may not exist.
+
+## Ephemeral by default
+
+A wizard is built for one run — saved to a scratch or `scripts/` path, deleted when the job is done. Commit it only when it's a repeatable setup path that should live in the repo, in which case link it from the README so the next person runs the script instead of re-asking an agent.
+
+It's also never run end-to-end by the agent that wrote it: 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.
+
+## It's working if
+
+- You're shown an ordered list of stages and the values each produces, and asked to confirm, before any script exists.
+- The generated file's library section is byte-identical to `template.sh` — only the block below the `STAGES` marker is yours.
+- Every URL is opened before the value it produces is asked for, secrets use hidden entry, and irreversible actions sit behind a confirmation.
+
+## Where it fits
+
+`wizard` is a reach-for-it-anytime standalone, sitting where automation stops and a human has to click. Its nearest neighbour is [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills), because both are run-once setup — that one configures this skill set for a repo, while `wizard` generates setup paths for everything else. It also pairs with [implement](https://aihero.dev/skills-implement): when a build lands a feature that needs credentials or a manual cutover, a wizard is how the human half gets done. When you're unsure which skill fits the moment, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.

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

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

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

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

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

docs/productivity/wait-what.md

@@ -0,0 +1,38 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/wait-what)
+
+## What it does
+
+`wait-what` is the fire extinguisher for a message that didn't land. You fire it the moment you lose the thread, and the agent re-pitches what it just said: a little of the context you were missing, plain English, and the vocabulary from your project's `CONTEXT.md`.
+
+It is three lines long, and that is the design rather than an unfinished draft. Skills that fight verbosity fail by growing — a four-hundred-line concision skill still leaves the model verbose, because the model reads the volume, not the plea. This one carries a single precise leading word and nothing else.
+
+## When to reach for it
+
+You invoke this by typing `/wait-what` — the agent won't reach for it on its own, and it shouldn't: only you know when you stopped following.
+
+Reach for it the second you notice you're skimming — the agent has drifted into jargon it invented, stacked five acronyms, or explained a decision whose premise you never saw. It's a one-shot corrective on the conversation you're already in. To stop the jargon arriving in the first place, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs) instead, which builds the shared language upfront.
+
+## The name is the mechanism
+
+The leading word is **wait**. Not "be concise" — an instruction about the agent's output, which the model satisfies by clipping words and losing you further. **Wait** is about *your* state: it says comprehension failed here. An agent that hears "be brief" writes telegrams. An agent that hears "wait, you lost me" backs up and explains.
+
+That distinction is the whole skill. Every popular fix for verbosity — `/tldr`, `/no-fluff`, `/talk-normal` — names the *output*, so the model over-corrects into a caveman register that's shorter and no clearer. Naming the *listener* asks for both halves at once: fewer words **and** the context you were missing.
+
+The re-pitch is deliberately vague about its own scope. It says re-pitch **that**, not "that last message", because what lost you is usually bigger than one paragraph — the agent decides how far back to go.
+
+## It plugs into the language you already have
+
+The body reuses the leading words already sitting in your global `CLAUDE.md` and your project's `CONTEXT.md`: ASD-STE100 Simplified Technical English for the register, ubiquitous language for the nouns. Skill, `CLAUDE.md` and `CONTEXT.md` reach for the same tokens, so firing it isn't a new instruction — it's a reminder of one the agent already agreed to.
+
+If you have no `CONTEXT.md`, it still works; you just lose the domain-vocabulary half.
+
+## It's working if
+
+- The re-pitch is **shorter and clearer**, not shorter and blunter.
+- It adds the premise you were missing rather than just deleting words.
+- Project nouns replace invented ones — the terms in your `CONTEXT.md` come back.
+- You can fire it twice in a row without it degrading into terseness.
+
+## Where it fits
+
+`wait-what` is a reach-for-it-anytime standalone — it sits inside whatever conversation you're already having, in any skill, at any point. It's the extinguisher; [grill-with-docs](https://aihero.dev/skills-grill-with-docs) is the sprinkler system, because a shared language agreed upfront is the real cure for jargon, and [domain-modeling](https://aihero.dev/skills-domain-modeling) is what you reach for when the *words themselves* are the problem rather than one bad message. When you're unsure which skill fits the moment, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.

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

skills/deprecated/README.md

@@ -1,8 +1,3 @@
 # Deprecated
 
-Skills I no longer use.
+Skills I no longer use. This bucket is currently empty — a retired skill is deleted, and the changeset that removes it names whatever replaced it.
-
-- **[design-an-interface](./design-an-interface/SKILL.md)** — Generate multiple radically different interface designs for a module using parallel sub-agents.
-- **[qa](./qa/SKILL.md)** — Interactive QA session where user reports bugs conversationally and the agent files GitHub issues.
-- **[request-refactor-plan](./request-refactor-plan/SKILL.md)** — Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue.
-- **[ubiquitous-language](./ubiquitous-language/SKILL.md)** — Extract a DDD-style ubiquitous language glossary from the current conversation.

skills/deprecated/design-an-interface/SKILL.md

@@ -1,94 +0,0 @@
----
-name: design-an-interface
-description: Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".
----
-
-# Design an Interface
-
-Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
-
-## Workflow
-
-### 1. Gather Requirements
-
-Before designing, understand:
-
-- [ ] What problem does this module solve?
-- [ ] Who are the callers? (other modules, external users, tests)
-- [ ] What are the key operations?
-- [ ] Any constraints? (performance, compatibility, existing patterns)
-- [ ] What should be hidden inside vs exposed?
-
-Ask: "What does this module need to do? Who will use it?"
-
-### 2. Generate Designs (Parallel Sub-Agents)
-
-Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach.
-
-```
-Prompt template for each sub-agent:
-
-Design an interface for: [module description]
-
-Requirements: [gathered requirements]
-
-Constraints for this design: [assign a different constraint to each agent]
-- Agent 1: "Minimize method count - aim for 1-3 methods max"
-- Agent 2: "Maximize flexibility - support many use cases"
-- Agent 3: "Optimize for the most common case"
-- Agent 4: "Take inspiration from [specific paradigm/library]"
-
-Output format:
-1. Interface signature (types/methods)
-2. Usage example (how caller uses it)
-3. What this design hides internally
-4. Trade-offs of this approach
-```
-
-### 3. Present Designs
-
-Show each design with:
-
-1. **Interface signature** - types, methods, params
-2. **Usage examples** - how callers actually use it in practice
-3. **What it hides** - complexity kept internal
-
-Present designs sequentially so user can absorb each approach before comparison.
-
-### 4. Compare Designs
-
-After showing all designs, compare them on:
-
-- **Interface simplicity**: fewer methods, simpler params
-- **General-purpose vs specialized**: flexibility vs focus
-- **Implementation efficiency**: does shape allow efficient internals?
-- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
-- **Ease of correct use** vs **ease of misuse**
-
-Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
-
-### 5. Synthesize
-
-Often the best design combines insights from multiple options. Ask:
-
-- "Which design best fits your primary use case?"
-- "Any elements from other designs worth incorporating?"
-
-## Evaluation Criteria
-
-From "A Philosophy of Software Design":
-
-**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly.
-
-**General-purpose**: Can handle future use cases without changes. But beware over-generalization.
-
-**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?
-
-**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
-
-## Anti-Patterns
-
-- Don't let sub-agents produce similar designs - enforce radical difference
-- Don't skip comparison - the value is in contrast
-- Don't implement - this is purely about interface shape
-- Don't evaluate based on implementation effort

skills/deprecated/design-an-interface/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Design an Interface"
-  short_description: "Explore alternative module interfaces"

skills/deprecated/qa/SKILL.md

@@ -1,130 +0,0 @@
----
-name: qa
-description: Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, file issues conversationally, or mentions "QA session".
----
-
-# QA Session
-
-Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file GitHub issues that are durable, user-focused, and use the project's domain language.
-
-## For each issue the user raises
-
-### 1. Listen and lightly clarify
-
-Let the user describe the problem in their own words. Ask **at most 2-3 short clarifying questions** focused on:
-
-- What they expected vs what actually happened
-- Steps to reproduce (if not obvious)
-- Whether it's consistent or intermittent
-
-Do NOT over-interview. If the description is clear enough to file, move on.
-
-### 2. Explore the codebase in the background
-
-While talking to the user, kick off an Agent (subagent_type=Explore) in the background to understand the relevant area. The goal is NOT to find a fix — it's to:
-
-- Learn the domain language used in that area (check UBIQUITOUS_LANGUAGE.md)
-- Understand what the feature is supposed to do
-- Identify the user-facing behavior boundary
-
-This context helps you write a better issue — but the issue itself should NOT reference specific files, line numbers, or internal implementation details.
-
-### 3. Assess scope: single issue or breakdown?
-
-Before filing, decide whether this is a **single issue** or needs to be **broken down** into multiple issues.
-
-Break down when:
-
-- The fix spans multiple independent areas (e.g. "the form validation is wrong AND the success message is missing AND the redirect is broken")
-- There are clearly separable concerns that different people could work on in parallel
-- The user describes something that has multiple distinct failure modes or symptoms
-
-Keep as a single issue when:
-
-- It's one behavior that's wrong in one place
-- The symptoms are all caused by the same root behavior
-
-### 4. File the GitHub issue(s)
-
-Create issues with `gh issue create`. Do NOT ask the user to review first — just file and share URLs.
-
-Issues must be **durable** — they should still make sense after major refactors. Write from the user's perspective.
-
-#### For a single issue
-
-Use this template:
-
-```
-## What happened
-
-[Describe the actual behavior the user experienced, in plain language]
-
-## What I expected
-
-[Describe the expected behavior]
-
-## Steps to reproduce
-
-1. [Concrete, numbered steps a developer can follow]
-2. [Use domain terms from the codebase, not internal module names]
-3. [Include relevant inputs, flags, or configuration]
-
-## Additional context
-
-[Any extra observations from the user or from codebase exploration that help frame the issue — e.g. "this only happens when using the Docker layer, not the filesystem layer" — use domain language but don't cite files]
-```
-
-#### For a breakdown (multiple issues)
-
-Create issues in dependency order (blockers first) so you can reference real issue numbers.
-
-Use this template for each sub-issue:
-
-```
-## Parent issue
-
-#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"
-
-## What's wrong
-
-[Describe this specific behavior problem — just this slice, not the whole report]
-
-## What I expected
-
-[Expected behavior for this specific slice]
-
-## Steps to reproduce
-
-1. [Steps specific to THIS issue]
-
-## Blocked by
-
-- #<issue-number> (if this issue can't be fixed until another is resolved)
-
-Or "None — can start immediately" if no blockers.
-
-## Additional context
-
-[Any extra observations relevant to this slice]
-```
-
-When creating a breakdown:
-
-- **Prefer many thin issues over few thick ones** — each should be independently fixable and verifiable
-- **Mark blocking relationships honestly** — if issue B genuinely can't be tested until issue A is fixed, say so. If they're independent, mark both as "None — can start immediately"
-- **Create issues in dependency order** so you can reference real issue numbers in "Blocked by"
-- **Maximize parallelism** — the goal is that multiple people (or agents) can grab different issues simultaneously
-
-#### Rules for all issue bodies
-
-- **No file paths or line numbers** — these go stale
-- **Use the project's domain language** (check UBIQUITOUS_LANGUAGE.md if it exists)
-- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws on line 42"
-- **Reproduction steps are mandatory** — if you can't determine them, ask the user
-- **Keep it concise** — a developer should be able to read the issue in 30 seconds
-
-After filing, print all issue URLs (with blocking relationships summarized) and ask: "Next issue, or are we done?"
-
-### 5. Continue the session
-
-Keep going until the user says they're done. Each issue is independent — don't batch them.

skills/deprecated/qa/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "QA"
-  short_description: "Conversational QA that files issues"

skills/deprecated/request-refactor-plan/SKILL.md

@@ -1,68 +0,0 @@
----
-name: request-refactor-plan
-description: Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
----
-
-This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.
-
-1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
-
-2. Explore the repo to verify their assertions and understand the current state of the codebase.
-
-3. Ask whether they have considered other options, and present other options to them.
-
-4. Interview the user about the implementation. Be extremely detailed and thorough.
-
-5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.
-
-6. Look in the codebase to check for test coverage of this area of the codebase. If there is insufficient test coverage, ask the user what their plans for testing are.
-
-7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working."
-
-8. Create a GitHub issue with the refactor plan. Use the following template for the issue description:
-
-<refactor-plan-template>
-
-## Problem Statement
-
-The problem that the developer is facing, from the developer's perspective.
-
-## Solution
-
-The solution to the problem, from the developer's perspective.
-
-## Commits
-
-A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state.
-
-## Decision Document
-
-A list of implementation decisions that were made. This can include:
-
-- The modules that will be built/modified
-- The interfaces of those modules that will be modified
-- Technical clarifications from the developer
-- Architectural decisions
-- Schema changes
-- API contracts
-- Specific interactions
-
-Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
-
-## Testing Decisions
-
-A list of testing decisions that were made. Include:
-
-- A description of what makes a good test (only test external behavior, not implementation details)
-- Which modules will be tested
-- Prior art for the tests (i.e. similar types of tests in the codebase)
-
-## Out of Scope
-
-A description of the things that are out of scope for this refactor.
-
-## Further Notes (optional)
-
-Any further notes about the refactor.
-
-</refactor-plan-template>

skills/deprecated/request-refactor-plan/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Request Refactor Plan"
-  short_description: "Plan a safe incremental refactor"

skills/deprecated/ubiquitous-language/SKILL.md

@@ -1,93 +0,0 @@
----
-name: ubiquitous-language
-description: Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".
-disable-model-invocation: true
----
-
-# Ubiquitous Language
-
-Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to a local file.
-
-## Process
-
-1. **Scan the conversation** for domain-relevant nouns, verbs, and concepts
-2. **Identify problems**:
-   - Same word used for different concepts (ambiguity)
-   - Different words used for the same concept (synonyms)
-   - Vague or overloaded terms
-3. **Propose a canonical glossary** with opinionated term choices
-4. **Write to `UBIQUITOUS_LANGUAGE.md`** in the working directory using the format below
-5. **Output a summary** inline in the conversation
-
-## Output Format
-
-Write a `UBIQUITOUS_LANGUAGE.md` file with this structure:
-
-```md
-# Ubiquitous Language
-
-## Order lifecycle
-
-| Term        | Definition                                              | Aliases to avoid      |
-| ----------- | ------------------------------------------------------- | --------------------- |
-| **Order**   | A customer's request to purchase one or more items      | Purchase, transaction |
-| **Invoice** | A request for payment sent to a customer after delivery | Bill, payment request |
-
-## People
-
-| Term         | Definition                                  | Aliases to avoid       |
-| ------------ | ------------------------------------------- | ---------------------- |
-| **Customer** | A person or organization that places orders | Client, buyer, account |
-| **User**     | An authentication identity in the system    | Login, account         |
-
-## Relationships
-
-- An **Invoice** belongs to exactly one **Customer**
-- An **Order** produces one or more **Invoices**
-
-## Example dialogue
-
-> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
-> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed. A single **Order** can produce multiple **Invoices** if items ship in separate **Shipments**."
-> **Dev:** "So if a **Shipment** is cancelled before dispatch, no **Invoice** exists for it?"
-> **Domain expert:** "Exactly. The **Invoice** lifecycle is tied to the **Fulfillment**, not the **Order**."
-
-## Flagged ambiguities
-
-- "account" was used to mean both **Customer** and **User** — these are distinct concepts: a **Customer** places orders, while a **User** is an authentication identity that may or may not represent a **Customer**.
-```
-
-## Rules
-
-- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
-- **Flag conflicts explicitly.** If a term is used ambiguously in the conversation, call it out in the "Flagged ambiguities" section with a clear recommendation.
-- **Only include terms relevant for domain experts.** Skip the names of modules or classes unless they have meaning in the domain language.
-- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
-- **Show relationships.** Use bold term names and express cardinality where obvious.
-- **Only include domain terms.** Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning.
-- **Group terms into multiple tables** when natural clusters emerge (e.g. by subdomain, lifecycle, or actor). Each group gets its own heading and table. If all terms belong to a single cohesive domain, one table is fine — don't force groupings.
-- **Write an example dialogue.** A short conversation (3-5 exchanges) between a dev and a domain expert that demonstrates how the terms interact naturally. The dialogue should clarify boundaries between related concepts and show terms being used precisely.
-
-<example>
-
-## Example dialogue
-
-> **Dev:** "How do I test the **sync service** without Docker?"
-
-> **Domain expert:** "Provide the **filesystem layer** instead of the **Docker layer**. It implements the same **Sandbox service** interface but uses a local directory as the **sandbox**."
-
-> **Dev:** "So **sync-in** still creates a **bundle** and unpacks it?"
-
-> **Domain expert:** "Exactly. The **sync service** doesn't know which layer it's talking to. It calls `exec` and `copyIn` — the **filesystem layer** just runs those as local shell commands."
-
-</example>
-
-## Re-running
-
-When invoked again in the same conversation:
-
-1. Read the existing `UBIQUITOUS_LANGUAGE.md`
-2. Incorporate any new terms from subsequent discussion
-3. Update definitions if understanding has evolved
-4. Re-flag any new ambiguities
-5. Rewrite the example dialogue to incorporate new terms

skills/deprecated/ubiquitous-language/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Ubiquitous Language"
-  short_description: "Build a shared domain glossary"
-policy:
-  allow_implicit_invocation: false

skills/engineering/README.md

@@ -15,6 +15,7 @@ Reachable only when you type them (Claude Code: `disable-model-invocation: true`
 - **[to-tickets](./to-tickets/SKILL.md)** — Break any plan, spec, or conversation into a set of tracer-bullet tickets, each declaring its blocking edges — text in a local file, or native blocking links on a real tracker.
 - **[implement](./implement/SKILL.md)** — Build the work described by a spec or set of tickets, driving `/tdd` at pre-agreed seams and closing out with `/code-review` before committing.
 - **[wayfinder](./wayfinder/SKILL.md)** — Plan a huge chunk of work — more than one agent session can hold — as a shared map of decision tickets on the issue tracker, resolved one at a time until the way to the destination is clear.
+- **[wizard](./wizard/SKILL.md)** — Generate an interactive bash wizard that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening URLs, capturing values, and writing `.env` files and GitHub Actions secrets.
 
 ## Model-invoked
 

skills/engineering/ask-matt/PHASE-BOUNDARIES.md

@@ -0,0 +1,55 @@
+# Phase boundaries
+
+A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. The definition is fuzzy on purpose: a phase ends when you think *"ok, we're done with that"*.
+
+The **phase boundary** is the gap between two phases, and it is the only place this decision belongs. Mid-phase there is no decision to make — continue, or split the work that's left into subagents. Compacting mid-phase makes the agent lose the thread.
+
+## The five options
+
+| Option       | What it does                                                    |
+| ------------ | --------------------------------------------------------------- |
+| **Continue** | Stay in the session. No context switch at all.                    |
+| **`/clear`** | Empty the context window and start from nothing.                  |
+| **`/handoff`** | Write a portable markdown file and seed a session anywhere with it. |
+| **Subagent** | Send the task to its own context window and get a report back.     |
+| **`/compact`** | Compress this context and seed a fresh session with the summary.  |
+
+## The tree
+
+Work top to bottom at the boundary. The first **yes** wins.
+
+**1. Can you continue in this session?** Two things make the answer yes: the next phase needs this phase as a **primary source**, or you have enough [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) left (~150k tokens) for the next phase to fit. Grilling → implementation is the standard yes: the implementation wants the reasoning verbatim, not a summary of it. Continue costs nothing and loses nothing, so rule it out before anything else.
+
+**2. Is the context irrelevant to what comes next?** Is everything in this session — the exploration, the decisions, the dead ends — disposable? If so, **`/clear`**. It is the cheapest move on the board: it takes no time and hands back the whole window. `/clear` also isn't terminal — the old session stays resumable.
+
+The cost of getting this wrong is one-way. Clear a *relevant* context and you lose the **why** behind what you built, and no amount of reading the diff back gets it returned.
+
+**3. Do you need to hand off?** `/handoff` is narrow. You need it only when you are:
+
+- swapping to a **new harness** (Claude → Codex),
+- moving to a **new directory** or repo,
+- sending the work to a **colleague**,
+- or forking a side task you found **mid-phase** without derailing what you're doing.
+
+That list is the whole clause. What `/handoff` buys is **portability** — a file that travels. If nothing is travelling, you don't need it.
+
+**4. Can the task be done AFK?** Is it scoped tightly enough to run with you away from the keyboard, no steering? Then send it to a **subagent** and leave this session untouched. Automated review is the standard case: the agent reads the diff and reports, and you aren't needed while it does.
+
+**5. Otherwise, `/compact`.** Relevant context, same harness, same directory, and you need to stay in the loop — this is where the tree lands, and it lands here often. Pass it an instruction (`/compact we're going to QA this area`) so the summary keeps what the next phase needs.
+
+`/compact` is the **default, not the first reach**. It sits at the bottom because the four questions above it are all cheaper or more precise. The failure mode when people start here is a fresh session that is confidently wrong about a decision the summary flattened.
+
+## Primary and secondary sources
+
+Every move except **Continue** turns a **primary source** into a **secondary source** — the session as it happened, replaced by a summary of it. The trade is always the same shape:
+
+| Source                            | Information | Noise | Room to move |
+| --------------------------------- | ----------- | ----- | ------------ |
+| Primary (Continue)                | Full        | Lots  | Little       |
+| Secondary (`/compact`, `/handoff`) | Lossy       | Less  | Lots         |
+
+This is why question 1 comes first. You only pay the lossiness when staying costs more than it saves.
+
+## These are judgement calls
+
+The questions are not objective — each has taste in it, and the same boundary can go two ways on two days. The value is in asking them **in order**, at the boundary rather than in the middle of the work.

skills/engineering/ask-matt/SKILL.md

@@ -15,12 +15,12 @@ A **flow** is a path through the skills. Most paths run along one **main flow**,
 The route most work travels. You have an idea and want it built.
 
 1. **`/grill-with-docs`** — sharpen the idea by interview. Start here when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail.)
-2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (see Crossing sessions):
+2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (a prototype lives in its own directory, which is exactly what `/handoff` is for — see Phase boundaries):
    - **`/handoff`** out, then open a fresh session against that file,
    - **`/prototype`** to answer the question with throwaway code,
    - **`/handoff`** back what you learned, and reference it from the original idea thread.
 3. **Branch — is this a multi-session build?**
-   - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **clearing context between each one**.
+   - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
    - **No** → **`/implement`** right here, in the same context window.
 
    Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
@@ -29,7 +29,7 @@ The route most work travels. You have an idea and want it built.
 
 Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket.
 
-The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/handoff` and continue in a fresh thread.
+The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~150k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/compact` at the nearest phase boundary and carry on (see Phase boundaries).
 
 ## On-ramps
 
@@ -58,10 +58,17 @@ Two model-invoked references that run *beneath* the other skills — each the si
 - **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary.
 - **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `/tdd` and `/improve-codebase-architecture` both speak it.
 
-## Crossing sessions
+## Phase boundaries
 
-- **`/handoff`** — when a thread is full or you need to branch off (e.g. into a `/prototype` session), this compacts the conversation into a markdown file. You don't continue in place — you **open a new session and reference that file** to carry the context across. It's the bridge between context windows, in either direction. Use it when you want a **fresh session** but need the **current conversation preserved**.
+A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. At the **boundary** between two of them you have five options, and picking between them is the fuzziest decision in this whole map:
-- **`/compact`** (built-in) — stay in the **same conversation**, letting the earlier turns be summarized. Use it at **intentional breaks between phases**, when you don't mind losing the verbatim history. Don't compact mid-phase — the agent can lose its way. `/handoff` forks; `/compact` continues.
+
+- **Continue** — stay put. Costs nothing, loses nothing.
+- **`/clear`** — empty the window, when nothing here matters to what's next.
+- **`/handoff`** — write a portable markdown file. Narrow: only for a **new harness**, a **new directory**, a **colleague**, or forking a side task **mid-phase**. What it buys is portability.
+- **Subagent** — send a tightly-scoped task to its own window and get a report back.
+- **`/compact`** — compress this context and seed a fresh session with it. The **default**, at the bottom of the tree rather than the first reach.
+
+Read [PHASE-BOUNDARIES.md](PHASE-BOUNDARIES.md) for the ordered tree — the five questions, the reasoning behind each branch, and why the primary-source cost makes **Continue** the one to rule out first. Make the decision **at** a boundary; mid-phase, continue or split the rest into subagents.
 
 ## Standalone
 
@@ -71,6 +78,8 @@ Off the main flow entirely.
 - **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway from day one — keep the answer, delete the code. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
 - **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
 - **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
+- **`/wizard`** — for the steps only a **human** can take: clicking through a third-party dashboard, running a one-off migration, moving the project from state A to state B. It generates an interactive bash script that opens each URL, captures each value, and writes it into `.env` and GitHub secrets — so the procedure stops being something you re-explain to an agent every time. If the agent could just do it itself, it should; reach for this only where a human is genuinely in the loop.
+- **`/wait-what`** — the fire extinguisher for a message that didn't land. Fire it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It's the in-the-moment corrective; `/grill-with-docs` and `/domain-modeling` are the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
 - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
 - **`/writing-for-agents`** — reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs.
 

skills/engineering/setup-matt-pocock-skills/SKILL.md

@@ -37,7 +37,7 @@ Lead each section with the recommended answer so the user can accept it in a wor
 
 **Section A — Issue tracker.**
 
-> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, `to-spec`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, and `to-spec` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
 
 Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
 

skills/in-progress/README.md

@@ -1,9 +1,14 @@
 # In Progress
 
-Skills that are still being developed. They're not ready to ship — expect rough edges, breaking changes, and abandoned experiments. They're excluded from the plugin and the top-level README until they graduate to a stable bucket.
+Beta. These skills are public on purpose — try them and tell me what breaks. They're excluded from the plugin and the top-level README until they graduate to a stable bucket, they get no docs pages, and they can change or disappear without warning.
+
+The plugin won't give you these. Install one directly:
+
+```bash
+npx skills@latest add mattpocock/skills --skill=<name>
+```
 
 - **[loop-me](./loop-me/SKILL.md)** — Grill yourself into implementable workflow specs over multiple sessions, using the current directory as a stateful workspace. User-invoked.
-- **[wizard](./wizard/SKILL.md)** — Generate an interactive bash wizard that walks a human through a manual procedure (setup, a one-off migration, a state transition) — opening URLs, capturing values, writing `.env` and GitHub Actions secrets. User-invoked.
 - **[writing-beats](./writing-beats/SKILL.md)** — Shape an article as a journey of beats, choose-your-own-adventure style. Pick a starting beat, write only that beat, then pivot to the next, until the article reaches a natural end.
 - **[writing-fragments](./writing-fragments/SKILL.md)** — Grilling session that mines you for fragments — heterogeneous nuggets of writing — and appends them to a single document as raw material for a future article.
 - **[writing-shape](./writing-shape/SKILL.md)** — Take a markdown file of raw material and shape it into an article paragraph by paragraph, arguing format choices at each step.

skills/personal/README.md

@@ -1,6 +0,0 @@
-# Personal
-
-Skills tied to my own setup, not promoted in the plugin.
-
-- **[edit-article](./edit-article/SKILL.md)** — Edit and improve articles by restructuring sections, improving clarity, and tightening prose.
-- **[obsidian-vault](./obsidian-vault/SKILL.md)** — Search, create, and manage notes in an Obsidian vault with wikilinks and index notes.

skills/personal/edit-article/SKILL.md

@@ -1,15 +0,0 @@
----
-name: edit-article
-description: Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.
-disable-model-invocation: true
----
-
-1. First, divide the article into sections based on its headings. Think about the main points you want to make during those sections.
-
-Consider that information is a directed acyclic graph, and that pieces of information can depend on other pieces of information. Make sure that the order of the sections and their contents respects these dependencies.
-
-Confirm the sections with the user.
-
-2. For each section:
-
-2a. Rewrite the section to improve clarity, coherence, and flow. Use maximum 240 characters per paragraph.

skills/personal/edit-article/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Edit Article"
-  short_description: "Restructure and tighten a draft"
-policy:
-  allow_implicit_invocation: false

skills/personal/obsidian-vault/SKILL.md

@@ -1,59 +0,0 @@
----
-name: obsidian-vault
-description: Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.
----
-
-# Obsidian Vault
-
-## Vault location
-
-`/mnt/d/Obsidian Vault/AI Research/`
-
-Mostly flat at root level.
-
-## Naming conventions
-
-- **Index notes**: aggregate related topics (e.g., `Ralph Wiggum Index.md`, `Skills Index.md`, `RAG Index.md`)
-- **Title case** for all note names
-- No folders for organization - use links and index notes instead
-
-## Linking
-
-- Use Obsidian `[[wikilinks]]` syntax: `[[Note Title]]`
-- Notes link to dependencies/related notes at the bottom
-- Index notes are just lists of `[[wikilinks]]`
-
-## Workflows
-
-### Search for notes
-
-```bash
-# Search by filename
-find "/mnt/d/Obsidian Vault/AI Research/" -name "*.md" | grep -i "keyword"
-
-# Search by content
-grep -rl "keyword" "/mnt/d/Obsidian Vault/AI Research/" --include="*.md"
-```
-
-Or use Grep/Glob tools directly on the vault path.
-
-### Create a new note
-
-1. Use **Title Case** for filename
-2. Write content as a unit of learning (per vault rules)
-3. Add `[[wikilinks]]` to related notes at the bottom
-4. If part of a numbered sequence, use the hierarchical numbering scheme
-
-### Find related notes
-
-Search for `[[Note Title]]` across the vault to find backlinks:
-
-```bash
-grep -rl "\\[\\[Note Title\\]\\]" "/mnt/d/Obsidian Vault/AI Research/"
-```
-
-### Find index notes
-
-```bash
-find "/mnt/d/Obsidian Vault/AI Research/" -name "*Index*"
-```

skills/personal/obsidian-vault/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Obsidian Vault"
-  short_description: "Manage linked notes in Obsidian"

skills/productivity/README.md

@@ -10,6 +10,7 @@ Reachable only when you type them (Claude Code: `disable-model-invocation: true`
 - **[handoff](./handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work.
 - **[teach](./teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace.
 - **[to-questionnaire](./to-questionnaire/SKILL.md)** — Turn a decision you can't answer alone into a Markdown questionnaire for the one person who can — filled in async, or together over a meeting.
+- **[wait-what](./wait-what/SKILL.md)** — Fire this the moment a message doesn't land. The agent re-pitches it with the context you're missing, in plain English, using your `CONTEXT.md` vocabulary.
 - **[writing-for-agents](./writing-for-agents/SKILL.md)** — Writing documents for agents: skills, AGENTS.md/CLAUDE.md, and any doc an agent reaches by a pointer.
 
 ## Model-invoked

skills/productivity/wait-what/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: wait-what
+description: Stop. That last message did not land — re-pitch it.
+disable-model-invocation: true
+---
+
+Wait — I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md`.

skills/productivity/wait-what/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Wait What"
+  short_description: "Re-pitch that — simpler, with the context I'm missing"
+policy:
+  allow_implicit_invocation: false