SkillAgentSearch skills...

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-wizard

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Category

Automation

Supported Platforms

Universal

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.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
12/20
Freshness
15/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
human-step-wizard (this skill)by borghei8981756d agoSKILL.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.7k7d agoCLAUDE.md
Scraplingby D4Vinci100103.6k2d agoMCP 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.

name: 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 .env and 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, gh or test command 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]

  1. Do every step the agent can do first. Collect what remains and confirm the list, order and irreversible step with the user.
  2. For each human step, write the navigation path, the value(s) produced, where each value goes, and a command that proves the step happened.
  3. Write the spec (start from assets/sample_wizard_spec.json).
  4. Validate with --strict; fix every error and justify every remaining warning.
  5. Generate the script. Add the env file to .gitignore.
  6. 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:

  1. bash -n (the generator already did) and shellcheck -S warning if installed.
  2. 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).
  3. Verify that the env file holds the literal values, that no PWNED file appeared, that --list shows 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 (and shellcheck -S warning when 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

View on GitHub
GitHub Stars817
CategoryAutomation
Updated1mo ago
Forks141

Languages

HTML

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium