agentleFS
cleysonunez6327cleysonunez6327/videos-demo/skills/ndemo/SKILL.md

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.

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
  1. Distinctive:

    Create narrated screen-recording demo videos of web applications.

    line 8
  2. Very specific:

    Check if ${CLAUDE_PLUGIN_ROOT}/dist/cli.js exists.

    line 13
  3. Distinctive:

    If it is missing, tell the user to export it from their shell profile:

    line 29
  4. Very specific:

    All commands are run via ${CLAUDE_PLUGIN_ROOT}/ndemo:

    line 58
  5. Distinctive:

    Create the directory and YAML file.

    line 114
  6. Distinctive:

    Write all segments with narration and intent first.

    line 212
  7. Very specific:

    If page-state shows [button "Settings"]:

    line 238
  8. Very specific:

    Look at the component source for data-testid attributes, class names, or IDs when the accessibility tree isn't sufficient.

    line 261
  9. Very specific:

    Add wait actions after visible changes so the viewer can see what happened:

    line 285
  10. Distinctive:

    After each change, replay the affected segment(s) to verify.

    line 337
  11. Distinctive:

    When the user approves:

    line 341
  12. Distinctive:

    Must be unique within the playbook

    line 440
  13. Very specific:

    Check .ndemo/daemon.log for browser daemon output.

    line 446
  14. Very specific:

    Element not found: Run ${CLAUDE_PLUGIN_ROOT}/ndemo page-state to see what's actually on the page.

    line 447
  15. Very specific:

    Actions pass but look wrong: Run with --segment <id> to replay just that segment and watch carefully.

    line 450
  16. Very specific:

    TTS fails with HTTP 401/402: Run ${CLAUDE_PLUGIN_ROOT}/ndemo doctor.

    line 457

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 build

Then install the Playwright browser if needed:

cd ${CLAUDE_PLUGIN_ROOT} && npx playwright install chromium

TTS 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 ~/.bashrc

Recommend 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 in

Verify the setup:

${CLAUDE_PLUGIN_ROOT}/ndemo doctor

Commands

All commands are run via ${CLAUDE_PLUGIN_ROOT}/ndemo:

CommandWhat it does
${CLAUDE_PLUGIN_ROOT}/ndemo open <playbook>Launch browser daemon, navigate to app
${CLAUDE_PLUGIN_ROOT}/ndemo closeShut down browser daemon
${CLAUDE_PLUGIN_ROOT}/ndemo resetNavigate back to app URL (fresh state)
${CLAUDE_PLUGIN_ROOT}/ndemo page-statePrint current page accessibility tree
${CLAUDE_PLUGIN_ROOT}/ndemo page-state --screenshotSame + 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> --audioPlay 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 doctorCheck 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 execute
  • parallel — 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.yaml

Step 3 — Author each segment

For each segment with empty actions:

a) Read the current page state:

${CLAUDE_PLUGIN_ROOT}/ndemo page-state

b) 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 content

At 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 seconds

c) 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.yaml

Watch 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 --audio

This 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 saysWhat 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.yaml

This 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.sh

Browser actions — same syntax as segment actions:

setup:
  - type: click
    target: { role: button, name: "Login" }
  - type: type
    target: { role: textbox, name: "Username" }
    text: admin

Conditional 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 page

Condition fields:

  • visible: "<selector>" — step runs only if selector matches visible elements
  • hidden: "<selector>" — step runs only if selector matches no visible elements
  • url: "<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

TypeRequired fieldsNotes
clicktarget
typetarget, textOptional delay in ms between keystrokes (default 80)
hovertarget
scrolltargetScrolls element into view
waitduration (ms)Pause for the viewer (default 1000ms)
presskeyKeyboard key, e.g. "Enter", "Escape"
selecttarget, optionDropdown 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 close then open again. Check .ndemo/daemon.log for browser daemon output.
  • Element not found: Run ${CLAUDE_PLUGIN_ROOT}/ndemo page-state to 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>.png in 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 verifies LLM4AGENTS_API_KEY against the API and prints the account balance — TTS is billed per character, so an empty balance fails the render.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.