CommunityImagemgithub.com

app-demo

Make how-to demo videos for any web app, with a voice-over in any language. The skill reads the app's code to list what it can do, proposes a catalog of demo videos, and for the one the user picks writes the voice-over script. It then waits for the user's TTS voice files, captures the real app screens, builds a 1920×1080 piece where a marker and camera zoom follow the voice (no captions), and exports an MP4 and a thumbnail. Use it whenever the user asks for a demo video, tutorial video, how-to video, walkthrough, help-centre or onboarding video, a "video for feature X", or wants to know which features of their app deserve demo videos.

O que é app-demo?

app-demo is a Claude Code agent skill that make how-to demo videos for any web app, with a voice-over in any language. The skill reads the app's code to list what it can do, proposes a catalog of demo videos, and for the one the user picks writes the voice-over script. It then waits for the user's TTS voice files, captures the real app screens, builds a 1920×1080 piece where a marker and camera zoom follow the voice (no captions), and exports an MP4 and a thumbnail. Use it whenever the user asks for a demo video, tutorial video, how-to video, walkthrough, help-centre or onboarding video, a "video for feature X", or wants to know which features of their app deserve demo videos.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/moessam93/app-demo-skill/tree/HEAD

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

App demo videos

A demo is a tutorial: one task, start to finish, in the real app.

  • No captions and no on-screen text. The only words on screen are the app's own UI. A marker on the control being used directs attention: a pulsing ring, then a tap ripple on a phone or a cursor click on desktop. A camera zoom onto it does the same.
  • The voice drives the timing. Claude writes the script. The user makes the speech with any TTS tool (or records it) and hands over the files. Each step lasts as long as its clip plus a silent gap. The screen changes in the gaps, never under speech. There's no music unless the user asks.
  • Every video is 1920×1080. Phone demos show the app in a phone frame on a branded background. Desktop demos show it in a browser window.
  • Optional second UI language. If the app has two UI languages, the voice names each button in both. The screen crossfades from one language to the other as the voice reaches the second name, so every viewer sees the label they know. references/script-format.md covers this.
  • Real screens only. Use captures of the real app, running locally, with sample data. Every spoken sentence must be true in the code today.

<skill> below means this skill's base directory. <demos> means the project's demos folder, demo-videos/ by default. Run every command from the project root.

The flow (always in this order, one gate per stage)

0. Set up (first time in a project)

Run node <skill>/scripts/doctor.mjs. It needs Node 22+, Chrome, Chromium, Edge or Brave, and ffmpeg. Then run node <skill>/scripts/init.mjs <demos> --product "<Name>", which copies the tools into <demos>/_tools/, so the project can rebuild videos without this skill. Fill in <demos>/demo.config.json from the code first. Then confirm with the user the few things code can't tell you: the voice language and tone, the TTS tool, and the public app URL to show. See references/setup.md.

1. Find the features

Read the codebase and write <demos>/features.md: every user-facing feature, who uses it, where it lives (route or screen) and the code that proves it. Follow references/discovery.md. Show the user a short summary grouped by area and audience, and ask what's missing or wrong.

2. Suggest demos, and let the user validate them

Turn the features into <demos>/catalog.md: videos grouped by audience, each one task (or a few related tasks as consecutive parts), with form, a priority and status proposed. Show it as a short list with your recommended first video. Update it with the user's answers. Don't write any script until the user picks a demo.

3. Write the script for the chosen demo

  1. Create the folder with node <demos>/_tools/new-demo.mjs <slug> --form phone|desktop --title "…". A demo for both phone and desktop is two demos, each with its own script.
  2. Verify the flow in the code first. Read the pages, components and copy (i18n files) the task touches, and walk it in the running app if you can. Note anything that differs between phone and desktop, or between roles.
  3. Write <demos>/<slug>/script.md in the format in references/script-format.md. Each numbered row is one voice clip. Then run node <demos>/_tools/lines.mjs <demos>/<slug>.
  4. Write <demos>/<slug>/tts.md, paste-ready lines for the user's TTS tool.
  5. Show the script in chat and wait for approval or edits. Once it's approved, the numbering is frozen, because the voice files are named by it. A step added later becomes 03a; tell the user which file is new.

4. Wait for the voice

The user generates the voice and gives you a folder path. While waiting you may capture screens and pre-build the piece; lines.json carries estimated lengths until then. When the folder arrives, run: node <demos>/_tools/voice.mjs <demos>/<slug> "<folder>". It accepts one file per row (1.mp3, 01.wav, 3a.m4a), or one file for the whole script (full.mp3), which it splits. It reports missing or extra files and any clip whose pace suggests the wrong line or a cut-off take. Listen to, or ask about, every flagged clip before building on it.

5. Capture the real screens

Write <demos>/<slug>/capture.mjs against a fresh, seeded local copy of the app, then run it. It takes every frame the voice needs, in every UI language, and records each control's position. See references/capture.md.

6. Direct and build

Write <demos>/<slug>/direction.js: which frame each row shows, which control is ringed at which word, where taps land and which frame follows. Never edit index.html per demo; it's the shared engine. See references/direction.md. Then run node <demos>/_tools/rows.mjs <demos>/<slug> until it reports no problems.

7. Review, export, hand off

Render review stills, look at every one, fix and repeat. Then export the MP4 and the thumbnail and hand off, as in references/review-export.md. Update the demo's status in catalog.md.

Commands

node <skill>/scripts/doctor.mjs                                  check the machine
node <skill>/scripts/init.mjs <demos> --product "Name"            set up / update tools
node <demos>/_tools/new-demo.mjs <slug> --form phone|desktop --title "…"
node <demos>/_tools/lines.mjs <demos>/<slug>                      script.md → lines.json
node <demos>/<slug>/capture.mjs [--lang xx] [--only a,b]          real screens + targets
node <demos>/_tools/voice.mjs <demos>/<slug> "<voice folder>"     import the voice
node <demos>/_tools/rows.mjs <demos>/<slug>                       timings + problems
node <demos>/_tools/export.mjs <demos>/<slug> --review            2 stills per row
node <demos>/_tools/export.mjs <demos>/<slug>                     the MP4
node <demos>/_tools/thumbnail.mjs <demos>/<slug>                  thumbnail.png + -1280
node <demos>/_tools/serve.mjs <demos>                             preview with Play/scrub
node <demos>/_tools/new-demo.mjs <slug> --engine                  refresh a demo's engine

Exports take about 1.5–2× the video's length, so run long ones in the background.

Ground rules

  • Truth. Every line matches a step the code really has, and every label is the app's exact copy. Don't make marketing claims. Anything that isn't an instruction must be true and verified in code.
  • Data. Use sample data in a local or test environment only. Never use real customers, never production, and never the user's real accounts. Sign in with test accounts from the project's own seed or fixture files. If none exist, ask the user to create one. Don't type real passwords.
  • Privacy. Never show secrets, API keys, payment destinations (IBANs, wallet numbers, payment QR codes), personal chats, or other people's accounts. Blur them from the rects the capture records (references/capture.md).
  • Ask first before changing the app's code to make capture easier (adding test ids, seed data, flags), before installing anything, and before committing. MP4s aren't committed.
  • Recreate, don't fake, what's outside the app. OS sheets, emails, notifications or a third-party site the task passes through are rebuilt in HTML/CSS, faithful to the current versions, with the app's real copy. See references/recreated-ui.md.

Where things live

<demos>/
  demo.config.json      product, app URLs, languages, voice, brand, capture settings
  features.md           step 1: what the app does, with evidence
  catalog.md            step 2: the videos to make and their status
  brand/logo.svg        the logo for end cards and thumbnails (copied from the app)
  _tools/               the scripts (from init.mjs), dependency-free
  <slug>/
    script.md  tts.md   the approved script, and paste-ready TTS lines
    lines.json          each row's text, gap and real length (d)
    capture.mjs         this demo's capture run
    shots-<lang>/       real captures, one PNG per frame
    targets.json        each control's rect per language and frame
    direction.js        the direction
    index.html          the engine (never edited per demo)
    voice/  voice/norm/ the user's clips, then trimmed and normalised
    thumbnail.png  thumbnail-1280.png
    out/                MP4s and review stills (git-ignored)

References

  • references/setup.md: demo.config.json field by field, and asking the user.
  • references/discovery.md: finding the features in any stack, and turning them into a catalog.
  • references/script-format.md: the script table, voice style, bilingual naming, TTS files.
  • references/capture.md: the capture API, data, sign-in, languages, blur, manual capture for native apps.
  • references/direction.md: direction.js, timing, the language switch, and pitfalls.
  • references/recreated-ui.md: OS, browser and third-party screens.
  • references/review-export.md: review stills, export, thumbnail, hand off.

Habilidades Relacionadas