Question 1

What does the wizard skill actually do?

Accepted Answer

It generates an interactive bash script — a 'wizard' — that walks a human, step by step, through a manual procedure only they can perform: provisioning infrastructure, setting up credentials or CI secrets, navigating an unfamiliar third-party dashboard, or running a one-off migration or cutover. The agent authors the stages; the human drives the browser and pastes values back. It sits in mattpocock/skills at skills/engineering/wizard/ with 392.6K all-time installs (rank 133 on skills.sh on 2026-09-21).

Question 2

When should I use it — and when not?

Accepted Answer

Use it when a procedure is tedious to do by hand and tedious to re-explain to an agent every time, and the steps genuinely require a human: browser dashboards, secret entry, irreversible confirmations. Don't invoke it for steps the agent can perform itself. The skill's trigger list: provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, running a one-off migration or cutover.

Question 3

What does a generated wizard look like when run?

Accepted Answer

A banner lists the total stages, then each stage clears the screen and shows one focused task: the URL to open, exactly what to click and copy, and where the captured value lands. open_url opens the page in the human's browser, ask and ask_secret collect values, confirm gates anything irreversible, and a finishing summary lists .env values written, GitHub secrets set, and anything skipped. Interrupt with Ctrl-C and re-run later — it remembers values already saved.

Question 4

What is the 'library above the STAGES marker'?

Accepted Answer

template.sh splits at a marker. Everything above it is a wizard library that is identical in every generated wizard — banner, stage, say, step, note, warn, open_url, pause, confirm, ask, ask_secret, write_env, set_secret, set_var, finish, plus _clear and _existing helpers. Everything below is the author's stages. The skill is explicit: never hand-edit the library; the agent's whole job is scoping the procedure and authoring the stages below the marker.

Question 5

How does the authoring process work?

Accepted Answer

Three steps. Scope: read the repo first — .env, .env.example, README, docker-compose, and every workflow file, because each secrets.* or vars.* reference is a value the wizard must produce — then list the ordered stages and confirm with the user, who may add, drop, or reorder. Map: for each stage write the precise journey (URL to open, what to do, where the value appears, which variable it fills). Author: copy template.sh, replace the example stage with one stage per step, set TOTAL_STAGES to match, and verify.

Question 6

How does the agent verify a wizard it can't run?

Accepted Answer

It must not run it end-to-end — wizards open browsers and block on human input. Instead: bash -n for syntax, shellcheck when available, chmod +x, then a static trace — every value from the scoping step lands where step 1 said it would (including the right ENV_FILE), and every set_secret name exactly matches a secrets.* reference in CI. The skill's bar: a stranger should be able to follow the stages without asking the agent anything.

Question 7

How are secrets handled?

Accepted Answer

ask_secret reads input hidden from the terminal. write_env upserts KEY=VALUE into the .env file idempotently — it replaces any existing line and keeps the current value as a default on re-runs. set_secret writes only the values CI actually needs, pushing them via gh, and records a SKIPPED warning with the exact manual command if gh is missing or unauthenticated, so the human gets a to-do list in the finishing summary.

Question 8

What are the common traps?

Accepted Answer

Inventing UI steps that may not exist — if you don't know the current dashboard, say so and check the docs instead. Asking the user cold instead of reading the repo first. Bundling several actions into one stage, since each stage clears the screen. Skipping confirm() before irreversible actions. And committing an ephemeral one-off wizard that was meant to be thrown away after the job.

Question 9

Is a wizard ephemeral or committed?

Accepted Answer

Ephemeral by default: built for one run, saved to a scratch or scripts/ path, deleted when the job is done. Commit it only when the user wants a repeatable setup path that should live in the repo — then link it from the README so the next person runs the script instead of asking an agent. The template's closing line makes the same point: 'only the stages below this marker are yours.'

Question 10

Is the 392.6K install number real?

Accepted Answer

Yes. skills.sh on 2026-09-21 showed wizard at #133 with 392,600 all-time installs and a weekly series of 19,850, 42,981, 41,317, 44,161, 41,947, 41,252, 37,335, 34,729 — a peak near 44K about seven weeks back, now settling in the mid-30K band. The repo pushed on 2026-09-18, and the skill's SKILL.md reads only 4 KB while template.sh carries 8.5 KB of the actual UX.

Bash on Top AI Skills

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

Frequently Asked Questions

Why a Wizard FAQ Exists