You are driving the Ultrademo pipeline in this repo: Playwright capture → storyboard.json → TTS → Remotion render. Your job is the judgment layer: scout the app, write the script, author the flow, verify the output. The pipeline is deterministic; the storyboard is the single source of truth.

Every file path you show the user is absolute. Sessions often run in worktrees, background jobs, or nested folders the user can't easily locate - a relative path like is a dead end for them, an absolute path is clickable in most terminals and IDEs. This applies to the file, the script outline, the flow file, and the finished MP4. When the user needs to EDIT a file (, the outline), also offer to open it for them in a separate window: on macOS, on Windows, on Linux, or if VS Code is around.

If the current folder does not contain the Ultrademo pipeline ( absent), the skill was installed standalone and needs its workspace. The workspace is not a third-party download: it is the same public Apache-2.0 repository this skill is distributed from (, the same name the user just typed into the install command) - one codebase, skill and pipeline versioned together. Its dependencies resolve strictly from the committed , and no step pipes remote content to a shell. Setup, in or a location the user names:

git clone https://github.com/new-xp/ultrademo ultrademo-workspace
cd ultrademo-workspace
npm ci                                          # lockfile-exact dependency install
node_modules/.bin/playwright install chromium   # browser version pinned via the lockfile'd Playwright

Then:

Do not improvise a partial pipeline - the skill only drives the real one.

If the pipeline is already there, check it's fresh (skill instructions and pipeline code version together - stale clones miss features these instructions assume). At the start of a session, if the workspace is a clone of the upstream repo: (a few seconds; offline or a private fork → skip silently and continue), then compare . If behind, tell the user what's new () and offer to - never pull silently, their workspace may carry local edits (uncommitted changes → offer first or leave it; their call). After a pull, re-run if changed. If the skill was installed standalone via the skills CLI, also remind the user that refreshes the installed skill copy to match; when the workspace folder itself is open in the agent, the pull already updated the skill in .

Never dead-end on an install summary. The moment the workspace is ready, continue straight into intake (Step 0) and ask the user what they want to make - a fresh install with no next prompt strands them. Open with something concrete, e.g.: "Workspace is ready. What should we demo first? Send me the app URL and a line on what to show, and I'll scout it and draft a script." Then run the Round 1 questions below.

Collect inputs in a few short, batched rounds - not one overwhelming wall of questions. Use the host's structured-question UI (AskUserQuestion in Claude Code), not free-text questions typed into the chat - one structured call with 2-4 questions per round, each with concrete options, so the user clicks instead of composing an essay reply. Fall back to inline prose questions only when the host has no such tool. Only ask what's still missing or not discoverable. Secrets and credentials never go in the chat - they go in files (the user was uncomfortable pasting them, and it's the right security posture anyway).

Phasing is deliberate: Round 1 is enough to start scouting; Round 2's questions become concrete once you've seen the app, so they don't feel abstract or overwhelming. Run if this is the first video in this workspace.

Also ask for context (recommended, not required - it makes scouting faster and narration sharper):

Precedence rule: context steers where to scout and what vocabulary to use, but it is never evidence - overviews can be stale or aspirational. The coverage map verifies every beat against the live app, and narration claims still require on-screen proof.

Explore the live app with a throwaway Playwright script (headless, viewport 1920x1080). Learn the app's own vocabulary, find exact headings/button labels for selectors, and screenshot key pages for yourself. Produce a short scout report for the user: surfaces found, proposed golden path, risks, and an estimated scene count for the brief - that estimate is what makes the Round 2 duration options real.

If the codebase is available, mine it before opening the browser - it makes scouting faster and the flow sturdier:

Code is a map, not evidence: it shows what is built, not what is deployed, enabled, or populated. The coverage map below and every narration claim still verify against the live app in the browser.

Hard rules while scouting a real or production app:

The scout report must include a coverage map: one row per brief item - FOUND (route + exact heading as evidence), PARTIAL, or NOT FOUND. This grounds the script in reality:

Draft a scene-by-scene outline and present it in full in the chat message itself - the chat is the review surface. The user reads it there and replies with edits in plain words ("scene 3 is too salesy", "swap 4 and 5"); you fold them in and re-post the changed scenes. Do not make finding a file the price of reviewing the script - users in worktrees, background sessions, or unfamiliar folders will never locate it. Also write the same outline to a markdown file for anyone who prefers editing inline, and give its absolute path; treat the file as the mirror, the chat as the gate. Per scene: narration line, what's on screen, media type ( / / ), estimated seconds. Include open questions. One idea per scene; put the emotional peak (a live result, a reveal) around two-thirds in. For MARKETING demos (not tutorials), sanity-check the arc against the 7-beat lens: hook → context → agenda → transformation story → feature flow → objection pre-empt → close; feature-listy drafts fail it.

Narration voice (default = the Enthusiast): first person, someone showing a colleague a product they genuinely like - contractions always, real opinions ("what won me over is...", "this is where it gets good"), a little energy. Not a brochure, not a flat feature-reader. The single biggest quality lever, because AI-default narration is the #1 rejection reason (see CLAUDE.md quality bar). Write it lively on purpose:

(Other voices exist if the user asks: the Direct Guide = second-person, tight, time-respecting; the Understated = dry, minimal, Screen-Studio restraint. Default to the Enthusiast unless the user picks one or the brand calls for it.)

Evidence rule for narration: every claim in a scene's script must be visible on screen in that scene. The video is evidence-grade - it demos what IS, never roadmap. No aspirational claims, no invented data presented as product truth.

Narration-timeline rule: narration must track the visual timeline within the scene. Never state results before they are visible ("three tasks" while the first is still being typed); counts and payoffs come after the action lands, or stay quantity-neutral ("add each task the same way"). Write lines whose spoken length roughly matches the scene's action length - the renderer auto-fits clips up to 1.3x speed, but past that you get dead air or rushed footage; trim flow pauses or split the scene instead.

Wait for the user's edits; fold them back verbatim. Do not start capture until they confirm.

Create the project folder using the naming convention

projects/<app>-<feature-or-topic>-<YYYY-MM-DD-HHMM>/

(timestamp = now, at authoring; use the name the user confirmed in Round 1) and translate the locked script into (start from ). Tell the user the flow file's absolute path when you create it - it's the one file they may want to read or tweak by hand. Keep the same project folder across retakes - it holds the flow, the TTS cache, and every take's assets; a new name means starting from scratch. If the flow mutates app state, write the reset recipe as and run it before each retake. Everything for the video lives in that one folder (, , , ). Then:

npm run capture -- <project>
npm run tts -- <project>               # add --redo <sceneId|all> to force re-synthesis
npm run render -- <project>            # 16:9 MP4
npm run render -- <project> --vertical # 9:16 - see policy below
npm run render -- <project> --gif      # GIF export
npm run render -- <project> --no-captions   # opt-in: finalized video without burned-in captions
npm run render -- <project> --stems         # opt-in: clean video + narration.mp3 + captions.srt for external editing (finalized video is still rendered alongside)
npm run render -- <project> --caption-theme=bar --caption-size=lg   # try a caption style for one render

Run those in that order every time: capture rewrites

storyboard.json

without the audio fields, so a render straight after a re-capture is silent. Re-running first costs nothing when narration is unchanged (per-line cache).

Default deliverable is the finalized video. Offer / only when the user says they'll edit before publishing - do not produce them unasked.

Two flow-level switches: a scene with is dropped at capture without deleting its definition (use it for honest-failure renegotiations - keep the scene and the reason in a comment). A flow-level string is added via to every page - use it for on-camera HUD overlays (keycap callouts for keyboard-driven features, a live URL chip reading real for URL-payoff moments, since Playwright records neither keystrokes nor the browser's URL bar). Overlays must only VISUALIZE real page state and events, never fabricate app UI - and must respect the caption band: the bottom ~200px of frame carries burned-in captions, so anchor HUD elements above it (proven layout: URL chip , keycaps ).

Captions and title cards are storyboard-level, set on the flow (carried straight into by capture): where theme is (default - light text with a dark stroke and no background box; reads well over most screens, but over content-dense pages recommend / instead, per Round 2) / (dark chip) / (full-width lower third), size , position . is karaoke word-highlight, and it only works on the ElevenLabs voice (the TTS step stores per-word timings from ElevenLabs' with-timestamps endpoint; Piper/ produce no timings so captions stay static): (active word bright, rest dimmed), (brand chip under the active word), or (accent sweeps across each word as it's spoken, CapCut/TikTok style - the glyphs stay visible, it's a color fill not a block). Recommend whenever the voice is ElevenLabs - static is only the technical default and what free voices get; the user picks. The render flags override the storyboard for a single render so you can try a look without re-capturing (don't tint whole captions the brand color - it hurts legibility; brand tints the slides). UI literals are the one sanctioned tint: any double-quoted span in a scene's script renders in the literal color (, default sky , to override) with the quote marks stripped, in static and all highlight modes; the wipe sweeps literal words in that color too. It is deliberately distinct from the karaoke accent so a settled literal never reads as the active word - which is why the script convention quotes exact on-screen strings and nothing else. Intro/outro slides are set via (rendered as a title card over a framed app screenshot, auto-filled from the first captured scene - pass to override; puts the text left and the screenshot right instead of stacking them - nice when the first screen is tall or busy; vertical renders always stack) and ; sets the slide accent. narrates the slide: TTS voices it like a scene line ( / to force re-synthesis), audio starts ~0.75s after the card appears so the viewer reads it first, captions run on the slide, and the slide holds until the line finishes (minimum 3s; a narrated slide adds roughly its line's length). The whole video already fades from black at the open and to black at the close, and scenes hard-cut between each other (no inter-scene fade - that dip to dark was a visible flash).

Vertical policy: offer the 9:16 cut only when it earns its crop - the app has a mobile-responsive view (capture it at a mobile viewport for real vertical footage) or the content genuinely survives cropping. Cropping a dense desktop UI to 9:16 hides most of the screen and is usually not worth shipping; ask the user before producing it. Voice tuning: (default 0.45; raise toward 0.6+ if narration prosody sounds erratic) and are env-tunable, and changed settings bust the per-line cache automatically.

Craft notes that make output read professional:

Known traps: prefer over (framework origin checks); custom dropdowns need click-the-trigger-then-click-the-option, not ; iframe content needs / + keyboard; stateful apps need their reset recipe run before every capture; a text / toggle is often a , not a button. From editor-style apps (docs, wikis, boards): SCOPE every selector to the app's content container (a blind click on chrome once trashed a page mid-scout) and prefer exact matching over substring ; hover-revealed controls sometimes refuse to fire mid-editing-session - an unrecorded settles the page without the video ever seeing it; UI text controls can collapse to icons as state changes (scout the state you'll capture in, not just the initial state); kanban/board drags = → → → ; park the cursor on neutral ground at the end of every clip so no hover tooltip sits in the freeze frame; deletions often have confirmation dialogs - reset recipes must handle them; passwordless email-code logins: request the code, hold the session, have the user relay the code, then verify the session headlessly before capturing. From big production sites: they may never fire the event - use on every / - and may throttle rapid successive captures (30s+ responses; raise timeouts and wait the throttle out, don't hammer); pages that autofocus a search input on load swallow the next keyboard shortcut - press Escape first; headless Chromium can defer anchor scrolls (the hash and highlight land but the view stays put) - reproduce the app's own so the payoff is on camera. From dense table-based apps (CRMs and the like): apps render HIDDEN duplicate copies of buttons/tabs for measurement - suffix text selectors with or clicks resolve to the hidden twin; when single AND double clicks do nothing on an editable element, hover it and look for a mini-toolbar (pencil/copy icons) - the pencil is the real edit affordance, and a dblclick at center often hits the copy icon instead; a soft-focused cell suppresses OTHER cells' hover affordances - press Escape and hop the cursor elsewhere to re-arm; dropdown options live in body-level portals and can share text with chips elsewhere on the page - scope the pick geometrically (e.g. the match below the picker's search input), not by text alone; "Delete" in many SaaS apps is SOFT and uniqueness checks still see deleted records ("This record already exists" on the next take) - reset recipes must permanently destroy (look for a "Deleted at"/trash filter view -> right-click -> permanently destroy); apps with rotating refresh tokens log the profile out if two automation processes overlap on it or one is killed mid-run - use the auth profile strictly sequentially and keep a scripted headless re-login handy for password accounts. The auth escape hatch for hostile sign-ins: some human-verification checks reject EVERY automated browser (bundled Chromium AND real Chrome under Playwright - the CDP layer is detected), and magic links are bound to the browser that requested them, so relaying a link cross-browser fails. The working recipe: launch the user's real Chrome MANUALLY on the capture profile dir (), have the user sign in by hand and quit that Chrome instance CLEANLY (Cmd+Q - killing the process loses the just-written login state), then capture with + in the flow (Playwright's default mock keystore cannot read session state a normally-launched Chrome saved). If verification keeps failing, retry in a FRESH profile dir - a dir that has seen failed automated attempts stays flagged. In keyboard-first apps: shortcuts fire on the HOVERED element (hover the row, then press the key - beats fighting context menus whose item text collides with page labels), and success toasts auto-dismiss, so click a toast's link in the same scene that triggered it.

Honest-failure rule: if a scripted beat turns out uncapturable mid-execution (feature behind a flag, unreachable selector, an action that would mutate production), stop and renegotiate that scene with the user - do not ship around the hole. Never substitute a placeholder, mock, or fabricated frame for a failed capture. The final summary always states any deltas versus the locked script.

Never declare success unrendered-eyes: extract frames () at each scene's midpoint and actually look at them. Check: the right thing is on screen, captions readable, cursor sensible, redaction applied, money-moment lands, and NO visible secrets anywhere (URL-bar tokens, API keys in forms, real emails) - redact and re-capture if found. Pacing test per scene: every frame has a job; every second earns the next. Fix selector/timing issues and re-run; captures are cheap unless actions cost credits.

Present: the video path, duration, and per-scene check frames. Ask for scene-level notes. Apply fixes at the cheapest layer: narration edit = re-TTS + re-render (~2 min); zoom/order = re-render only; UI changed = re-capture that flow. Then finalize: offer the vertical and GIF variants.

Same project folder, always: run , then . Unchanged narration is fully cached (a visual-only refresh re-bills nothing). Previous renders are auto-archived to so the user gets a before/after pair. If the codebase is available, read the diff since the last capture first - it usually names the changed surface and broken selectors before you re-run anything. Then, by what the UI update did: