cap-demo — Claude Code skill: video demos and installation
The cap-demo Claude Code skill turns a page URL into a short product demo with a 3D camera, branded background, and music. It runs when an agent is asked to make a product video.
MIT ★ 184 updated 2026-11-16
npx skills add joeseesun/capwise --skill cap-demo -a claude-codeWhat cap-demo does
cap-demo opens a page, records browser actions, and exports an MP4 with 3D camera shots, a brand-colored background, a synthetic cursor, and music. It picks a CTA or a scroll path; an agent-driven run can inspect frames and reshoot failed transitions.
It requires macOS on Apple Silicon, Node 18+, Python 3, ffmpeg, ffprobe, and the cap CLI on PATH. macOS screen-recording permission must be granted to cap. Run npm install inside the skill directory on first use. Playwright Chromium must also be cached; if it is not, install it with npx playwright install chromium. Windows and Linux are unsupported.
What it helps with
- record a product page from its URL
- create a short demo with 3D camera shots and music
- reshoot a video when a CTA leads to a dead end
Example prompts for the agent
- Make a short product demo video from this page URL.
- Record the page and create a demo with 3D camera shots and music.
- Reshoot the demo by scrolling instead of clicking the CTA.
How to install cap-demo
1Skills CLI (Vercel)
npx skills add joeseesun/capwise --skill cap-demo -a claude-code2Manually: put the files in place
~/.claude/skills/cap-demo/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/cap-demo/
1Skills CLI (Vercel)
npx skills add joeseesun/capwise --skill cap-demo -a codex2Manually: put the files in place
.agents/skills/cap-demo/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add joeseesun/capwise --skill cap-demo -a cursor2Manually: put the files in place
.cursor/skills/cap-demo/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install joeseesun/capwise apps/cli/skill/cap-demo2Manually: put the files in place
.github/skills/cap-demo/SKILL.md1Skills CLI (Vercel)
npx skills add joeseesun/capwise --skill cap-demo -a gemini-cli2Platform CLI
gemini skills install https://github.com/joeseesun/capwise --path apps/cli/skill/cap-demoManually: put the files in place
.devin/skills/cap-demo/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about cap-demo
How do I install cap-demo in Claude Code?
Run npx skills add joeseesun/capwise --skill cap-demo -a claude-code. The skill file is installed at ~/.claude/skills/cap-demo/SKILL.md.
What does cap-demo do?
It records a page from a URL and turns the capture into a short MP4 product demo with 3D camera shots, a branded background, a cursor, and music.
What does cap-demo need to run?
It requires macOS on Apple Silicon, Node 18+, Python 3, ffmpeg, ffprobe, and the cap CLI on PATH; cap needs macOS screen-recording permission. playwright-core and a cached Chromium build are also needed; install Chromium with npx playwright install chromium if no cached build is available.
Source text
SKILL.md · MIT
---
name: cap-demo
description: Generate a cinematic 3D product-demo video from any URL — scouts the page, records it with virtual input, and treats it with Cap's 3D camera, brand background, and music.
---
# cap-demo
Give it a URL, get back a short, cinematic product-demo video. The pipeline
scouts the page headlessly, shoots a headed browser with **virtual input only**
(CDP mouse/keyboard — the user's real cursor is never touched), records with
Cap's CLI, then treats the recording with Cap's 3D camera, a brand-matched
background gradient, a synthetic cursor, and music, and exports an mp4.
> **macOS only (for now).** This skill records via Cap's window capture and
> resolves a cached Playwright Chromium under
> `~/Library/Caches/ms-playwright`, both of which are macOS-specific today.
> Apple Silicon is assumed (the bundled Chromium path is `chrome-mac-arm64`).
## The skill directory
`<skilldir>` below is the directory this `SKILL.md` was installed into. `cap
agents install` writes it next to the main `cap` skill, so it is one of:
- Claude: `~/.claude/skills/cap-demo`
- Cursor: `~/.cursor/skills/cap-demo`
- Codex: `<CODEX_HOME>/skills/cap-demo` (default `~/.codex/skills/cap-demo`)
There is no `cap-demo` binary on PATH — the `cap-demo` command is just
`node <skilldir>/cap-demo.mjs`. Alias it if you like:
```
alias cap-demo='node <skilldir>/cap-demo.mjs'
```
## Requirements
- **macOS on Apple Silicon.** Windows/Linux are not supported yet.
- **Node 18+**, with `playwright-core` vendored into the skill. Run `npm
install` once inside `<skilldir>` on first use. It **reuses an already-cached
Chromium** under `~/Library/Caches/ms-playwright`; if none is cached, run
`npx playwright install chromium` once.
- **`python3`** and **`ffmpeg`/`ffprobe`** on PATH.
- The **`cap` CLI** on PATH (Cap Desktop, https://cap.so) with macOS
**screen-recording permission** granted to it. Both stages otherwise resolve
the binary from `CAP_BIN`; if neither is set they error clearly.
## One-liner
```
cap-demo https://website.com
```
Output lands at `<outDir>/<slug>-demo.mp4` (default `<tmp>/cap-demo/<slug>/<slug>-demo.mp4`).
## Two modes
- **Deterministic** (`cap-demo <url>`): fixed heuristics, no agent in the loop.
Scores the best CTA, picks click-through vs scroll, paints a brand gradient
from the page colors, picks music by brand darkness. Good, ~70% quality. Use
it for batch runs or when you cannot watch the frames.
- **Agent-driven recipe** (recommended, ~95% quality): the agent runs the
same steps but frame-QAs each stage and applies judgment — sets the brand
color by eye, matches export fps to the real capture rate, reshoots on a
dead-end CTA, regrades until the beats read. This is the path that produced
the shipped demos. Follow the recipe below.
## The agent recipe
Run the two stages by hand so you can inspect between them. Both scripts live in
this skill; the orchestrator just chains them.
### 1. Scout + shoot
```
node <skilldir>/lib/scout-shoot.mjs <url> <outDir> <slug> [--story click|scroll]
```
- Writes the recording to `<outDir>/<slug>.cap` and the beat log to
`<outDir>/<slug>.timeline.json`.
- Prints a final JSON line: `{"slug","story","scout":{title,hero,accent,pageBg,ctaText}}`.
Read it to see what it decided (story, chosen CTA, brand colors).
- It already: kills stale test-chrome, closes Finder windows, dismisses cookie
banners, injects the shimmer div, matches the capture window by exact page
title (asserts a single match), and logs the virtual cursor path.
**Story choice.** Leave it to auto for most sites (a strong content CTA →
`click`, otherwise `scroll`). Force `--story scroll` for product one-pagers that
showcase best as a scroll of their own sections, or when the top CTA dead-ends
at a booking/login page.
### 2. Frame-QA the raw recording (before treating)
Extract a few beat frames and **look at them**:
```
ffmpeg -y -ss <t> -i <outDir>/<slug>.cap/content/segments/segment-0/display.mp4 -frames:v 1 /tmp/raw-<t>.png
```
Check: the right window/content is captured (no leftover footage from a prior
shoot), no cookie banner leaked in, the CTA click did **not** dead-end at a
booking calendar or login form, and the **end** of the clip is clean (no desktop
or Finder window bleeding into the bottom of the capture). If any of that is
wrong, reshoot with `--story scroll` or a better landmark before spending an
export.
### 3. Treat + export
```
python3 <skilldir>/lib/treat.py <outDir> <slug> [--music ID] [--quality 4k|hd] [--bg-gradient FROM_HEX,TO_HEX]
```
- Aligns beats to video (tail-anchored: the video can be **shorter** than the
event log — never trust event times blindly), trims dead time, aims three 3D
shots at the logged landmarks, paints the brand gradient, synthesizes the
cursor track from the bundled cursor assets, copies music, exports the mp4.
- **Set the brand background by eye** when the site is gradient-heavy or
light/pastel: `getComputedStyle` lies on those (e.g. a site that looks white
with lavender accents can sample as black). Look at the raw frames and pass
`--bg-gradient FROM_HEX,TO_HEX` (light sites → a soft light gradient; dark
sites → a deep tint of the brand hue).
- **Match export fps to the real capture rate.** `cap record --detach` can
engage late and the window capture stalls timestamps on static pixels, so the
true rate is often ~58, not 60. Check it and avoid the 58-vs-60 judder:
`ffprobe -v error -select_streams v:0 -show_entries stream=nb_frames,duration -of csv=p=0 <cap>/content/segments/segment-0/display.mp4`,
then pass `--quality hd` (60) only if the capture is really ~60, otherwise
leave fps at the source rate (omit `--quality`).
### 4. Frame-QA the export, then regrade if needed
Extract 4 beat frames from `<outDir>/<slug>-demo.mp4` and look: each beat
readable, a typing shot aimed at the **text-entry point** (not the field
center), no window/desktop bleed, clean fps, music fades feel right. If a shot
reads too tight or the aim is off, adjust and re-export. The reference 3D poses
were tuned on full-desktop captures; a browser-window capture fills the card
more, so distances can read ~30% too tight — back the zoom off if so.
### 5. Deliver
Ship `<outDir>/<slug>-demo.mp4`.
## Hard editorial rules (encode these every time)
- **12s max** total. The tail is shaved evenly if the cut runs long.
- **A camera cut MUST be a content cut.** Every 3D perspective change lands on a
different section/page — the shot boundary sits exactly on the clip cut or the
scroll into new content. Never cut the camera mid-idle.
- **Cut on action, trim dead time.** Cut on the click; resume on the loaded
page. Trim page-loads and loading-state frames — never let a blur-up or
spinner leak into a shot tail (frame-check the cut points).
- **Aim at content, not the container.** Shots are aimed at landmarks (hero, the
clicked CTA, the destination header), not copied pans. Blur focus rides the
aim.
- **One motion system.** All emphasis lives in the 3D shot (a dolly-in is the
click punch). Never stack 2D zoom segments on 3D shots — the two systems fight
and read as jarring.
- **Hands off.** Virtual input only; the user's real cursor/mouse is never
moved. The on-screen cursor is synthesized post-hoc from the logged glide path.
## Options reference
Orchestrator (`cap-demo <url> [flags]`):
- `--out DIR` — output directory (default `<tmp>/cap-demo/<slug>`).
- `--slug NAME` — project slug (default: the URL host, dashed).
- `--music ID` — music track id (see below). Default: chosen by brand darkness
(dark → `lofi-cinematic-pulsebox`, light → `sunday-mood-lofi-cafe-upbeat-bluelike`).
- `--quality 4k|hd` — `4k` = 3840x2160 / 60fps / maximum / filesize-optimized;
`hd` = 60fps / maximum. Omit for the source-rate default.
- `--story click|scroll` — force the storyboard (default: auto).
`lib/treat.py` extra flags (when running the stages by hand):
- `--bg-gradient FROM_HEX,TO_HEX` — override the brand gradient by eye
(e.g. `--bg-gradient E4DCF8,C6BAEA` for a light lavender, or `261A40,0C0914`
for a deep purple).
**Bundled music** (a premium/dark/light/moody spread):
`lofi-cinematic-pulsebox` (moody/premium), `lofi-hip-hop-leberch` (dark),
`sunday-mood-lofi-cafe-upbeat-bluelike` (light/upbeat), `lofi-smooth-pulsebox`
(light/smooth). Music resolves only from the skill's bundled
`assets/music/<id>.mp3`; an unknown id errors.
**Binary resolution** (both scripts): Cap binary = env `CAP_BIN`, else `cap` on
PATH, else a clear error. Chromium = newest cached
`~/Library/Caches/ms-playwright/chromium-*` (macOS), else the pinned
`chromium-1228` build.
## For dev tools / typing showcases (closeup variant)
For dev tools with a live terminal or code on screen, a bespoke storyboard beats
the generic click-through. Scout for `[class*=terminal]` / `pre` / `code`,
scroll each to center, dwell ~2.7s (live terminals animate = free motion). The
**closeup shot recipe**: a gentle tilt (tiltX 10-13, tiltY 9-13, rotateX -4) so
text stays legible, a tight slow push-in zoom (0.72-0.82), and blur focus locked
ON the element (focusX = the element's fraction, small focusSize ~0.55). Keep it
a single continuous clip (no editorial cut) so scrolls stay smooth — cuts are
3D-only. Aim typing shots at the **text-entry region**, not the field center.
Rebuild a bespoke shoot from `lib/scout-shoot.mjs` as the base when a site
deserves it (edit a fresh copy — do not sed/splice shot arrays, overlapping
offsets corrupt the file).
© joeseesun · MIT · joeseesun/capwise