stepped-demo-script

Stepped Demo Script

Compose a single bash file that a human can paste into their terminal and walk through, one step at a time, and see at each step (a) what the script is doing, (b) the command's output, and (c) whether the outcome matched expectations. The reader is often not the author – could be a teammate, a stakeholder, a support engineer on the other side of a ticket – so the script needs to be self-contained, legible without context, and not terrifying to open.

The goal is authoring velocity: the user starts most of these from a blank page, and the skill's job is to get them past the blank page with the right bones in place, not to dictate the body.

When this applies

Trigger when the user wants a runnable script that demonstrates a process by calling out each step and pausing for the reader. Common shapes:

• API sequence – a series of cURL calls showing a flow (e.g. auth → create → fetch → verify), often to reproduce a customer-ticket scenario or show off correct vs. broken behavior.
• CLI walkthrough – a series of commands in a shell or tool (git, kubectl, a CLI the user is learning or teaching).
• Mixed – any sequence where each step is one or two commands whose output the human should look at before moving on.

Skip when the script shouldn't pause (CI, cron, piped-to-file), when there's no stepping (a single long command), or when the "demo" is really a tutorial document (that's Markdown, not bash).

The authoring flow

1. Elicit the scenario if it's not already clear from the conversation. You need: what's being demonstrated, in roughly what steps, and whether any of it is misbehavior (so expect can surface the mismatch). Don't over-interview – a one-line scenario plus a list of steps is enough to draft.
2. Pick the closest example from examples/ to seed the structure (API sequence or CLI walkthrough). Read the full example before drafting – the shape matters more than any one line.
3. Start from templates/minimal.sh for new scripts, or extend the chosen example if its shape matches. Never compose a demo script from scratch without the prelude – the constants and helpers in the prelude are the whole point of the skill.
4. Compose the body from the alphabet in references/primitives.md: announce, section, expect, pause, plus the _jq/$c/$x constants. Each step is roughly announce "what I'm about to do" → <command> → pause, with an expect line afterward if there's an outcome to assert.
5. Wrap repeated calls in a shell function, not with a new primitive. If the same cURL shows up twice, lift it into a local function (see examples/api-sequence.sh). Functions wrap the command + its announce, not the pause – pauses stay at the call site so step granularity is controlled by the caller.
6. Read the draft back with fresh eyes. The test is whether a reader who's never seen the context can paste the file into their terminal and follow along. If a step's purpose isn't obvious from the announce line, fix the announce, not the code.
7. Write the script to disk, defaulting to /tmp/<scenario-slug>.sh. Use the active client's file-writing capability. The chat answer is a one-line handoff pointing at the file path -- not the script itself in a fenced block. Two reasons: (a) inlining the script in chat gives the user an unnecessary copy-paste-and-save step before they can run it; (b) writing to a relative path (e.g. ./demo.sh, squash-demo.sh) pollutes whatever directory the user invoked the skill from -- they may be inside a repo, and the demo doesn't belong there. Default to /tmp/<scenario-slug>.sh; pick a different absolute path only if the user names one. The user-facing chat answer should be ~1-2 sentences pointing at the file (e.g. "Script is at /tmp/find-delete-demo.sh -- run it with bash /tmp/find-delete-demo.sh. Each step pauses for Enter.").