refactor: flatten skills/ and adopt Agent Plugins 1.0

The Agent Plugins standard reads only the immediate children of
skills/ and cannot be pointed elsewhere, so a bucketed tree is
invisible to every conformant client.

Rather than generate a flat copy of the repo into a package
directory — a builder, a validator, an allowlist, a drift CI job,
and every skill committed twice — remove the buckets.

- skills/ is flat and holds exactly the promoted 25
- in-progress/ -> drafts/, misc/ -> extras/, deprecated/ deleted
- new root plugin.json (Agent Plugins 1.0)
- .claude-plugin/plugin.json loses its 25-entry skills array
- docs/ keeps its category folders; it is now the only place a
  skill's category lives

Reasoning in .agents/adr/0003.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.agents/adr/0003-flat-skills-tree-for-agent-plugins.md

@@ -0,0 +1,38 @@
+# Flatten `skills/` to the promoted set, and adopt Agent Plugins 1.0
+
+[ADR 0002](./0002-ship-as-a-claude-code-plugin.md) shipped the Claude Code plugin and deferred everything else, because no other manifest format could express "a curated subset of a bucketed repo". It named two ways out: **(a)** restructure so `skills/` holds only promoted skills, or **(b)** commit a generated flat copy. This ADR takes **(a)**.
+
+## What forced the decision
+
+The [Agent Plugins](https://agent-plugins.org/) standard published 1.0.0 on 6 August 2026 — Cursor, VS Code, GitHub Copilot, ChatGPT/Codex and Kiro are listed as clients. Its discovery rule is fixed and normative: a client reads the immediate children of `skills/`, "MUST NOT recursively search deeper descendants", and "`plugin.json` cannot override these locations". A bucketed `skills/engineering/<name>/` tree is therefore invisible to every conformant client.
+
+A spec was proposed that kept the buckets and generated a flat package under `plugins/mattpocock-skills/`, with a TypeScript builder, a validator, a promoted-skill allowlist, and a CI job failing on any rebuild diff. That is option (b) with extra steps: every skill in the repo twice, a rewrite step mangling `SKILL.md` frontmatter on the way through, and four new pieces of tooling — in a repo with no TypeScript at all. The whole apparatus exists only to work around the buckets.
+
+Removing the buckets removes the apparatus. We are conformant by layout instead of by tooling.
+
+## Decision
+
+- `skills/` is **flat** and holds **exactly** the promoted set. Folder location is the only promotion mechanism.
+- Unpromoted skills move out of `skills/`: `in-progress/` → `drafts/`, `misc/` → `extras/`. `deprecated/` is deleted — it was empty, and a retired skill is deleted outright anyway.
+- Add `plugin.json` at the repo root: the canonical Agent Plugins 1.0 manifest. It lists no skills, because the standard's schema is closed and discovery is fixed.
+- Keep `.claude-plugin/plugin.json` for Claude Code, which does not implement the standard yet, and **delete its `skills` array** — Claude auto-discovers a flat `skills/`, and a 25-entry list is a second promotion mechanism that can drift.
+- No generated package, no build script, no duplicate skill tree, no drift CI, no TypeScript.
+
+## What we deliberately did not do
+
+- **No `.codex-plugin/plugin.json` or `.cursor-plugin/plugin.json`.** Cursor documents dual support ("A plugin that conforms to the Agent Plugins specification loads in Cursor without changes"), and the Codex source reads the root `plugin.json` first, falling back to the legacy paths only if it is absent. The proposed spec was more conservative than either client.
+- **No new marketplace manifests.** Marketplaces are not part of Agent Plugins at all. Copilot reads `.claude-plugin/marketplace.json`, and Codex treats it as legacy-compatible, so the file we already have may serve all three. Add `.agents/plugins/marketplace.json` or `.github/plugin/marketplace.json` only where a real install fails.
+- **No rename to `mp`.** The public name stays `mattpocock-skills`. It is live in Claude Code's official marketplace with auto-update, so renaming would break every existing install for a shorter slash command.
+- **No flattening of `docs/`.** `docs/<category>/` is now the only place a skill's category lives. Flattening it would force 27 manual `githubSource` repoints on aihero.dev, one CLI call each, with no bulk command — for zero technical gain, because no client reads `docs/`.
+
+## Consequences
+
+- Promoting a skill is `git mv drafts/<name> skills/<name>` plus a README entry and a docs page. Retiring one is `git mv` out. No manifest to keep in step.
+- `npx skills@latest add mattpocock/skills` stops offering all 35 skills. It walks `skills/` to depth 3 regardless of any manifest, so it has been offering every draft and extra all along; moving them out of `skills/` narrows the offer to the promoted 25. A fix we got for free.
+- `disable-model-invocation` is carried by 14 of the 25 promoted skills and is **not** part of the Agent Skills standard — there is an open, unanswered proposal to make it one. We keep it in one shared tree and rely on non-Claude clients ignoring an unknown frontmatter key. If a portable client ever fires a user-invoked skill on its own, that assumption is broken and this decision needs revisiting; the alternative is a second skill tree, which is the duplication we just removed.
+- Claude Code was **not** on the compatible-clients list when this was written, and neither the docs nor a 5,370-line changelog mention the standard. `.claude-plugin/plugin.json` therefore stays as the working manifest, not as legacy baggage. Delete it only once Claude reads the root manifest.
+- The standard is one day old and still labelled a Working Draft. The flatten is right regardless of what the standard does next; the root `plugin.json` is 20 lines and costs nothing if the spec moves.
+
+## Status of ADR 0002
+
+Superseded in part. Its Claude-plugin decision stands. Its deferral of every other ecosystem is resolved here by taking the restructure it described.

.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/`, `in-progress/`, `deprecated/`) ship no docs page.
+Every promoted skill — every folder under `skills/` — has a human-facing **docs page** at `docs/<category>/<skill-name>.md`, where `<category>` is `engineering` or `productivity`. The skills tree itself is flat, so this docs folder is the only place a skill's category lives. The page is published at `https://aihero.dev/skills-<skill-name>`; the URL is always `skills-<skill-name>` regardless of category, so the docs path is repo organisation only. The page is not the skill and not a copy of `SKILL.md`. Skills in `drafts/` and `extras/` 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/`, `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/<category>/<old>.md` → `docs/<category>/<new>.md`), because the published URL tracks the name; recategorising a skill moves its docs file to the other folder and changes nothing else. Skills in `drafts/` and `extras/` get no page. A skill promoted into `skills/` gains a page; one moved out of `skills/` 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.
 

.changeset/domain-modeling-trigger-context-adr.md

@@ -1,5 +0,0 @@
----
-"mattpocock-skills": patch
----
-
-domain-modeling: trigger on discussing codebase terminology and on writing or editing a CONTEXT.md or an ADR directly, replacing the narrower "pin down domain terminology or a ubiquitous language" / "record an architectural decision" phrasing. Also drops the "another skill needs to maintain the domain model" caveat — that's the invoking skill's job to state explicitly, not this description's.

.changeset/flat-skills-tree.md

@@ -0,0 +1,15 @@
+---
+"mattpocock-skills": patch
+---
+
+Flatten `skills/` so the repo conforms to the [Agent Plugins 1.0](https://agent-plugins.org/) standard, which reads only the immediate children of `skills/` and can't be pointed anywhere else.
+
+Nothing changes for installed users: same plugin name, same 25 skills, same slash commands, same install commands. **Source paths moved**, so anything pinning a `skills/engineering/…` or `skills/productivity/…` path needs updating.
+
+- Promoted skills are now flat at `skills/<name>/`. Which folder a skill lives in is the only thing that decides whether it ships.
+- `in-progress/` → `drafts/`, `misc/` → `extras/`, both outside `skills/`. `deprecated/` is deleted; it was empty.
+- New `plugin.json` at the repo root — the Agent Plugins 1.0 manifest, read by Codex, Cursor and Copilot.
+- `.claude-plugin/plugin.json` keeps serving Claude Code, which doesn't implement the standard yet, and loses its 25-entry `skills` array.
+- `npx skills@latest add mattpocock/skills` now offers the promoted 25 only. It was quietly offering all 35, drafts included.
+
+The reasoning, and the generated-package approach we rejected, are in [ADR 0003](https://github.com/mattpocock/skills/blob/main/.agents/adr/0003-flat-skills-tree-for-agent-plugins.md).

.changeset/grilling-remove-em-dashes.md

@@ -1,5 +0,0 @@
----
-"mattpocock-skills": patch
----
-
-grilling: remove em-dashes from `SKILL.md`, replacing them with colons and semicolons so the instructions read as plain text.

.claude-plugin/plugin.json

@@ -17,32 +17,5 @@
     "grilling",
     "domain-modeling",
     "productivity"
-  ],
-  "skills": [
-    "./skills/engineering/ask-matt",
-    "./skills/engineering/diagnosing-bugs",
-    "./skills/engineering/grill-with-docs",
-    "./skills/engineering/triage",
-    "./skills/engineering/improve-codebase-architecture",
-    "./skills/engineering/setup-matt-pocock-skills",
-    "./skills/engineering/tdd",
-    "./skills/engineering/to-spec",
-    "./skills/engineering/to-tickets",
-    "./skills/engineering/wayfinder",
-    "./skills/engineering/implement",
-    "./skills/engineering/prototype",
-    "./skills/engineering/research",
-    "./skills/engineering/domain-modeling",
-    "./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"
   ]
 }

.github/workflows/release.yml

@@ -26,6 +26,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Check plugin manifest versions
+        run: npm run check-plugin-version
+
       - name: Create Version Pull Request
         uses: changesets/action@v1
         with:

CLAUDE.md

@@ -1,23 +1,23 @@
-Skills are organized into bucket folders under `skills/`:
+A skill's folder decides whether it ships. There are three top-level folders, and no buckets inside them:
 
-- `engineering/` — daily code work
-- `productivity/` — daily non-code workflow tools
-- `misc/` — kept around but rarely used, not promoted
-- `in-progress/` — beta: public on purpose, feedback wanted, not shipped in the plugin
-- `deprecated/` — no longer used
+- `skills/` — the **promoted** set. Exactly what the plugin ships, flat, one folder per skill.
+- `drafts/` — beta: public on purpose, feedback wanted, not shipped.
+- `extras/` — kept around but rarely used, not shipped.
 
-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.
+`skills/` is flat because the [Agent Plugins](https://agent-plugins.org/) standard reads only the immediate children of `skills/` and cannot be pointed elsewhere. Never add a folder between `skills/` and a skill, and never put a non-promoted skill under `skills/` — it would ship.
 
-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. 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).
+Promoting a skill is a `git mv` into `skills/`, plus a reference in the top-level `README.md`. Retiring one is a `git mv` out. There is no manifest list to keep in step.
+
+Install commands are copied verbatim from [.agents/install-block.md](./.agents/install-block.md). Two manifests carry the same metadata and must agree: `plugin.json` at the root (the Agent Plugins 1.0 manifest, read by Codex, Cursor and Copilot) and `.claude-plugin/plugin.json` (read by Claude Code, which does not implement the standard yet). Neither lists skills. `.claude-plugin/marketplace.json` makes the repo its own single-plugin marketplace — a fallback the install block explains, not the documented route. Run `claude plugin validate . --strict` and `node scripts/sync-plugin-version.mjs --check` after touching any manifest. Why the repo is laid out this way lives in [.agents/adr/0003-flat-skills-tree-for-agent-plugins.md](./.agents/adr/0003-flat-skills-tree-for-agent-plugins.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/`, `in-progress/`) use a flat list.
+`drafts/` and `extras/` each have a `README.md` listing every skill in the folder with a one-line description, name linked to its `SKILL.md`, as a flat list. The promoted skills are listed only in the top-level `README.md`, grouped into **User-invoked** and **Model-invoked**.
 
-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). A finished page carries four sections — **What it does**, **When to reach for it**, **Common questions**, **It's working if** — and `writing-docs.md` holds the template, the section order, and where to hunt for the questions. Skills in the non-promoted buckets (`misc/`, `in-progress/`, `deprecated/`) get **no** docs page.
+Every promoted skill also has a human-facing docs page at `docs/<category>/<skill-name>.md`, where `<category>` is `engineering` or `productivity`. That docs folder is the **only** place a skill's category lives — no client reads it, and it drives nothing but the grouping on the site and in the top-level `README.md`. The published URL is `https://aihero.dev/skills-<skill-name>` regardless of category. When you add, rename, or change the behaviour of a promoted skill, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md). A finished page carries four sections — **What it does**, **When to reach for it**, **Common questions**, **It's working if** — and `writing-docs.md` holds the template, the section order, and where to hunt for the questions. Skills in `drafts/` and `extras/` 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).
 
-[`ask-matt`](./skills/engineering/ask-matt/SKILL.md) is the router that maps every user-reachable skill and how they relate. The same trigger that re-syncs a docs page applies to it: whenever you add, rename, remove, or change how a user-reachable skill fits the flows, re-read `ask-matt`'s `SKILL.md` and update it so the map stays accurate — a new skill it never mentions, or a stale one it still routes to, is a router that lies.
+[`ask-matt`](./skills/ask-matt/SKILL.md) is the router that maps every user-reachable skill and how they relate. The same trigger that re-syncs a docs page applies to it: whenever you add, rename, remove, or change how a user-reachable skill fits the flows, re-read `ask-matt`'s `SKILL.md` and update it so the map stays accurate — a new skill it never mentions, or a stale one it still routes to, is a router that lies.
 
 To (re)link every skill into the local harness skill directories (`~/.claude/skills`, `~/.agents/skills`), run `scripts/link-skills.sh`. Each entry is a symlink into this repo, so a `git pull` keeps installed skills current; re-run the script after adding, removing, or renaming a skill.

README.md

@@ -97,8 +97,8 @@ This is just the same in the AI age. There is a communication gap between you an
 
 **The Fix** is to use:
 
-- [`/grill-me`](./skills/productivity/grill-me/SKILL.md) - for non-code uses
-- [`/grill-with-docs`](./skills/engineering/grill-with-docs/SKILL.md) - same as [`/grill-me`](./skills/productivity/grill-me/SKILL.md), but adds more goodies (see below)
+- [`/grill-me`](./skills/grill-me/SKILL.md) - for non-code uses
+- [`/grill-with-docs`](./skills/grill-with-docs/SKILL.md) - same as [`/grill-me`](./skills/grill-me/SKILL.md), but adds more goodies (see below)
 
 These are my most popular skills. They help you align with the agent before you get started, and think deeply about the change you're making. Use them _every_ time you want to make a change.
 
@@ -128,7 +128,7 @@ This concision pays off session after session.
 
 </details>
 
-This is built into [`/grill-with-docs`](./skills/engineering/grill-with-docs/SKILL.md). It's a grilling session, but that helps you build a shared language with the AI, and document hard-to-explain decisions in ADR's.
+This is built into [`/grill-with-docs`](./skills/grill-with-docs/SKILL.md). It's a grilling session, but that helps you build a shared language with the AI, and document hard-to-explain decisions in ADR's.
 
 It's hard to explain how powerful this is. It might be the single coolest technique in this repo. Try it, and see.
 
@@ -153,9 +153,9 @@ It's time to look at your feedback loops. Without feedback on how the code it pr
 
 For automated tests, a red-green-refactor loop is critical. This is where the agent writes a failing test first, then fixes the test. This helps give the agent a consistent level of feedback that results in far better code.
 
-I've built a **[`/tdd`](./skills/engineering/tdd/SKILL.md) skill** you can slot into any project. It encourages red-green-refactor and gives the agent plenty of guidance on what makes good and bad tests.
+I've built a **[`/tdd`](./skills/tdd/SKILL.md) skill** you can slot into any project. It encourages red-green-refactor and gives the agent plenty of guidance on what makes good and bad tests.
 
-For debugging, I've also built a **[`/diagnosing-bugs`](./skills/engineering/diagnosing-bugs/SKILL.md)** skill that wraps best debugging practices into a disciplined loop, gated phase by phase.
+For debugging, I've also built a **[`/diagnosing-bugs`](./skills/diagnosing-bugs/SKILL.md)** skill that wraps best debugging practices into a disciplined loop, gated phase by phase.
 
 ### #4: We Built A Ball Of Mud
 
@@ -173,9 +173,9 @@ For debugging, I've also built a **[`/diagnosing-bugs`](./skills/engineering/dia
 
 This is built in to every layer of these skills:
 
-- [`/to-spec`](./skills/engineering/to-spec/SKILL.md) quizzes you about which modules you're touching before creating a spec
+- [`/to-spec`](./skills/to-spec/SKILL.md) quizzes you about which modules you're touching before creating a spec
 
-And crucially, [`/improve-codebase-architecture`](./skills/engineering/improve-codebase-architecture/SKILL.md) surveys a codebase for deepening opportunities and hands you the candidates. I recommend running it on your codebase once every few days. It is a survey, not a rescue: on a genuinely old codebase it will find real candidates, but it won't untangle the mud for you.
+And crucially, [`/improve-codebase-architecture`](./skills/improve-codebase-architecture/SKILL.md) surveys a codebase for deepening opportunities and hands you the candidates. I recommend running it on your codebase once every few days. It is a survey, not a rescue: on a genuinely old codebase it will find real candidates, but it won't untangle the mud for you.
 
 ### Summary
 
@@ -191,27 +191,27 @@ Skills I use daily for code work.
 
 **User-invoked**
 
-- **[ask-matt](./skills/engineering/ask-matt/SKILL.md)** — Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo.
-- **[grill-with-docs](./skills/engineering/grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline.
-- **[triage](./skills/engineering/triage/SKILL.md)** — Move issues through a state machine of triage roles.
-- **[improve-codebase-architecture](./skills/engineering/improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
-- **[setup-matt-pocock-skills](./skills/engineering/setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills.
-- **[to-spec](./skills/engineering/to-spec/SKILL.md)** — Turn the current conversation into a spec and publish it to the issue tracker. No interview — just synthesizes what you've already discussed.
-- **[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 decision tickets on the issue tracker — resolve them one at a time until the way to the destination is clear.
+- **[ask-matt](./skills/ask-matt/SKILL.md)** — Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo.
+- **[grill-with-docs](./skills/grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline.
+- **[triage](./skills/triage/SKILL.md)** — Move issues through a state machine of triage roles.
+- **[improve-codebase-architecture](./skills/improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+- **[setup-matt-pocock-skills](./skills/setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills.
+- **[to-spec](./skills/to-spec/SKILL.md)** — Turn the current conversation into a spec and publish it to the issue tracker. No interview — just synthesizes what you've already discussed.
+- **[to-tickets](./skills/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/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/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 — resolve them one at a time until the way to the destination is clear.
 
 **Model-invoked**
 
-- **[prototype](./skills/engineering/prototype/SKILL.md)** — Build a throwaway prototype to answer a design question — a single shareable HTML file for state/logic questions, or several radically different UI variations toggleable from one route.
-- **[diagnosing-bugs](./skills/engineering/diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: build a feedback loop that goes red on this bug → minimise → hypothesise → instrument → fix → regression-test.
-- **[research](./skills/engineering/research/SKILL.md)** — Investigate a question against high-trust primary sources and capture the findings as a cited Markdown file in the repo, run as a background agent.
-- **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time.
-- **[domain-modeling](./skills/engineering/domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms against the glossary, stress-test with edge-case scenarios, and update `CONTEXT.md` and ADRs inline.
-- **[codebase-design](./skills/engineering/codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface.
-- **[code-review](./skills/engineering/code-review/SKILL.md)** — Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/spec?), run as parallel sub-agents so neither pollutes the other.
-- **[resolving-merge-conflicts](./skills/engineering/resolving-merge-conflicts/SKILL.md)** — Work through an in-progress git merge or rebase conflict hunk by hunk, resolving by intent traced to each side's primary source, then finish the operation — never `--abort`.
-- **[wizard](./skills/engineering/wizard/SKILL.md)** — Generate an interactive bash wizard that walks a human through steps only they can perform: provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover.
+- **[prototype](./skills/prototype/SKILL.md)** — Build a throwaway prototype to answer a design question — a single shareable HTML file for state/logic questions, or several radically different UI variations toggleable from one route.
+- **[diagnosing-bugs](./skills/diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: build a feedback loop that goes red on this bug → minimise → hypothesise → instrument → fix → regression-test.
+- **[research](./skills/research/SKILL.md)** — Investigate a question against high-trust primary sources and capture the findings as a cited Markdown file in the repo, run as a background agent.
+- **[tdd](./skills/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time.
+- **[domain-modeling](./skills/domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms against the glossary, stress-test with edge-case scenarios, and update `CONTEXT.md` and ADRs inline.
+- **[codebase-design](./skills/codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface.
+- **[code-review](./skills/code-review/SKILL.md)** — Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/spec?), run as parallel sub-agents so neither pollutes the other.
+- **[resolving-merge-conflicts](./skills/resolving-merge-conflicts/SKILL.md)** — Work through an in-progress git merge or rebase conflict hunk by hunk, resolving by intent traced to each side's primary source, then finish the operation — never `--abort`.
+- **[wizard](./skills/wizard/SKILL.md)** — Generate an interactive bash wizard that walks a human through steps only they can perform: provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover.
 
 ### Productivity
 
@@ -219,13 +219,13 @@ General workflow tools, not code-specific.
 
 **User-invoked**
 
-- **[grill-me](./skills/productivity/grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the design tree is resolved.
-- **[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.
+- **[grill-me](./skills/grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the design tree is resolved.
+- **[handoff](./skills/handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work.
+- **[teach](./skills/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/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/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.
 
 **Model-invoked**
 
-- **[grilling](./skills/productivity/grilling/SKILL.md)** — Interview the user relentlessly about a plan, decision, or idea until every branch of the design tree is resolved. The reusable interview primitive behind `grill-me`, `grill-with-docs`, `triage`, `wayfinder` and `improve-codebase-architecture`.
-- **[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.
+- **[grilling](./skills/grilling/SKILL.md)** — Interview the user relentlessly about a plan, decision, or idea until every branch of the design tree is resolved. The reusable interview primitive behind `grill-me`, `grill-with-docs`, `triage`, `wayfinder` and `improve-codebase-architecture`.
+- **[writing-for-agents](./skills/writing-for-agents/SKILL.md)** — Writing documents for agents: skills, AGENTS.md/CLAUDE.md, and any doc an agent reaches by a pointer.

docs/engineering/codebase-design.md

@@ -43,13 +43,13 @@ Depth is deliberately *not* defined as the ratio of implementation lines to inte
 - **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is the wrong shape.
 - **One adapter means a hypothetical seam. Two adapters means a real one.** Don't cut a seam until something actually varies across it. A single-adapter seam is just indirection.
 
-Two supporting files go further, and the skill reads them on demand rather than up front. [DEEPENING.md](https://github.com/mattpocock/skills/blob/main/skills/engineering/codebase-design/DEEPENING.md) classifies a candidate's dependencies — in-process, local-substitutable, remote-but-owned, true-external — because the category decides how the deepened module gets tested across its seam. [DESIGN-IT-TWICE.md](https://github.com/mattpocock/skills/blob/main/skills/engineering/codebase-design/DESIGN-IT-TWICE.md) spins up parallel [sub-agents](https://www.aihero.dev/ai-coding-dictionary/subagent) to produce three or more radically different interfaces for the same module, then compares them on depth, locality and seam placement.
+Two supporting files go further, and the skill reads them on demand rather than up front. [DEEPENING.md](https://github.com/mattpocock/skills/blob/main/skills/codebase-design/DEEPENING.md) classifies a candidate's dependencies — in-process, local-substitutable, remote-but-owned, true-external — because the category decides how the deepened module gets tested across its seam. [DESIGN-IT-TWICE.md](https://github.com/mattpocock/skills/blob/main/skills/codebase-design/DESIGN-IT-TWICE.md) spins up parallel [sub-agents](https://www.aihero.dev/ai-coding-dictionary/subagent) to produce three or more radically different interfaces for the same module, then compares them on depth, locality and seam placement.
 
 ## Common questions
 
 **How do I actually build a deep module in TypeScript?**
 
-This is the most-asked question about the skill and the skill does not answer it. It defines what a deep module *is*; it says nothing about how to stop a stray import from reaching past the interface. [Issue #458](https://github.com/mattpocock/skills/issues/458) put it plainly: "let's say we're happy with the interface, it hides the details, etc. But how do we enforce it? I think without linting or clear guardrails, humans and LLMs alike will start making it messy over time." Matt's answer, in that thread, was three options: wrap it in a class or IIFE and accept that the class gets enormous; make it a package in a monorepo and accept the monorepo tooling; or use a linter like [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) to forbid imports that bypass the interface. He has separately called Effect the best mechanism and dependency-cruiser the second-best. There is a `setup-ts-deep-modules` skill in the repo's `in-progress/` bucket that lays down a `src/packages/<name>/index.ts` convention, but it is a beta-channel skill with no docs page, and it has no lint rule shipped with it.
+This is the most-asked question about the skill and the skill does not answer it. It defines what a deep module *is*; it says nothing about how to stop a stray import from reaching past the interface. [Issue #458](https://github.com/mattpocock/skills/issues/458) put it plainly: "let's say we're happy with the interface, it hides the details, etc. But how do we enforce it? I think without linting or clear guardrails, humans and LLMs alike will start making it messy over time." Matt's answer, in that thread, was three options: wrap it in a class or IIFE and accept that the class gets enormous; make it a package in a monorepo and accept the monorepo tooling; or use a linter like [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) to forbid imports that bypass the interface. He has separately called Effect the best mechanism and dependency-cruiser the second-best. There is a `setup-ts-deep-modules` skill in the repo's `drafts/` folder that lays down a `src/packages/<name>/index.ts` convention, but it is a beta-channel skill with no docs page, and it has no lint rule shipped with it.
 
 **I pointed a session at it and it burned 100k [tokens](https://www.aihero.dev/ai-coding-dictionary/token) redesigning things I never asked about.**
 

docs/engineering/wizard.md

@@ -41,7 +41,7 @@ For each captured value, scoping settles where it lands:
 
 ## The template already solves the UX
 
-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 [template](https://github.com/mattpocock/skills/blob/main/skills/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, 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.
 
@@ -80,9 +80,9 @@ The artifact does, unconditionally: it's a plain bash script and it doesn't care
 
 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?**
+**It used to be a beta skill — where is it now?**
 
-`engineering/`, as of v1.2. It graduated out of the beta bucket and now ships in the plugin, so it arrives with the rest of the promoted set rather than needing an individual install. Its behaviour didn't change on graduation.
+Promoted, as of v1.2. It graduated out of the beta channel and now ships in the plugin, so it arrives with the rest of the promoted set rather than needing an individual install. Its behaviour didn't change on graduation.
 
 ## It's working if
 

drafts/README.md

@@ -1,6 +1,6 @@
-# In Progress
+# Drafts
 
-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.
+Beta. These skills are public on purpose — try them and tell me what breaks. They live outside `skills/`, so they're excluded from the plugin and the top-level README until they graduate, they get no docs pages, and they can change or disappear without warning.
 
 The plugin won't give you these. Install one directly:
 

extras/README.md

@@ -1,6 +1,6 @@
-# Misc
+# Extras
 
-Tools I keep around but rarely use — not promoted in the plugin.
+Tools I keep around but rarely use. They live outside `skills/`, so the plugin doesn't ship them.
 
 - **[git-guardrails-claude-code](./git-guardrails-claude-code/SKILL.md)** — Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, etc.) before they execute.
 - **[migrate-to-shoehorn](./migrate-to-shoehorn/SKILL.md)** — Migrate test files from `as` type assertions to @total-typescript/shoehorn.

plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "mattpocock-skills",
+  "version": "1.2.3",
+  "description": "Matt Pocock's agent skills for real engineering — grilling, spec/ticket flows, TDD, code review, domain modelling and more. Plug-and-play, not vibe coding.",
+  "author": {
+    "name": "Matt Pocock",
+    "url": "https://www.aihero.dev"
+  },
+  "homepage": "https://www.aihero.dev/s/skills-newsletter",
+  "repository": "https://github.com/mattpocock/skills",
+  "license": "MIT",
+  "keywords": [
+    "engineering",
+    "skills",
+    "tdd",
+    "code-review",
+    "grilling",
+    "domain-modeling",
+    "productivity"
+  ]
+}

scripts/link-skills.sh

@@ -5,7 +5,8 @@ set -euo pipefail
 # It is not a supported installer. Modifications to it — or requests for
 # modifications — will not be approved.
 #
-# Links all skills in the repository into the local skill directories used by
+# Links every skill in the repository — promoted (`skills/`) as well as
+# unpromoted (`drafts/`, `extras/`) — into the local skill directories used by
 # each agent harness:
 #   - ~/.claude/skills  — Claude Code
 #   - ~/.agents/skills  — Codex and other Agent Skills-compatible harnesses
@@ -22,7 +23,7 @@ while IFS= read -r -d '' skill_md; do
   src="$(dirname "$skill_md")"
   names+=("$(basename "$src")")
   srcs+=("$src")
-done < <(find "$REPO/skills" -name SKILL.md -not -path '*/node_modules/*' -not -path '*/deprecated/*' -print0)
+done < <(find "$REPO/skills" "$REPO/drafts" "$REPO/extras" -maxdepth 2 -name SKILL.md -not -path '*/node_modules/*' -print0)
 
 for DEST in "${DESTS[@]}"; do
   # If $DEST is a symlink that resolves into this repo, we'd end up writing the

scripts/sync-plugin-version.mjs

@@ -1,41 +1,55 @@
 #!/usr/bin/env node
-// Copies package.json's version into .claude-plugin/plugin.json.
+// Copies package.json's version into every plugin manifest:
+//   plugin.json                  — the Agent Plugins 1.0 manifest
+//   .claude-plugin/plugin.json   — the Claude Code manifest
 // Runs as part of `npm run version`, immediately after `changeset version`.
-// With --check it changes nothing and exits 1 if the two versions differ.
+// With --check it changes nothing and exits 1 if any version differs.
 
 import { readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const repo = join(dirname(fileURLToPath(import.meta.url)), "..");
-const pluginPath = join(repo, ".claude-plugin", "plugin.json");
+const manifests = [
+  join(repo, "plugin.json"),
+  join(repo, ".claude-plugin", "plugin.json"),
+];
 
 const { version } = JSON.parse(readFileSync(join(repo, "package.json"), "utf8"));
-const source = readFileSync(pluginPath, "utf8");
-const plugin = JSON.parse(source);
+const check = process.argv.includes("--check");
+let failed = false;
 
-if (plugin.version === version) {
-  console.log(`plugin.json version is ${version} — already in sync`);
-  process.exit(0);
-}
+for (const path of manifests) {
+  const name = relative(repo, path);
+  const source = readFileSync(path, "utf8");
+  const manifest = JSON.parse(source);
 
-if (process.argv.includes("--check")) {
-  console.error(
-    `plugin.json version is ${plugin.version}, package.json is ${version}. Run \`node scripts/sync-plugin-version.mjs\`.`,
+  if (manifest.version === version) {
+    console.log(`${name} version is ${version} — already in sync`);
+    continue;
+  }
+
+  if (check) {
+    console.error(
+      `${name} version is ${manifest.version}, package.json is ${version}. Run \`node scripts/sync-plugin-version.mjs\`.`,
+    );
+    failed = true;
+    continue;
+  }
+
+  // Rewrite only the version line, to keep the key order and the formatting.
+  const updated = source.replace(
+    /("version"\s*:\s*")[^"]*(")/,
+    `$1${version}$2`,
   );
-  process.exit(1);
+
+  if (JSON.parse(updated).version !== version) {
+    console.error(`Could not find a version field to replace in ${path}.`);
+    process.exit(1);
+  }
+
+  writeFileSync(path, updated);
+  console.log(`${name} version ${manifest.version} -> ${version}`);
 }
 
-// Rewrite only the version line, to keep the key order and the formatting.
-const updated = source.replace(
-  /("version"\s*:\s*")[^"]*(")/,
-  `$1${version}$2`,
-);
-
-if (JSON.parse(updated).version !== version) {
-  console.error(`Could not find a version field to replace in ${pluginPath}.`);
-  process.exit(1);
-}
-
-writeFileSync(pluginPath, updated);
-console.log(`plugin.json version ${plugin.version} -> ${version}`);
+process.exit(failed ? 1 : 0);

skills/deprecated/README.md

@@ -1,3 +0,0 @@
-# Deprecated
-
-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.

skills/domain-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: domain-modeling
-description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
+description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
 ---
 
 # Domain Modeling

skills/engineering/README.md

@@ -1,32 +0,0 @@
-# Engineering
-
-Skills I use daily for code work.
-
-## User-invoked
-
-Reachable only when you type them (Claude Code: `disable-model-invocation: true`; Codex: `policy.allow_implicit_invocation: false` in `agents/openai.yaml`).
-
-- **[ask-matt](./ask-matt/SKILL.md)** — Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo.
-- **[grill-with-docs](./grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline.
-- **[triage](./triage/SKILL.md)** — Move issues through a state machine of triage roles.
-- **[improve-codebase-architecture](./improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
-- **[setup-matt-pocock-skills](./setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo.
-- **[to-spec](./to-spec/SKILL.md)** — Turn the current conversation into a spec and publish it to the issue tracker.
-- **[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.
-
-## Model-invoked
-
-Model- or user-reachable (rich trigger phrasing so the model can reach for them).
-
-- **[prototype](./prototype/SKILL.md)** — Build a throwaway prototype to answer a design question: a single shareable HTML file for state/logic, or several toggleable UI variations.
-
-- **[diagnosing-bugs](./diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: build a feedback loop that goes red on this bug → minimise → hypothesise → instrument → fix → regression-test.
-- **[research](./research/SKILL.md)** — Investigate a question against high-trust primary sources and capture the findings as a cited Markdown file in the repo, run as a background agent.
-- **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time.
-- **[domain-modeling](./domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms, stress-test with scenarios, update `CONTEXT.md` and ADRs inline.
-- **[codebase-design](./codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: small interfaces, clean seams, testable through the interface.
-- **[code-review](./code-review/SKILL.md)** — Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/spec?), run as parallel sub-agents.
-- **[resolving-merge-conflicts](./resolving-merge-conflicts/SKILL.md)** — Work through an in-progress git merge or rebase conflict hunk by hunk, resolving by intent traced to each side's primary source, then finish the operation — never `--abort`.
-- **[wizard](./wizard/SKILL.md)** — Generate an interactive bash wizard that walks a human through steps only they can perform: provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover.

skills/grilling/SKILL.md

@@ -5,7 +5,7 @@ description: Grill the user relentlessly about a plan, decision, or idea. Use wh
 
 Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
 
-Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled — the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
 
 Each question should be formatted like so:
 
@@ -15,8 +15,8 @@ Each question should be formatted like so:
 ➡️ <your recommended answer>
 ```
 
-Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+Each round the user answers reshapes the tree — settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
 
-Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it — don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report — ask the rest of the frontier now. The _decisions_ are the user's — put each to them and wait.
 
 The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

skills/productivity/README.md

@@ -1,20 +0,0 @@
-# Productivity
-
-General workflow tools, not code-specific.
-
-## User-invoked
-
-Reachable only when you type them (Claude Code: `disable-model-invocation: true`; Codex: `policy.allow_implicit_invocation: false` in `agents/openai.yaml`).
-
-- **[grill-me](./grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the design tree is resolved.
-- **[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.
-
-## Model-invoked
-
-Model- or user-reachable (rich trigger phrasing so the model can reach for them).
-
-- **[grilling](./grilling/SKILL.md)** — Interview the user relentlessly about a plan, decision, or idea until every branch of the design tree is resolved.
-- **[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.