wizard

$npx mdskill add e2b-dev/herdr-e2b-sandbox/wizard

Generate interactive bash wizards that guide humans through manual setup steps.

  • Solves tedious manual procedures like provisioning infrastructure, setting credentials, or walking third-party dashboards.
  • Depends on bash, template.sh, and optionally gh CLI for GitHub secrets and variables.
  • Scopes the procedure and authors stages, leaving the shared wizard library untouched.
  • Delivers a runnable script with progress tracking, confirmation gates, and .env or secret writes.

SKILL.md

.github/skills/wizardView on GitHub ↗
---
name: wizard
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

A **wizard** is a bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an AI every time. It 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 are left. It might configure third-party services, run a one-off migration, or move the project from one state to another.

The delightful UX is already solved by [template.sh](template.sh) — stage-by-stage progress, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes, and a closing summary. **Your job is only to scope the procedure and author its stages.** The library above the `STAGES` marker is identical in every wizard; that consistency is the point — never hand-edit it.

A wizard is ephemeral by default — built for one run, saved to a scratch or `scripts/` path, deleted when the job's done. Commit it only when the user wants a repeatable setup path that should live in the repo.

## Process

### 1. Scope the procedure

Work out every manual step the human must take and every value that gets captured along the way. Read the repo first — don't ask cold:

- For setup: `.env`, `.env.example`, `.env.*`, `README`, `docker-compose*`, framework config, and `.github/workflows/*` (every `secrets.*` / `vars.*` reference is a value the wizard must produce).
- For a migration or transition: the current state, the target state, and the irreversible actions between them.

Then show the user the ordered list of stages and the values each produces, and confirm — they may add, drop, or reorder.

**Done when:** every stage is named in order, and for each captured value you know (a) where the human gets it, (b) where it's written (`.env`, a GitHub secret, both, or nowhere — some stages are pure actions), and (c) whether it's secret (hidden entry) or public.

### 2. Map each stage's journey

For each stage, write the precise path a human follows: which URL to open, what to do there, where a value is shown, which variable it fills — e.g. "Dashboard → Developers → API keys → Reveal test key → copy". Where you don't actually know the current UI or the exact command, say so and ask the user or check the docs — never invent steps that may not exist.

**Done when:** every stage traces to concrete instructions a stranger could follow.

### 3. Author the wizard

Copy `template.sh` to the target path. Replace the example stage with one `stage` per step, in dependency order. Use the library helpers — `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `pause`/`confirm` — and set `TOTAL_STAGES` to the number of stages you wrote.

Hold the bar the template sets: open the URL before asking for its value, use `ask_secret` for anything secret, `write_env` every persisted value, `set_secret` only the values CI actually needs, and `confirm` before any irreversible action. Each `stage` clears the screen so only the current step is visible — keep a stage to one focused task so nothing the human needs scrolls away. Don't touch the library above the marker.

### 4. Verify and hand off

- `bash -n <script>`; run `shellcheck` if available.
- `chmod +x <script>`.
- Don't run it end-to-end yourself — it opens browsers and blocks on human input. Trace it statically instead: every value from step 1 is captured and lands where step 1 said, and every `set_secret` name exactly matches a `secrets.*` reference in CI.
- Tell the user how to run it. If it's a repeatable setup path, commit it and link it from the README so the next person runs the script instead of asking an AI.

More from e2b-dev/herdr-e2b-sandbox

SkillDescription
ask-mattAsk which skill or flow fits your situation. A router over the skills in this repo.
e2b-boxDrive the herdr-e2b plugin — e2b-box, e2b-fleet, e2b-bench, e2b-dash — from the CLI, the way an agent orchestrator (or a human without the keybindings) uses it. Two workflows it maps: (1) you already have a worktree and want its work mirrored into an E2B cloud sandbox (e2b-box open/sync/pull, one box per worktree), and (2) you want ONE task fanned out from the current checkout to several coding agents at once — claude, codex, opencode, amp, grok, droid, prime, muse — each in its own auto-created worktree + sandbox (e2b-fleet), then monitored, graded with a held-out check (e2b-bench), and the best result pulled back (best-of-n). Use whenever the user mentions e2b-box, e2b-fleet, e2b-bench, fleets, "run the same task on claude and codex", "fan this out to N agents", "send this worktree to a sandbox", "move my work to the cloud box", "grade the fleet", "best of n agents", "pull the winner", or presses/asks about prefix+shift+E / prefix+shift+F / prefix+shift+D in herdr. Also use when orchestrating these commands yourself as the agent instead of the human.
herdr-e2b-benchBuild and run a coding-agent shootout in this repo — one task, N agents (claude, codex, opencode, amp, grok, droid, prime, muse), each in its own E2B sandbox, graded by a held-out test and compared on tokens, cost, wall clock and diff size. Takes one argument. `create` authors a new benchmark task: the brief (bench/BENCH.md), the held-out grader (bench/grade.sh), and the reusable measurement scripts (bench/usage.sh, bench/judge.sh, bench/README.md), then calibrates the grader by measuring its floor and its ceiling. `execute` drives an existing benchmark: fan out with e2b-box fleet, grade with e2b-bench, table with usage.sh, blind-judge with judge.sh, tear down. `quick` is `execute` on the fast task pair (bench/BENCH-quick.md + bench/grade-quick.sh) — ~5 minutes of agent time and a ~1s grader, for when you are testing the harness rather than the agents. Use this skill whenever the user mentions a bench, benchmark, shootout, race, "which agent is better", harness-bench, bench/BENCH.md, bench/grade.sh, held-out test, grading a fleet, best-of-n, or wants to compare coding agents on the same task, or says quick bench, fast bench, short bench, smoke bench, quick lap, or asks for a bench that does not take an hour — and also whenever they ask to add, change, calibrate, or score a benchmark task in this repo, or to run one for a demo recording. Prefer this over improvising e2b-fleet and e2b-bench calls by hand, because the held-out mechanics and the grader calibration are easy to get subtly wrong.
resolving-merge-conflictsUse when you need to resolve an in-progress git merge/rebase conflict.
to-questionnaireTurn a decision you can't fully answer into a questionnaire for someone else to fill in.
to-specTurn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
wait-whatStop. That last message did not land — re-pitch it.
wayfinderPlan a huge chunk of work — more than one agent session can hold — as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
writing-for-agentsWriting documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.