DemoDay

You are about to produce a finished demo video of someone's software — narrated, paced, with an intro, transitions and a point — not a screen recording. This folder is the whole toolkit: scripts, a rehearsal server, a Remotion template and the five craft guides below. Nothing lives outside it.

Where things are

$CLAUDE_PLUGIN_ROOT in the guides means this folder — the directory that holds this SKILL.md. In Claude Code the plugin sets that variable; installed through npx skills it is ~/.agents/skills/demoday (or the project's .agents/skills/demoday); as a Codex plugin it is the plugin's install directory. Every node scripts/... command in the guides runs from here, e.g.

cd ~/.agents/skills/demoday && node scripts/doctor.mjs

The video project is separate: it lives under the demoed repo at <repo>/demo/<slug>/ and is passed as --project demo/<slug> to every script.

First run — do this before anything else

node scripts/doctor.mjs --install        # installs node packages + Chromium, then checks the machine

doctor prints one line per requirement with the exact fix command. The two things it cannot do for the user: a FAL_API_KEY (fal.ai — narration, presenter, b-roll; store it in the macOS Keychain as printed), and, for desktop or terminal demos, the Screen Recording and Accessibility permissions, which the user grants to the terminal app and then restarts it. Stop and tell the user exactly what to do when either is missing; never fake a capture.

The rehearsal tools

Capture is two passes: rehearse (you drive the app, screenshot after every action, nothing recorded) and perform (a runner replays the rehearsed steps smoothly while recording). The rehearsal tools are demo_open, demo_open_app, demo_open_cli, demo_open_browser, demo_inspect, demo_click, demo_drag, demo_type, demo_key, demo_scroll, demo_highlight, demo_wait_stable, demo_screenshot, demo_undo_step, demo_review_script, demo_save_actions, demo_load_actions, demo_close.

Three ways to reach them, pick the first that applies:

1. They are already in your tool list (Claude Code plugin, Codex plugin) — call them directly.
2. Your agent supports MCP servers — register mcp/server.mjs as a stdio server once and the tools appear. Any client config takes the same shape:

   { "mcpServers": { "demo-stage": { "command": "node", "args": ["<this folder>/mcp/server.mjs"] } } }

   (Codex: codex mcp add demo-stage -- node <this folder>/mcp/server.mjs; Cursor: .cursor/mcp.json; Gemini CLI: ~/.gemini/settings.json; VS Code / Copilot: .vscode/mcp.json.) Raise the client's tool timeout if it has one — demo_wait_stable can legitimately take a couple of minutes.
3. Shell only — scripts/stage.mjs is the same server driven from the command line. The first call starts it in the background; each later call is one tool invocation against the live session, so the browser and the action script persist between commands:

   node scripts/stage.mjs tools                                     # every tool and its flags
   node scripts/stage.mjs open --url http://localhost:3000 --id feature-1
   node scripts/stage.mjs inspect --filter save
   node scripts/stage.mjs click --selectors '[data-testid=save]' --label "Save"
   node scripts/stage.mjs save_actions --file demo/<slug>/actions/feature-1.json
   node scripts/stage.mjs stop                                      # close + end the daemon

   Tool names drop the demo_ prefix. Screenshots are written as PNG files and the path is printed as screenshot: … — open that image after each step; deciding from the text alone is guessing. Desktop clicks take --x --y read off the most recent screenshot, exactly as with the MCP tool.

Everywhere the guides say demo_<name>, read node scripts/stage.mjs <name> if you are on path 3.

The workflow — read this next

Open and follow skills/demo-video/SKILL.md in this folder. It is the end-to-end recipe (recon → direction → script → narration → rehearse → perform → presenter/b-roll → render → QA) and it tells you when to read the others:

Where a guide says to use AskUserQuestion, ask the user in whatever way your agent asks questions; the answers (style, goal, length, presenter mode) change the whole video, so do not skip them.

Rules that never bend

• Show the cost estimate (node scripts/plan.mjs --project demo/<slug>) and get an explicit yes before generating anything. Narration, presenter and b-roll bill per second.
• Narration before capture. Durations drive the pacing of every scene.
• Rehearse, then perform. Never record yourself exploring.
• Everything goes in demo.json. State that only exists in your context is lost on the next run.
• Look at the frames during QA (node scripts/qa.mjs). There is no automatic grader.
• Report what actually happened. A failed scene is reported, not hidden.