/demo

name: demo
description: Record a demo video of a web app feature or flow on a real desktop (Docker, Xvfb, XFCE, real X cursor), producing an mp4 plus a click/hover/scroll/type telemetry file. Takes a flow description, an existing demo name or path, or init. Use when the user says "record a demo of the checkout", "gravar um demo dessa feature", "make a screencast of this flow", "video for the changelog", "re-record the checkout demo", "refresh the demo video", or "demo init". Do NOT use for general browser testing or automation that needs no video (use playwright-skill), page debugging or network inspection (use chrome-devtools), or static screenshots.
metadata:
  author: github.com/wcalderipe
  version: '1.0.0'

**IMPORTANT - Path Resolution:** This skill can be installed in different locations (plugin system, manual installation, global, or project-specific). Before executing any commands, determine the skill directory based on where you loaded this SKILL.md file, and use that path in all commands below. Replace `$SKILL_DIR` with the actual discovered path.

Demo

Records a scripted flow of the local app as `video.mp4` (1440x900, 30fps, full X display with XFCE panel, Chromium window, and system cursor) plus `events.json`.

Input forms

The first word decides the form: `init` is a command; anything else is a demo name, path, or flow description.

1. **Flow description**, for example `/demo record the checkout paying by card logged in as a customer`. Pick a name, write `.demos/<name>/script.mjs`, record. 2. **Existing demo**, for example `/demo checkout-card-as-customer`, `/demo .demos/checkout-card-as-customer`, or `/demo .demos/checkout-card-as-customer/script.mjs`. Skip authoring and re-record as-is. If it fails loudly (the UI changed), fix the demo script, retry, and tell the user what changed in it. 3. **`init`**, i.e. `/demo init`: follow `references/init.md`.

Layout

One directory per demo, fixed file names, plus one optional config for all demos:

.demos/demo.config.mjs     settings for every demo (see Config)
.demos/checkout-card-as-customer/
  script.mjs     demo script
  video.mp4      last good recording
  events.json    telemetry of that recording
  failed.png     only after a failed run that reached the desktop
  failed.json    only after a failed run

A successful run replaces `video.mp4` and `events.json` and removes `failed.*`. A failed run leaves the previous good video untouched. `.demos/` is gitignored.

Names are descriptive kebab-case slugs of the specific flow, not the area: `<area>-<flow>[-<variant>]`, e.g. `checkout-card-as-customer`, `checkout-coupon-applied`, `admin-user-invite`. Before creating one, `ls .demos/` and reuse the existing name for the same flow instead of adding a near-duplicate.

Workflow

1. For form 1, read the views/routes of the flow to pick stable locators, and work out how to sign in (and with which test account) from the project's code and docs (AGENTS.md, README; `/demo init` sets that up). Then write the demo script (template below). 2. Record: `$SKILL_DIR/scripts/record <name>`. The first run builds the Docker image (tag hashed from the assets, so edits rebuild automatically). Before launching the browser the recorder checks that `app.url` (unset, `http://localhost:$PORT` from the environment or `.env`, else 3000) answers; if `failed.json` says `app not reachable at <url>`, start the app the way the project's AGENTS.md or README says, re-run, and stop what you started when done. If the app runs elsewhere, set `app.url` in the config. 3. Verify: extract 3-4 frames around the events and look at them. The `t` in `events.json` is seconds into the video.

   ffmpeg -loglevel error -y -ss 6.5 -i .demos/<name>/video.mp4 -frames:v 1 /tmp/frame.png

4. Report the `video.mp4` and `events.json` paths.

Script

Runs inside the container next to `lib.mjs`, so always import `./lib.mjs`.

Framing rules:

• Capture starts only when the demo script calls `record()`. Set the scene before it: browser open, logged in, starting page loaded. The video never shows the browser launching or an empty desktop.
• Never show the sign-in unless the user asks for it. Do it with plain Playwright before `record()`, not the animated helpers. Start on the page where the user's intent begins (e.g. `/admin/users` for "invite a user"), not on the home page.

Pacing: timings come from the `pace` config, so call helpers without timing arguments. Don't `hover` right before `humanClick` on the same target (the click already approaches it). Keep extra `sleep`s short: 300-500ms between steps, ~400ms after a new page loads.

import { launch, record, hover, humanClick, type, wheel, sleep, finish, APP_URL } from './lib.mjs'

const { page } = await launch()
await page.goto(`${APP_URL}/<sign-in-path>`, { waitUntil: 'networkidle' })
await page.getByLabel('<email-label>').fill('<test-account-email>')
await page.getByLabel('<password-label>').fill('<test-account-password>')
await Promise.all([
  page.waitForURL((url) => !url.pathname.startsWith('/<sign-in-path>')),
  page.getByRole('button', { name: '<submit-label>' }).click(),
])
await page.goto(`${APP_URL}/cart`, { waitUntil: 'networkidle' })
await record()

await hover(page, page.getByRole('link', { name: /Order summary/ }).last())
await humanClick(page, page.getByRole('link', { name: 'Checkout' }).first())
await wheel(page, 400)
await type(page, page.getByLabel('Coupon'), 'SAVE10')

await finish()

`lib.mjs` API: `launch()`, `record({ lead })` (starts capture and the event clock; required, a demo script that never calls it fails), `hover`, `humanClick`, `type` (click then key by key), `wheel(page, pixels)`, `moveTo(x, y, ms)` in screen coordinates, `settle(page)`, `mark(type, box)` for custom telemetry, `sleep`, `finish(ms)`.

Test accounts are project-specific: take them from the project's docs (AGENTS.md, README) or seed data, never guess.

Config

`.demos/demo.config.mjs`