Wizard Skill FAQ: The Bash Script That Walks Humans Through Setup

Why a Wizard FAQ Exists#

Matt Pocock’s wizard skill generates a bash script that walks a human through steps only they can perform — provisioning infrastructure, pasting API keys, clicking through a vendor dashboard. It sounds niche until you count the setup tasks you re-explain to an agent every week. The SKILL.md is short (4 KB), but the real substance lives in template.sh (8.5 KB), which ships the entire wizard library: every helper, the STAGES marker, the closing summary. I read both files plus the skills.sh leaderboard on 2026-09-21; every answer above traces to one of them.

The Short Answers#

• It writes bash, not actions. A wizard opens URLs and captures values; the human does the clicking.
• Three authoring steps: scope the procedure, map each stage’s journey, author below the marker.
• Never edit the library. Everything above STAGES is identical across every wizard for a reason.
• Static verification only. Don’t run a wizard end-to-end; trace it instead.
• Ephemeral by default. Commit only when the repo should own the setup path.

What a Wizard Actually Is#

A wizard is the awkward middle ground between “the agent does everything” and “the README says click here, then here, then here.” The generated script opens each URL, says exactly what to click and copy, captures the values, writes them where they belong (.env, GitHub secrets), confirms at every stage, and shows how many stages remain. The skill’s own framing: “It might configure third-party services, run a one-off migration, or move the project from one state to another.”

The delightful UX is pre-solved — that’s the point of the template. Progress stages, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent .env upserts, gh secret and gh variable writes, a closing summary. The agent’s only job is scoping the procedure and authoring its stages. A wizard is a tiny product: the human’s time is the constraint, and every helper exists to make the human’s job smaller.

The Library vs. The Stages#

template.sh enforces a hard boundary. Above the marker: banner, stage, say, step, note, warn, open_url, pause, confirm, ask, ask_secret, write_env, set_secret, set_var, finish, plus _clear and _existing. Below it: TOTAL_STAGES and one stage block per manual step, in dependency order.

The consistency is load-bearing. A library that changes per wizard can’t be trusted; a library that’s identical everywhere gets audited once. The author contract is strict: copy template.sh, replace the example Stripe stage with real stages, set TOTAL_STAGES, and don’t touch anything above the marker. The template even ships an example (Stripe test keys → .env + CI secret) so the shape is unambiguous.

Secrets and CI: The Three Write Paths#

Every captured value lands somewhere, and the skill names exactly where. write_env upserts to .env — it greps out any existing KEY= line and rewrites the file, so re-runs never duplicate keys and an empty Enter keeps the current value. set_secret and set_var push to GitHub Actions through gh — secrets for values CI must not print, variables for non-secret config — and if gh isn’t authenticated, they append to a SKIPPED list that the finishing summary prints as explicit manual to-dos. ask_secret hides input with read -rs; nothing secret ever echoes.

That mapping is why the scoping step matters: every secrets.* reference in .github/workflows/* is a value the wizard must produce, and the static verification step checks each set_secret name against those references exactly.

Verification Without Running It#

Wizards block on human input and open browsers — so running one end-to-end is off the table. The skill substitutes static checks plus an audit: bash -n for syntax, shellcheck when present, chmod +x, then a trace that every value from the scoping pass actually lands where step 1 declared and every set_secret matches a CI reference. The test of a well-built wizard is that a stranger can run it without asking the agent anything — which is a higher bar than the agent running it once itself.

It slots into the same repo family as handoff — where one skill passes work to a human, this one builds the human a scripted path through the setup. Install with npx skills add https://github.com/mattpocock/skills --skill wizard. Next time provisioning needs a browser and a paste, that’s exactly what the wizard is for.