ndemo
Skill0 starsChanged 3 months agoMITView on GitHub
Record narrated demo videos of a web application by driving a real browser. Use when the user asks for a demo video, screencast, walkthrough, product video, tutorial video or promo of a running web app, or asks to update, re-render or restructure one. Triggers on demo video, screencast, video walkthrough, product demo, grabar un demo, video de la app, playbook.
- Reads credentials
- Installs packages
In this repositoryOne other file it gives its agents.
- testimonialSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 7 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Create narrated screen-recording demo videos of web applications.
- Very specific: line 13
Check if ${CLAUDE_PLUGIN_ROOT}/dist/cli.js exists.
- Distinctive: line 29
If it is missing, tell the user to export it from their shell profile:
- Very specific: line 58
All commands are run via ${CLAUDE_PLUGIN_ROOT}/ndemo:
- Distinctive: line 114
Create the directory and YAML file.
- Distinctive: line 212
Write all segments with narration and intent first.
- Very specific: line 238
If page-state shows [button "Settings"]:
- Very specific: line 261
Look at the component source for data-testid attributes, class names, or IDs when the accessibility tree isn't sufficient.
- Very specific: line 285
Add wait actions after visible changes so the viewer can see what happened:
- Distinctive: line 337
After each change, replay the affected segment(s) to verify.
- Distinctive: line 341
When the user approves:
- Distinctive: line 440
Must be unique within the playbook
- Very specific: line 446
Check .ndemo/daemon.log for browser daemon output.
- Very specific: line 447
Element not found: Run ${CLAUDE_PLUGIN_ROOT}/ndemo page-state to see what's actually on the page.
- Very specific: line 450
Actions pass but look wrong: Run with --segment <id> to replay just that segment and watch carefully.
- Very specific: line 457
TTS fails with HTTP 401/402: Run ${CLAUDE_PLUGIN_ROOT}/ndemo doctor.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ndemo
Create narrated screen-recording demo videos of web applications.
Setup
On first use, you MUST build the toolkit before running any command.
Check if ${CLAUDE_PLUGIN_ROOT}/dist/cli.js exists. If not, run:
cd ${CLAUDE_PLUGIN_ROOT} && npm install && npm run buildThen install the Playwright browser if needed:
cd ${CLAUDE_PLUGIN_ROOT} && npx playwright install chromiumTTS needs LLM4AGENTS_API_KEY. Never write a key yourself, and never
read one back to the user — ask them to set it and then verify with
doctor.
If it is missing, tell the user to export it from their shell profile:
echo 'export LLM4AGENTS_API_KEY="their-key"' >> ~/.bashrc && source ~/.bashrcRecommend that over a .env file when the plugin was installed from a
marketplace: the plugin lives in Claude Code's cache, which is replaced
when the plugin updates, so a key written there is lost on the next
update. They get a key by registering an agent at
https://api.llm4agents.com/docs.
ndemo also reads .env — from the current working directory first, then
from ${CLAUDE_PLUGIN_ROOT} — and a real environment variable always
wins over both. Prefer a project-level .env only when the key differs
per project, or when working from a local clone of this repository:
cp ${CLAUDE_PLUGIN_ROOT}/.env.example ./.env # then the user fills it inVerify the setup:
${CLAUDE_PLUGIN_ROOT}/ndemo doctorCommands
All commands are run via ${CLAUDE_PLUGIN_ROOT}/ndemo:
| Command | What it does |
${CLAUDE_PLUGIN_ROOT}/ndemo open <playbook> | Launch browser daemon, navigate to app |
${CLAUDE_PLUGIN_ROOT}/ndemo close | Shut down browser daemon |
${CLAUDE_PLUGIN_ROOT}/ndemo reset | Navigate back to app URL (fresh state) |
${CLAUDE_PLUGIN_ROOT}/ndemo page-state | Print current page accessibility tree |
${CLAUDE_PLUGIN_ROOT}/ndemo page-state --screenshot | Same + save screenshot to .ndemo/screenshot.png |
${CLAUDE_PLUGIN_ROOT}/ndemo play <playbook> | Play all segments |
${CLAUDE_PLUGIN_ROOT}/ndemo play <playbook> --segment <id> | Play one segment (rewinds first) |
${CLAUDE_PLUGIN_ROOT}/ndemo play <playbook> --from <id> | Play from segment to end |
${CLAUDE_PLUGIN_ROOT}/ndemo play <playbook> --to <id> | Stop after this segment |
${CLAUDE_PLUGIN_ROOT}/ndemo play <playbook> --audio | Play with TTS narration audio |
${CLAUDE_PLUGIN_ROOT}/ndemo render <playbook> | Full pipeline: TTS → replay → merge → mp4 |
${CLAUDE_PLUGIN_ROOT}/ndemo render <playbook> --output <path> | Render to a specific output file |
${CLAUDE_PLUGIN_ROOT}/ndemo doctor | Check dependencies |
Workflow
Step 1 — Create the playbook
Each playbook lives in its own directory under demo/ in the
user's project. The directory name matches the playbook name.
demo/
my-feature/
my-feature.yaml ← playbook
fixtures/ ← files to restore during setup
audio/ ← generated TTS files (auto)
video-raw/ ← raw recording (auto)
demo.mp4 ← final output (auto)Before writing the playbook, read references/narrative.md. It
covers which segment order holds attention and how to write narration
that adds to the screen instead of describing it. Structure is decided
in the playbook, and changing it after a render means regenerating every
narration.
Then think about what state the app needs to be in for the demo to work reliably and repeatably:
- Does the user need to be logged in? → add conditional login steps
- Does the demo modify files/data that need restoring? → copy
originals into the playbook's
fixtures/directory so setup can restore them - Does the demo depend on specific content existing? → create it in fixtures or via setup shell commands
Copy any files that will be modified during the demo into the
fixtures/ subdirectory of the playbook directory. Setup steps
will copy them back before each run so the demo always starts
from a clean state.
Create the directory and YAML file. The full playbook schema supports these top-level sections:
# demo/edit-page/edit-page.yaml
app:
url: http://localhost:8080/wiki
viewport: # optional, default 1920x1080
width: 1920
height: 1080
scale: 2 # device scale factor (default 2)
zoom: 1.25 # real browser zoom (default 1.25)
colorScheme: light # "light" or "dark" (default "light")
setup:
# Restore files modified during the demo
- run: cp demo/edit-page/fixtures/page.txt data/pages/page.txt
# Clean up artifacts from previous runs
- run: rm -f data/cache/*.tmp
# Login if needed (conditional — skipped if already logged in)
- type: click
target: { role: link, name: "Login" }
if:
hidden: ".user-info"
- type: type
target: { role: textbox, name: "Username" }
text: admin
if:
visible: ".login-form"
- type: type
target: { role: textbox, name: "Password" }
text: password
if:
visible: ".login-form"
- type: click
target: { role: button, name: "Sign in" }
if:
visible: ".login-form"
done:
visible: ".user-info"
titleCard: # optional title card (shown as first frame)
title: "Editing a Wiki Page" # displayed prominently
subtitle: "A quick tour of the editor" # optional subtitle
stat: # optional: lead with a metric
value: "10x" # fills the frame
label: "menos tokens por pagina" # sits under the number
duration: 600 # milliseconds to hold (default 600)
tts: # optional TTS configuration
provider: llm4agents # "llm4agents" (default) or "voxcpm"
model: x-ai/grok-voice-tts-1.0 # TTS model (this is the default)
voice: sal # eve, ara, rex, sal or leo (default "sal")
speed: 1.0 # speed multiplier, 0 < speed <= 4 (default 1.0)
# VoxCPM2 alternative — cloned voices, no API key and nothing to pay per
# render. Reachable at https://voicelab.vocaltwin.io by default; export
# VOXCPM_BASE_URL to use a tailnet or LAN address instead, which is faster
# and has no request ceiling. Query GET <base>/api/voices for current slugs;
# the catalogue changes whenever someone clones a voice, so never assume it.
tts:
provider: voxcpm
voice: angie # required, unless designing one via style
mode: ultimate # "ultimate" (default) or "simple"
refMaxSec: 29 # reference seconds, max 45 (default 15)
language: Spanish # informational; the model reads the text
format: mp3 # mp3 (default) or wav
# style: "tono de documental" # forces mode: simple — see below
# baseUrl: http://skywalker:7862 # overrides VOXCPM_BASE_URL here
# mode: ultimate conditions on the reference audio AND its transcript, which
# is what carries the speaker's cadence. mode: simple uses audio only.
# `style` cannot ride along with `ultimate`: the model would read the
# directive out loud. Pick nuance (ultimate, no style) or delivery control
# (simple, with style) — the schema rejects the combination.
recording: # optional recording settings
outputDir: "." # output directory relative to playbook (default ".")
fps: 30 # video frame rate (default 30)
segments:
- id: intro
narration: "Welcome to our wiki. Let's edit a page."
intent: "show the wiki start page"
timing: after # "after" (default) or "parallel"
actions:
- type: wait
duration: 2000
- id: open-editor
narration: "Click the edit button to open the editor."
intent: "click the edit button"
actions: []Segment timing controls when actions run relative to narration:
after(default) — narration plays first, then actions executeparallel— actions execute while narration plays
Write all segments with narration and intent first. Leave actions as empty arrays. Use absolute paths when passing playbook paths to ndemo commands.
Step 2 — Open the browser
${CLAUDE_PLUGIN_ROOT}/ndemo open /absolute/path/to/demo/my-demo/my-demo.yamlStep 3 — Author each segment
For each segment with empty actions:
a) Read the current page state:
${CLAUDE_PLUGIN_ROOT}/ndemo page-stateb) Look at the accessibility tree output. Find the elements referenced in the segment's intent. Write actions into the playbook YAML using elements from the tree.
How to write targets — use info from page-state output:
If page-state shows [button "Settings"]:
target: { role: button, name: "Settings" }If page-state shows [searchbox "Search reports" value=""]:
target: { role: searchbox, name: "Search reports" }Other target fields — use whichever best identifies the element:
target: { selector: "#my-element" } # CSS selector
target: { testId: "submit-btn" } # data-testid attribute
target: { label: "Email" } # aria-label
target: { placeholder: "Search..." } # placeholder text
target: { text: "Click me" } # visible text contentAt least one target field is required. Multiple fields can be combined to narrow the match.
Tip: The web app's source code is available in the project repo.
Look at the component source for data-testid attributes,
class names, or IDs when the accessibility tree isn't sufficient.
How to write done conditions:
done:
visible: ".settings-panel" # element appears
hidden: ".loading-spinner" # element disappears
networkIdle: true # no pending requests
stable: 500 # DOM unchanged for 500ms
url: "**/settings" # URL changed
text: # element contains text
selector: ".results"
has: "Q3 Revenue"
attribute: # element has attribute
selector: html
name: data-theme
value: dark
timeout: 10000 # override default timeout (ms)Every action that changes the page MUST have a done condition. Without one, the next action may execute before the page is ready.
Add wait actions after visible changes so the viewer can see
what happened:
- type: wait
duration: 2000 # 2 secondsc) Test the segment:
${CLAUDE_PLUGIN_ROOT}/ndemo play /absolute/path/to/demo/my-demo/my-demo.yaml --segment <id>d) If it fails, run ${CLAUDE_PLUGIN_ROOT}/ndemo page-state to see
what's on screen now, adjust the actions, and retry.
e) After the segment works, read page-state again before authoring the next segment — the page has changed.
Step 4 — Review
${CLAUDE_PLUGIN_ROOT}/ndemo play /absolute/path/to/demo/my-demo/my-demo.yamlWatch the full sequence in the browser. Ask the user if it looks right.
To review with TTS narration (requires LLM4AGENTS_API_KEY and ffplay):
${CLAUDE_PLUGIN_ROOT}/ndemo play /absolute/path/to/demo/my-demo/my-demo.yaml --audioThis generates TTS audio for each segment (cached by content hash), plays the audio alongside the browser actions, and pads timing so actions match the narration duration. If narration text changes, the audio is automatically regenerated and the old file is deleted.
Step 5 — Iterate
The user may request changes. Common patterns:
| User says | What to do |
| "Wrong button" | Run page-state, find correct element, update target |
| "Too fast" / "too slow" | Adjust wait durations, replay with --audio to check timing |
| "Change narration to ..." | Edit narration field |
| "Add a step showing X" | Insert new segment, author its actions |
| "Remove that step" | Delete the segment from YAML |
| "Replay from segment X" | ${CLAUDE_PLUGIN_ROOT}/ndemo play --from <id> |
| "Start over" | ${CLAUDE_PLUGIN_ROOT}/ndemo reset then play again |
After each change, replay the affected segment(s) to verify.
Step 6 — Render
When the user approves:
${CLAUDE_PLUGIN_ROOT}/ndemo render /absolute/path/to/demo/my-demo/my-demo.yamlThis produces the final mp4 with TTS narration.
Setup Steps Reference
Setup steps run before the demo starts (on open, reset, play,
and render). They can be shell commands or browser actions.
Shell commands execute relative to the project working directory
(the directory ndemo was called from). All paths in run commands
should be relative to the project root.
Shell commands — use run for file operations:
setup:
- run: cp demo/my-feature/fixtures/original.txt data/page.txt
- run: rm -f data/cache/*.tmp
- run: ./scripts/reset-db.shBrowser actions — same syntax as segment actions:
setup:
- type: click
target: { role: button, name: "Login" }
- type: type
target: { role: textbox, name: "Username" }
text: adminConditional steps — add if to skip when condition is not met:
setup:
# Only login if not already logged in
- type: click
target: { role: link, name: "Sign in" }
if:
hidden: ".user-menu" # skip if user menu is visible
# Only run on a specific page
- type: click
target: { role: button, name: "Reset" }
if:
url: "**/admin/settings" # skip if not on this pageCondition fields:
visible: "<selector>"— step runs only if selector matches visible elementshidden: "<selector>"— step runs only if selector matches no visible elementsurl: "<pattern>"— step runs only if current URL matches (**= any path)
Guard a login on something only the login page has. A generic
input[type="password"] looks like the obvious signal and is a trap: any
settings screen with an API secret, a token or a "change password" field
matches it too, and the setup then tries to fill a username box that is not
there. Guard on the submit button's own name instead — button:has-text("Sign
in") — which no other page carries.
Log in before the recording starts, not during it. Credentials belong in
setup, which runs ahead of the first frame, so the typing never reaches the
video. Keep the playbook itself in a directory that is gitignored: the
password sits in it as plain text.
Landing straight on a deep page. Most apps accept a redirect parameter on
the sign-in URL — /sign-in?redirect=%2Fsome%2Fdeep%2Fpage. Point app.url
at that and the demo opens exactly where the story starts, with the login
already behind it. Give its done a generous timeout; a cold sign-in can
take a while, and the failure otherwise looks like a broken selector.
Action Types Reference
| Type | Required fields | Notes |
| click | target | |
| type | target, text | Optional delay in ms between keystrokes (default 80) |
| hover | target | |
| scroll | target | Scrolls element into view |
| wait | duration (ms) | Pause for the viewer (default 1000ms) |
| press | key | Keyboard key, e.g. "Enter", "Escape" |
| select | target, option | Dropdown selection |
There is no file-upload action. A flow that requires picking a file cannot be recorded past that step — check for one before promising a demo of an import, a bulk upload or a CSV-driven feature.
A native <select> does not open on camera. The dropdown list is drawn
by the operating system, not the page, so it never reaches the recording —
a segment built around "open the menu to show the options" records as a
motionless frame. To show breadth, run several select actions in sequence
instead: the closed control's value changes on screen, and any dependent
field updates with it.
Segment ID Rules
- Lowercase alphanumeric with hyphens:
open-settings,toggle-dark - Must be unique within the playbook
- Used as filenames for audio/video, so keep them short
Troubleshooting
- Browser not responding:
${CLAUDE_PLUGIN_ROOT}/ndemo closethenopenagain. Check.ndemo/daemon.logfor browser daemon output. - Element not found: Run
${CLAUDE_PLUGIN_ROOT}/ndemo page-stateto see what's actually on the page. The element might have a different name than expected. Check the app's source code for test IDs. - Actions pass but look wrong: Run with
--segment <id>to replay just that segment and watch carefully. - Render fails: An error screenshot is saved as
error-<segment-id>.pngin the output directory. - TTS sounds wrong: Edit narration text (punctuation affects pacing), or change voice/speed in playbook tts settings. Changing any tts setting regenerates the audio automatically.
- TTS fails with HTTP 401/402: Run
${CLAUDE_PLUGIN_ROOT}/ndemo doctor. It verifiesLLM4AGENTS_API_KEYagainst the API and prints the account balance — TTS is billed per character, so an empty balance fails the render.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

