wizard

Generated source view for the actual executable engineering/wizard skill. The durable routing article is Cloud, Data, and Service Skills. Source: skills/engineering/wizard/SKILL.md

Runtime Source

Bundled Resources

These files are part of the executable skill folder and must be preserved with the skill source.

Description

Generate an interactive bash wizard that walks a human through a manual setup, third-party service configuration, one-off migration, or A-to-B state transition. Use when Kevin invokes /wizard or explicitly asks for an interactive CLI that opens URLs, captures values, writes .env entries, sets GitHub secrets/vars, and confirms each step.

Skill Source

---
name: wizard
description: Generate an interactive bash wizard that walks a human through a manual setup, third-party service configuration, one-off migration, or A-to-B state transition. Use when Kevin invokes /wizard or explicitly asks for an interactive CLI that opens URLs, captures values, writes .env entries, sets GitHub secrets/vars, and confirms each step.
origin: personal
source_slug: wizard
upstream_slug: wizard
disable-model-invocation: true
---

# Wizard

A **wizard** is a small bash script that turns a tedious manual procedure into a human-driven CLI. It opens the right URLs, tells the human exactly what to click or copy, captures values, persists them to `.env`, optionally writes GitHub Actions secrets/vars, confirms each stage, and prints a final summary.

Use this for setup and transitions where the agent cannot safely complete the whole job alone because a human must authenticate, copy secrets, approve irreversible actions, or operate a third-party dashboard.

Do not use it for normal implementation work, routine repo scripts, or a stable product onboarding flow. A wizard is ephemeral by default. Commit it only when the setup path should be repeatable for the repo.

Upstream provenance: adapted from `github.com/mattpocock/skills/skills/in-progress/wizard/SKILL.md` at `7a83a3a682adf699f24dbc06613de87f4e52a0a0`.

## Process

### 1. Scope the procedure

Read the repo first. Do not ask cold.

For service setup, inspect:

- `.env`, `.env.example`, `.env.*`
- `README*`
- `docker-compose*`
- framework config
- `.github/workflows/*` for every `secrets.*` and `vars.*` reference

For a migration or state transition, inspect the current state, target state, and every irreversible or externally visible action between them.

Then show Kevin:

- ordered stages
- values each stage captures
- where each value is written
- which values are secret
- estimated time
- any irreversible action gates

Continue only after the stage list is confirmed.

Done when every captured value has a source, destination, and secrecy classification.

### 2. Map each stage's journey

For every stage, write concrete human instructions:

- URL to open
- dashboard path or command to run
- exact value to copy
- target variable name
- whether to write `.env`, GitHub secret, GitHub var, or nowhere
- confirmation gate before destructive actions

If the dashboard path or current UI is unknown, check docs or ask Kevin. Do not invent vendor UI steps. Wrong wizards are worse than no wizard. Tiny glass maze, except the glass is also on fire.

Done when a stranger could complete each stage without asking what to click next.

### 3. Author the wizard

Copy [`references/template.sh`](references/template.sh) to the target path, usually one of:

- `.scratch/<task>/wizard.sh` for one-off setup
- `scripts/setup-<service>.sh` for repeatable repo setup
- `scripts/migrate-<state>.sh` for a repeatable migration

Use the template helpers:

- `stage`, `say`, `step`, `note`, `warn`
- `open_url`
- `ask`, `ask_secret`
- `write_env`
- `set_secret`, `set_var`
- `pause`, `confirm`

Set `TOTAL_STAGES` and `TOTAL_MINUTES` honestly. Each `stage` should be one focused task. Open the URL before asking for a value. Use `ask_secret` for secrets. Use `confirm` before irreversible actions.

Do not edit the library above the `STAGES` marker unless you are deliberately updating the template itself.

### 4. Verify and hand off

Run:

```bash
bash -n <script>
chmod +x <script>
```

Run `shellcheck <script>` if available.

Do not run the wizard end-to-end yourself unless Kevin explicitly asks. It opens browsers, blocks on human input, and may set secrets. Instead, trace it statically:

- every value from the confirmed scope is captured
- every persisted value lands at the confirmed destination
- every `set_secret` name matches a `secrets.*` reference or a confirmed CI need
- every destructive action has `confirm`
- reruns preserve existing `.env` values

Hand off with the run command and what the wizard will write.

## Commit Rule

For one-off wizards, leave the script in `.scratch/` or delete it after use.

For repeatable setup paths, commit the script and link it from the repo README or setup docs so the next human runs the wizard instead of asking an agent to rediscover the flow.

## Related Skills

- `setup-kevin-engineering-flow` - configures repo issue/domain docs for Kevin's engineering skills.
- `agent-docs` - enrolls or refreshes repo-level agent documentation.
- `skill-creator` - create or prune durable skills when a wizard pattern becomes reusable.
- `service-cli-registry` - find first-party CLIs before hand-writing API setup.

---

Timeline

• 2026-07-15 | Generated a browseable source page from the actual executable skill file. Source: skills/engineering/wizard/SKILL.md