wizard skill

How a wizard session runs, step by step

The skill splits the work into four phases. Each phase ends with a stated "done when" condition, which tells you when the agent is ready to move on.

1. Scope the procedure. For a setup task, the agent reads .env, .env.example, .env.*, the README, docker-compose*, framework config and .github/workflows/*. For a migration or cutover, it works out the current state, the target state and the irreversible actions between them. It then shows you the ordered stages. You can add, drop or reorder them. This phase is done when the agent knows three things about every captured value: where you get it, where it is written (.env, a GitHub secret, both, or nowhere, since some stages are pure actions), and whether it is secret or public.
2. Map each stage's journey. The agent writes the click path for each stage, for example "Dashboard → Developers → API keys → Reveal test key → copy". If it does not know the current UI or the exact command, it should ask you or check the docs. This phase is done when a stranger could follow every stage.
3. Author the wizard. The agent copies template.sh to the target path and replaces the example stage with one stage per step, in dependency order. It also sets TOTAL_STAGES to match the number of stages.
4. Verify and hand off. The agent runs syntax and lint checks, makes the script executable and tells you how to run it.

Example requests that fit the skill's description:

• "Write a wizard that walks me through creating the API keys this repo needs and puts them in .env and GitHub secrets."
• "I need to move this project from one hosting setup to another. Build a wizard for the cutover, with a confirmation before anything irreversible."
• "Our README setup section is long. Turn it into a wizard we can commit."

You will get better results if you correct the stage list in phase 1. That is the point where the agent asks you to confirm, and every later phase builds on that list.

Template helpers and the rules for writing stages

The skill folder holds three files: SKILL.md, agents/openai.yaml and template.sh. Everything above the STAGES marker in template.sh is the same library in every wizard. The skill tells the agent never to hand-edit it. The agent writes only the stage section, using these helpers:

The skill also sets rules for using these helpers:

• Open the URL before asking for the value that page shows.
• Use ask_secret for anything secret.
• Call write_env for every value that should persist.
• Use set_secret only for values CI actually needs, not for every captured value.
• Call confirm before any irreversible action.
• Keep each stage to one focused task. The screen clears at each stage, so anything the person still needs from an earlier stage will be gone.

Prerequisites and checking a generated wizard

A wizard is a bash script, so you need bash. The GitHub CLI (gh) is optional and only matters for stages that write secrets or variables. Without it, values can still go to .env. If shellcheck is installed, the agent runs it during verification. If not, the agent relies on bash -n alone.

The agent does not run the finished wizard itself. Instead it traces the script statically. Every value from the scoping phase must be captured and end up where that phase said it would. Every set_secret name must exactly match a secrets.* reference in the CI workflows. You can repeat that check yourself before you run anything. Open the stage section, list each set_secret name, and search .github/workflows/ for the same names. A mismatch means CI will look for a secret the wizard never created.

The template's comments describe how ask behaves on re-runs. It offers the existing .env value as the default, so pressing Enter keeps it. Together with idempotent .env writes, this makes it reasonable to run a wizard a second time after you fix one stage. The same comment says ask fails at end of input when it gets nothing. Run the script in an interactive terminal, not with piped or redirected input.

If you commit a wizard as the repeatable setup path, the skill suggests linking it from the README. That way the next person runs the script instead of asking an AI to explain the setup again.