From 61accb0e66652cfe71da1266d49f1cbd129e3ae1 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 5 Aug 2026 13:02:28 +0100 Subject: [PATCH] skill: make wizard model-invoked MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The agent can now reach for wizard the moment it hits a step only a human can perform, instead of writing numbered instructions into the chat. Typing /wizard is unaffected — model-invocation only adds the agent's reach. The description is rewritten as the pointer that decides when it fires: a short statement of the artifact, four trigger branches, and an explicit non-trigger for steps the agent can perform itself. Behaviour is unchanged — same name, same template.sh, same four process steps, same stage-list confirmation, which now doubles as the proposal when the agent fires it mid-build. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/graduate-wizard.md | 2 +- .changeset/wizard-model-invoked.md | 9 +++++++++ README.md | 2 +- docs/engineering/wizard.md | 10 ++++++++-- skills/engineering/README.md | 2 +- skills/engineering/ask-matt/SKILL.md | 2 +- skills/engineering/wizard/SKILL.md | 3 +-- skills/engineering/wizard/agents/openai.yaml | 2 -- 8 files changed, 22 insertions(+), 10 deletions(-) create mode 100644 .changeset/wizard-model-invoked.md diff --git a/.changeset/graduate-wizard.md b/.changeset/graduate-wizard.md index da04f98..c51bd3b 100644 --- a/.changeset/graduate-wizard.md +++ b/.changeset/graduate-wizard.md @@ -8,4 +8,4 @@ The delightful UX is pre-solved by the bundled `template.sh` (progress with time 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. +Now wired as a promoted skill — plugin entry, top-level + Engineering READMEs under **Model-invoked**, a docs page at `docs/engineering/wizard.md`, and a Standalone route in `ask-matt` for the steps only a human can take. diff --git a/.changeset/wizard-model-invoked.md b/.changeset/wizard-model-invoked.md new file mode 100644 index 0000000..bef1d3f --- /dev/null +++ b/.changeset/wizard-model-invoked.md @@ -0,0 +1,9 @@ +--- +"mattpocock-skills": minor +--- + +Make **`wizard`** model-invoked. The agent can now reach for it the moment it hits a step only a human can perform, instead of dumping numbered instructions into the chat and hoping you follow them. Typing `/wizard` works exactly as before — model-invocation only ever *adds* the agent's reach. + +The description is rewritten as the pointer that decides when it fires: a short statement of what it produces, four trigger branches (provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, a one-off migration or cutover), and an explicit non-trigger — don't invoke it for steps the agent can perform itself. Work an agent can do, an agent should do; the wizard is for the clicks, approvals and dashboard trips you would not hand to one. + +Nothing else changed. Same name, same `template.sh`, same four process steps, same stage-list confirmation before a line is written — which now doubles as the proposal when the agent fires it mid-build. Also moved to **Model-invoked** in both READMEs, and out of the reach of [#693](https://github.com/mattpocock/skills/issues/693), which drops user-invoked skills from the listing on Claude's desktop and web surfaces. diff --git a/README.md b/README.md index f3a547a..828569c 100644 --- a/README.md +++ b/README.md @@ -200,7 +200,6 @@ 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 decision 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** @@ -212,6 +211,7 @@ Skills I use daily for code work. - **[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. ### Productivity diff --git a/docs/engineering/wizard.md b/docs/engineering/wizard.md index 32c3939..1c645c7 100644 --- a/docs/engineering/wizard.md +++ b/docs/engineering/wizard.md @@ -6,7 +6,7 @@ You reach for it only where a human is genuinely in the loop. If the agent could ## When to reach for it -You invoke this by typing `/wizard` — the agent won't reach for it on its own. +You can type `/wizard`, and the agent can also reach for it on its own. When it hits a step only you can perform — a key it can't mint, a dashboard it can't click — it builds you a wizard instead of writing the instructions into the chat, where they scroll away. Reach for it when the next thing blocking you is a human clicking through a dashboard: @@ -78,7 +78,13 @@ Nowhere in particular. It's a standalone, not a chain step. The common guess is **Does it work outside Claude Code?** -The artifact does, unconditionally: it's a plain bash script and it doesn't care what harness generated it. The skill itself is user-invoked, so you type `/wizard` in Claude Code or `$wizard` in Codex. One known gap — on Claude's desktop and web surfaces, which run in coordinator mode, every user-invoked skill is dropped from the model's listing entirely, so the assistant tells you `/wizard` isn't installed when it is. The plain `claude` CLI is unaffected. The tracking issue is [#693](https://github.com/mattpocock/skills/issues/693); the fix belongs in the harness. +The artifact does, unconditionally: it's a plain bash script and it doesn't care what harness generated it. The skill itself is model-invoked, so it's listed everywhere — type `/wizard` in Claude Code or `$wizard` in Codex, or just describe the setup you're stuck on. Being model-invoked also keeps it clear of [#693](https://github.com/mattpocock/skills/issues/693), where Claude's desktop and web surfaces drop *user-invoked* skills from the model's listing and report them as not installed. + +**Didn't this used to be user-invoked?** + +It did. It's now model-invoked, so the agent reaches for it unprompted when it hits a step only you can take. Nothing you could do before stopped working — model-invocation *adds* the agent's reach, it never removes yours, so `/wizard` behaves exactly as it did. What changed is the failure mode it retires: the agent hitting a credentials wall mid-build and dumping six numbered steps into the chat for you to follow by hand. + +The guard against the opposite failure is in the description itself — don't invoke it for steps the agent can perform itself. Work an agent can do, an agent should do. **It used to be in `in-progress/` — where is it now?** diff --git a/skills/engineering/README.md b/skills/engineering/README.md index a0e06bd..4a948b8 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -15,7 +15,6 @@ 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 @@ -30,3 +29,4 @@ Model- or user-reachable (rich trigger phrasing so the model can reach for them) - **[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. diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md index 147b6ab..7f3ab78 100644 --- a/skills/engineering/ask-matt/SKILL.md +++ b/skills/engineering/ask-matt/SKILL.md @@ -80,7 +80,7 @@ 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 is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/` branch out of main, pointed at from the implementation issue. 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. +- **`/wizard`** — for the steps only a **human** can take: provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party dashboard, running a one-off migration or cutover. 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. Model-invoked, so the agent reaches for it the moment it hits a wall only you can pass. If the agent could just do it itself, it should; this is for where a human is genuinely in the loop. - **`/wait-what`** — the corrective for a message that didn't land. Use 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 works after the fact; `/grill-with-docs` is 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. diff --git a/skills/engineering/wizard/SKILL.md b/skills/engineering/wizard/SKILL.md index a754784..7c42dbd 100644 --- a/skills/engineering/wizard/SKILL.md +++ b/skills/engineering/wizard/SKILL.md @@ -1,7 +1,6 @@ --- name: wizard -description: 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, confirming each step, and writing .env files and GitHub Actions secrets. -disable-model-invocation: true +description: Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself. --- # Wizard diff --git a/skills/engineering/wizard/agents/openai.yaml b/skills/engineering/wizard/agents/openai.yaml index 0a5f4b1..b601bdf 100644 --- a/skills/engineering/wizard/agents/openai.yaml +++ b/skills/engineering/wizard/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: "Wizard" short_description: "Generate an interactive setup wizard" -policy: - allow_implicit_invocation: false