Setup Wizard Generator: Interactive Bash Onboarding Scripts

The Setup Wizard Generator is an optional Hermes Agent skill that produces an interactive bash script walking a human through a manual procedure one step at a time. Reach for it when a task requires dashboard clicks, credential capture, or irreversible human-gated actions that the agent cannot perform on its own. It is ported from the MIT-licensed wizard skill in mattpocock/skills.

What it does

The skill generates a wizard: a bash script that opens each URL in sequence, tells the human exactly what to click and copy, captures the values they paste back, and writes those values where they belong, such as a .env file or GitHub secrets. It confirms at every stage and shows how many stages remain, so the person running it always knows where they are in the procedure.

The output is a script, not a service. You author it, hand it to whoever needs to run the setup, and delete it once the job is done, unless the user wants a repeatable path committed to the repo.

Before you start

• bash is required. The gh CLI is only needed if your stages write GitHub secrets or variables.
• The library template lives at templates/template.sh inside this skill's directory. You copy it to your target path and author below the STAGES marker.
• Platforms: linux and macos.
• Tier: optional, installed on demand. Skill path: optional-skills/devops/setup-wizard-generator. Version 1.0.0, MIT licensed.

Scoping the procedure

Before writing any bash, work out every manual step the human must take and every value captured along the way. Read the repo first rather than asking cold. For setup work, inspect .env, .env.example, README, docker-compose*, framework config, and .github/workflows/*. Every secrets.* or vars.* reference in a workflow is a value the wizard must produce. For migrations or cutovers, map the current state, the target state, and the irreversible actions between them.

Show the user the ordered stage list and the values each stage produces. They may add, drop, or reorder stages. You are done scoping when every stage is named in order and, for each captured value, you know three things: where the human gets it, where it gets written (.env, a GitHub secret, both, or nowhere), and whether it is secret (hidden entry) or public.

Mapping each stage's journey

For each stage, write the precise path a human follows: which URL to open, what to do there, and where the value is shown. A typical path reads like "Dashboard → Developers → API keys → Reveal test key → copy". Where you do not know the current UI or the exact command, say so and check the docs or ask. Never invent steps that may not exist.

Authoring the wizard

Copy templates/template.sh from this skill's directory to the target path. Replace the example stage with one stage per step, in dependency order. Set TOTAL_STAGES to the number of stages you wrote.

The library provides these helpers: stage, say/step/note/warn, open_url, ask/ask_secret, write_env, set_secret/set_var, pause/confirm, banner, and finish. Everything above the STAGES marker is the wizard library and is identical in every wizard. Never hand-edit it; that consistency is the point.

Hold the bar the template sets. Open the URL before asking for its value. Use ask_secret for anything secret. Call write_env for every persisted value. Use set_secret only for what CI actually needs. Call confirm before anything irreversible. Each stage clears the screen, so keep one focused task per stage and nothing the human needs will scroll away.

A wizard is ephemeral by default. Save it to a scratch or scripts/ path and delete it when the job is done. Commit it only when the user wants a repeatable setup path living in the repo.

Verifying and handing off

Run bash -n on the script, run shellcheck if it is available, and chmod +x the file. Do not run the wizard end-to-end yourself: it opens browsers and blocks on human input. Instead, trace it statically. Confirm that every value from the scoping step is captured and lands where you said it would, and that every set_secret name exactly matches a secrets.* reference in CI.

Tell the user how to run it. If the procedure is repeatable, commit the script and link it from the README.

When not to use it

Do not use this skill for steps the agent can perform itself. If the agent can run the command or make the API call directly, do that instead. The wizard exists for the human-gated parts: dashboard clicks, credential reveals, and irreversible confirmations.

Limits and gotchas

1. Editing the library section. Everything above the STAGES marker is the wizard library. Author only below it.
2. Inventing dashboard paths. Third-party UIs drift. If you are unsure of the click path, verify against current docs or flag it as approximate.
3. set_secret for values CI doesn't use. Only push to GitHub secrets what a workflow actually references.
4. Running the wizard yourself. It blocks on human input. Static tracing plus bash -n is the verification.
5. One mega-stage. Screen clearing per stage means a long stage scrolls critical instructions away. Split it.

Verification checklist

• Stage list confirmed with the user before authoring
• bash -n passes and the script is executable
• Every captured value traced to its declared destination
• Every set_secret name matches a CI secrets.* reference
• Library section untouched from the template

What pairs with this

This skill sits in the DevOps category alongside other optional skills for provisioning and CI work. If your stages write GitHub secrets or variables, you will need the gh CLI available. For repeatable setups, commit the wizard and link it from the README so teammates can run the same path.