human-step-wizard
Generate an interactive, resumable bash wizard that walks a person through steps only a human can do
Install / Use
npx skills add borghei/Claude-Skills --skill human-step-wizardInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AutomationSupported Platforms
Tags
Our assessment of human-step-wizard
human-step-wizard scores 89/100 on our quality scale, 1409th of 2,790 Automation skills we index.
Its SKILL.md is 13 KB long, well organised into 24 sections with 5 code examples: a thorough specification that gives an agent plenty to work with.
It has 817 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so human-step-wizard is actively maintained.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-10. Automated pattern scan on 2026-11-10. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
human-step-wizard compared with similar skills
All 4 of these similar skills score higher than human-step-wizard; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| human-step-wizard (this skill)by borghei | 89 | 817 | 56d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
Frequently asked questions
- How do I install human-step-wizard?
- Run
npx skills add borghei/Claude-Skills --skill human-step-wizard. The install tabs above show the steps for each supported agent. - Which AI agents does human-step-wizard work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is human-step-wizard safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is human-step-wizard still maintained?
- The repository was last updated about 2 months ago, so human-step-wizard is actively maintained.
Skill content
View source on GitHubname: human-step-wizard description: > Generate an interactive, resumable bash wizard that walks a person through steps only a human can do. Use when a task needs dashboard credentials, DNS or change approval, key rotation, or a manual traffic cutover. license: MIT + Commons Clause metadata: version: 1.0.0 author: borghei category: engineering domain: developer-tooling updated: 2026-11-08 tags: [wizard, bash, human-in-the-loop, credentials, cutover, runbook-automation]
Human Step Wizard
Some steps in an otherwise automated task need a person: creating a token in a dashboard, approving a DNS change, rotating a key the agent must never see, cutting traffic over at a moment someone chose. The usual hand-off is a paragraph of instructions in chat, which the human skims, half-follows, and reports back on from memory. This skill replaces that paragraph with a generated bash wizard: one step at a time, the exact link to open, hidden prompts for secrets, format validation on every pasted value, checks that confirm the step really happened, a typed confirmation before anything irreversible, and progress saved so the human can stop and resume.
The agent writes a small JSON spec; the tools validate it and generate the
script. This is distinct from engineering/runbook-generator, which produces
static operational documentation. A wizard is executable, interactive and
tied to one concrete task.
When to use this skill
- Credentials only a human can create: first admin token, OAuth app, API keys behind MFA, values the agent must not see
- Approvals and authority: DNS changes, change tickets, spending, accepting terms
- Rotations: roll a secret, deploy it, verify, revoke the old one
- Cutovers: DNS, load balancer, database primary, feature launch at a chosen time
- Onboarding setup: a new developer wiring up a dozen third-party accounts
into
.envand CI secrets
Not for steps the agent can perform itself; do those directly.
Clarify First
The procedure, not the script, is the hard part, and its details live with the human. Settle the inputs below before writing the spec. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.
- The step list and which step is irreversible: this sets the order (gather and verify everything before the point of no return) and where the typed confirmation goes.
- Where each value goes: env file, CI secret, both, or nowhere. Values a later check or the application needs must be stored, and secrets must not be stored more widely than they are used.
- Exact dashboard paths: if the agent is not sure of the current UI, it asks or links the page instead of inventing menu names.
- How to verify each step from outside: a
dig,curl,ghortestcommand that proves the outcome; without it, the wizard trusts the Enter key.
Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, generate from what you know and state your assumptions at the top of your reply.
Quick Start
# 1. Validate the spec (exit 1 on errors)
python3 engineering/human-step-wizard/scripts/wizard_spec_validate.py \
--spec engineering/human-step-wizard/assets/sample_wizard_spec.json
# 2. Generate the wizard (runs bash -n on the output)
python3 engineering/human-step-wizard/scripts/wizard_generate.py \
--spec engineering/human-step-wizard/assets/sample_wizard_spec.json --out scripts/cutover-wizard.sh
# 3. Hand it to the human
./scripts/cutover-wizard.sh # --list, --from STEP, --reset, --help
Tools Overview
| Tool | Purpose | Exit codes |
|------|---------|------------|
| scripts/wizard_spec_validate.py | Check ids, names, reserved variables, POSIX-ERE patterns, use-before-capture in checks, unquoted expansions, eval/source, irreversible steps without rollback or checks, unused secrets | 0 valid, 1 errors (or warnings with --strict), 2 unreadable or invalid JSON |
| scripts/wizard_generate.py | Validate, then emit one self-contained bash script: header, runtime, one function per step. Every spec string is single-quoted; output is bash -n checked | 0 written and syntax-checked, 1 spec errors or failed bash -n, 2 usage or I/O error |
| assets/wizard_runtime.sh | The runtime embedded in every wizard: prompts, hidden input, ERE validation, env-file upsert, checks with retry, irreversible confirmation, resume state, audit log | n/a (embedded) |
Both tools take --format text|json. The generator also takes --stdout to
print the script and --force to overwrite an existing file.
Generated wizard behaviour
| Feature | Behaviour |
|---------|-----------|
| Progress | ==== Step 3/6: title ====; --list shows done/pending |
| Resume | Finished step ids in .wizard-state/<slug>.done; stored values reloaded on restart |
| Secrets | read -s, never echoed or logged; env file written with mode 0600 |
| Validation | Anchored ERE per input, 3 attempts, then abort with progress kept |
| Checks | Spec commands run with captured values exported; failure offers retry/abort (and skip if allowed) |
| Irreversible | Rollback shown first; the human must type the step id |
| Safety | set -euo pipefail; refuses to run without a TTY unless WIZARD_ALLOW_NONINTERACTIVE=1 |
Workflows
Workflow 1: Hand a human step to a person [RECOMMENDED]
- Do every step the agent can do first. Collect what remains and confirm the list, order and irreversible step with the user.
- For each human step, write the navigation path, the value(s) produced, where each value goes, and a command that proves the step happened.
- Write the spec (start from
assets/sample_wizard_spec.json). - Validate with
--strict; fix every error and justify every remaining warning. - Generate the script. Add the env file to
.gitignore. - Tell the human the command, the time it takes, any waiting periods, and which step is irreversible. Wait for them; do not run it yourself.
python3 engineering/human-step-wizard/scripts/wizard_spec_validate.py \
--spec engineering/human-step-wizard/assets/sample_wizard_spec.json --strict --format json
python3 engineering/human-step-wizard/scripts/wizard_generate.py \
--spec engineering/human-step-wizard/assets/sample_wizard_spec.json --stdout > /tmp/wizard.sh
bash -n /tmp/wizard.sh && echo syntax-ok
Workflow 2: Verify a wizard before hand-off
The agent cannot complete the wizard (it blocks on human input), so it validates the script statically and with a scripted run in a scratch directory:
bash -n(the generator already did) andshellcheck -S warningif installed.- Copy the spec, replace network checks with local ones (
test -n "$VAR"), generate, and pipe answers in, including a hostile value such as$(touch PWNED). - Verify that the env file holds the literal values, that no
PWNEDfile appeared, that--listshows the right progress after an abort, and that a re-run resumes at the right step.
printf '%s\n' 'first-answer' 'abc' 'step-id' '' | \
WIZARD_ALLOW_NONINTERACTIVE=1 WIZARD_STATE_DIR=./state bash wizard.sh
Workflow 3: Fix a rejected spec
python3 engineering/human-step-wizard/scripts/wizard_spec_validate.py \
--spec engineering/human-step-wizard/assets/sample_wizard_spec_flawed.json
The flawed sample fails on purpose (exit 1) with eight errors: a non-slug
slug, a lowercase variable name, eval in a check, a value used before it is
captured, a duplicate step id, an irreversible step without rollback, a \d
pattern bash cannot match, and an input named PATH. Fix in that order:
naming errors first, because later rules depend on names resolving.
Spec Format
{
"title": "Move api.example.com to the new load balancer",
"slug": "api-lb-cutover",
"env_file": ".env.cutover",
"steps": [
{
"id": "cutover-dns",
"title": "Point api.example.com at the new load balancer",
"instructions": ["DNS -> Records -> api.example.com (A) -> Edit.", "Set the new address and save."],
"url": "https://dash.dns-provider.example/example.com/dns/records",
"inputs": [{"name": "NEW_LB_IP", "prompt": "New IPv4", "pattern": "^([0-9]{1,3}\\.){3}[0-9]{1,3}$", "store": "env"}],
"checks": [{"description": "DNS returns the new address", "command": "dig +short api.example.com A | grep -qxF \"$NEW_LB_IP\""}],
"irreversible": true,
"rollback": "Set the A record back to OLD_LB_IP from .env.cutover; 60 s TTL.",
"pause": true,
"allow_skip": false
}
]
}
| Field | Required | Notes |
|-------|----------|-------|
| title, slug | yes | Slug names the state files; lowercase and dashes |
| env_file | no (.env) | Relative path; captured store: env values go here, mode 0600 |
| steps[].id, title, instructions | yes | Id is the resume key: do not rename after first use |
| url | no | Printed; opened only with WIZARD_OPEN_URLS=1 |
| inputs[] | no | name UPPER_SNAKE, prompt, secret, pattern (anchored ERE), store env/none |
| checks[] | no | description, command (fixed shell text; quote "$VARS") |
| irreversible + rollback | no | Typed confirmation and rollback shown before instructions |
| pause | no | Defaults to true when a step has no inputs |
| allow_skip | no | Lets the human skip a failing check (logged) |
Anti-Patterns
The Chat Runbook
Mistake: Pasting ten numbered steps into the chat and asking the human to "let me know when done". Why it happens: It is the fastest thing for the agent to produce. Instead: Generate a wizard. The human sees one step at a time, values are captured and validated where they are produced, and the agent gets a verifiable result instead of "done, I think".
The Trust-the-Enter-Key Wizard
Mistake: Steps with a pause and no check, so pressing Enter marks them done.
Why it happens: Writing a check means knowing how to observe the outcome, which takes thought.
Instead: Attach a check that observes the world from outside (dig, curl, gh secret list, test -s). The validator warns on irreversible steps without one.
The Late Rollback Data
Mistake: Asking the human to change the DNS record without first capturing the old address. Why it happens: Rollback feels like a separate concern from the forward path. Instead: Capture rollback inputs in an earlier step and store them, so the rollback text can point at a saved value.
The PCRE Pattern
Mistake: Validating with ^\d+$ or (?:...), copied from a Python or JavaScript regex.
Why it happens: Most regex knowledge is PCRE; bash's [[ =~ ]] silently uses POSIX ERE.
Instead: Use [0-9], [A-Za-z0-9_], [[:space:]], plain groups. The validator rejects PCRE-only syntax because the human would be told their correct value is wrong.
The Sourced Env File
Mistake: Hand-editing the generated script to source .env or eval a captured value.
Why it happens: It is the shortest way to load variables.
Instead: Regenerate from the spec. The runtime parses the env file and assigns only declared names; a pasted $(...) stays text.
Verification Checklist
- [ ] Spec validates with
--strict(or each warning has a stated reason) - [ ] Every value a later check or the application needs has
store: env - [ ] Every irreversible step has rollback text that names the saved old value
- [ ] Generated script passes
bash -n(andshellcheck -S warningwhen available) - [ ] Scripted run in a scratch dir: hostile input stays literal, resume works
- [ ] Env file path is gitignored; the human knows which step is irreversible
Reference Documentation
| File | Contents |
|------|----------|
| references/human-step-design.md | What is h
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
