Wizard - Generate Interactive Bash Operation Guides

Skill Overview

The Wizard skill turns manual processes that only humans can complete into an interactive Bash wizard script: it opens URLs one by one, explains what to click and which value to copy, writes captured keys to .env and GitHub Secrets, and provides confirmation and progress prompts at every stage.

Applicable Scenarios

1. Infrastructure provisioning and credential configuration: When a new project needs cloud services enabled, API keys obtained, or database connections configured, use a wizard to combine scattered configuration steps into a single, progress-tracked flow and avoid having to explain everything from scratch each time.
2. CI secrets and variable configuration: Trace all secrets.* and vars.* references from .github/workflows/*, guide users through retrieving each value from the corresponding console, write them using gh secret / gh variable, and finally verify that the names match exactly.
3. Working with unfamiliar third-party consoles: When facing an unfamiliar console interface ("Dashboard → Developers → API keys → Reveal → Copy"), the wizard opens the page first and then clearly explains the navigation path, allowing first-time users to complete the process.
4. One-time migrations and cutovers: For database migrations, provider switches, and environment cutovers—operations performed only once and difficult to roll back—add confirmation gates before destructive actions.
5. Team member onboarding: Put local environment initialization into a script in the repository so the next person can run it directly instead of asking the AI again.

Core Features

1. Ready-to-use template.sh library: Staged progress, confirmation gates, cross-platform URL opening (including WSL), hidden secret input, idempotent .env upserts, writing via gh secret / gh variable, and a final summary—the library already handles these UX details in the template. The library code above the STAGES marker remains completely identical in every wizard and requires no manual changes; authors only need to write the stage content.
2. Scope analysis based on repository facts: First read .env, .env.example, README files, docker-compose*, framework configuration, and .github/workflows/*; infer from the code which values must be provided manually, where each value comes from, where it should be written, and whether it is a secret. Then output an ordered list of stages for confirmation.
3. Controlled generation and validation process: Each stage does exactly one thing at a time (after clearing the screen, it displays only the current step). After generation, run bash -n and shellcheck, apply chmod +x, and use static checks to confirm that every value is captured and that each set_secret name corresponds one-to-one with the secrets.* references in CI.

Frequently Asked Questions

What is the difference between the Wizard skill and writing a configuration document?

A document requires people to read it and make their own decisions, whereas a wizard guides them step by step: it opens pages for them, tells them where to retrieve values, writes those values directly to .env or GitHub Secrets, and confirms each step while showing how many stages remain. If a document omits a step, the reader may get stuck; if a wizard omits one, the script reports an error and exposes the problem earlier.

How is it different from asking the AI to configure everything directly?

The boundary is clear: steps the AI can perform itself should not use a wizard. Operations that require signing into an account, clicking authorization buttons in a browser, copying secrets visible only to you, or making human judgments cannot be performed by the AI and are therefore worth turning into a wizard. A wizard does not replace automation; it handles the portion that automation cannot cover.

Does the generated script need to be committed to the repository?

By default, no. A wizard is intended to be "use once and discard": generate it in a temporary directory or under scripts/, run it, and delete it afterward. Only commit it to the repository when the configuration process will recur and you want everyone on the team to follow the same path. Link to it from the README so the next person can run the script directly instead of asking the AI again.

Will secrets be written in plaintext into the script?

No. The script itself stores no secrets. It only hides input echo while you enter them (ask_secret), then writes the values to .env or GitHub Secrets. Whether a value is synchronized to CI follows the principle of least privilege—set_secret is called only for values that CI actually needs.

What should I do if the script is interrupted halfway through?

Run it again. .env writes use idempotent upserts, so repeated execution will not create duplicate entries. Each stage is independently reentrant; when rerun after an interruption, it will continue from the corresponding stage, and existing values will appear as defaults.