Screen Recorder

Screen Recorder

Produces a short .webm clip of a specific page section so an agent — or a reviewer reading a PR — can see motion that a static screenshot hides. Not a test suite, not a permanent fixture: every recording is a throwaway artifact written to .agent/recordings/ for one-shot visual review.

This SKILL.md is a thin index. Detailed rules live in rules/*.md and load on demand. Literal Playwright and ffmpeg boilerplate the skill emits lives in templates/*.md. Do not preload everything — load only what the current phase asks for.

When to use

Reach for this skill when any of the following is true:

• A diff changes animation, transition, or interactive motion code (@keyframes, transition, View Transitions, Motion layout, @starting-style, scroll-driven timelines).
• A still screenshot would not falsify the bug or feature claim — the proof requires at least two frames.
• A reviewer asks "what does this look like?" on a PR whose answer is a moving image, not a description.
• The animations skill has produced an animation and wants visual evidence it hits 60 fps and respects prefers-reduced-motion.
• The ux skill flagged a flow (drag, focus ring, hover reveal, expanding nav, modal entrance) where the asserted UX claim is about timing, not layout.

Do not reach for this skill when:

• A static screenshot is sufficient — capture a still directly (the pr-reviewer agent's visual pass reads stills locally; it never attaches them to the PR).
• The task is to author a durable Playwright test — use the e2e-testing skill.
• The input is an existing trace.zip — use playwright-trace-analyzer.
• The input is an existing screen recording (e.g., a user bug report) — use video-analyser.

Phase 0 — Preflight (mandatory gate)

Before recording anything, verify the environment. Halt and ask the user before installing tools.

Run these checks (read-only):

# 1. Playwright installed?
command -v npx >/dev/null && npx --no-install playwright --version 2>/dev/null

# 2. Chromium driver available?
npx --no-install playwright install --dry-run chromium 2>/dev/null

# 3. ffmpeg available (cropping + transcoding)?
command -v ffmpeg

Decision table:

Print exact commands; do not run silently. Full preflight rules: rules/preflight.md.

Phase 1 — Inputs

Collect, then confirm back to the user before running:

Echo the resolved inputs back as a one-screen summary before Phase 2.

Caller-specific overrides. When caller: pr-reviewer and out-format is unspecified, default to mp4 (GitHub previews .mp4 inline). When caller: animations and the immediate next step is a Skill("video-analyser") invocation, keep max-width: 768 and keyint: 15 — they are already analyser-optimal. Pass max-width: 0 only when a human reviewer has reported text-still-unreadable at 768 px (rare).

Phase 2 — Generate the recording script

Write a single-purpose Node.js script to .agent/recordings/<slug>/record.mjs using the template at templates/record.mjs.template. Substitution rules and the interaction recipe catalog are in rules/recording-script.md and rules/interactions.md.

Hard rules:

• Use chromium.launch({ headless: true }) — never headed, never webkit, never firefox (recording fidelity differs between engines).
• Pass recordVideo: { dir, size: viewport } on the context, not the browser. Playwright emits one .webm per page.
• Always await context.close() before reading the video path — the file is finalised only on context close.
• Cap the script at one page, one context, one recording per run. Multiple recordings means multiple runs.

Phase 3 — Run the script

node .agent/recordings/<slug>/record.mjs

Capture stdout / stderr. On non-zero exit, do not crop — surface the error and stop.

Resolve the produced .webm path from the script's stdout (the template prints VIDEO=<absolute-path> as its last line).

Phase 4 — Crop and downscale for the analyser

Use ffmpeg to crop the full-viewport .webm to the bounding box of the target element, then downscale to a max-width-px-wide output with a fixed 0.5 s GOP. The script in Phase 2 captures the bbox via locator.boundingBox() and writes it to a sibling bbox.json.

The defaults (max-width: 768, keyint: 15) are tuned for the video-analyser skill's Pareto knee — see the Analyser-optimised sizing section for the numbers. Net effect: 768 px wide keeps UI text legible at ~786 image tokens/frame on Sonnet, and the short GOP guarantees the analyser's keyframe-first sampling (Step 5a) lands on signal-dense scene transitions rather than falling back to uniform-time sampling.

Crop command, downscale filter, and format-conversion rules: rules/cropping.md.

If ffmpeg is unavailable, skip cropping with a one-line note and deliver the uncropped .webm.

Phase 5 — Deliver

Print a delivery summary:

Recording: <absolute path>
Format:    <webm | mp4 | gif>
Size:      <KB>
Duration:  <ms>
Viewport:  <w>x<h>
Cropped:   <yes (WxH at X,Y) | no — ffmpeg missing>
URL:       <recorded URL>
Selector:  <selector>
Interaction: <recipe or inline summary>

If the caller is another skill (Phase 6 below), return the path only — no narration.

Phase 6 — Integration callers

This skill is called by four other consumers via Skill("screen-recorder"). Full handshake spec: rules/integrations.md.

Callers pass inputs in their Skill() call body; this skill never asks the calling skill questions — it falls back to defaults and proceeds, or fails fast with one explanatory line.

Required Reading by Phase

Load on demand — do not preload.

Core Principles

1. Throwaway, not test. Recordings live in .agent/recordings/ and are never checked into git. Add .agent/recordings/ to .gitignore if it is not already covered.
2. One concern per clip. One URL, one selector, one interaction. If two animations need verifying, run twice.
3. Headless Chromium only. Headed mode introduces window-chrome that ruins the crop; other engines re-encode transform and filter differently.
4. Crop with ffmpeg, not with viewport gymnastics. Resizing the viewport to the element bbox changes layout (responsive breakpoints, container queries) and lies about what the user sees. Record the real viewport, crop after.
5. Respect prefers-reduced-motion explicitly. If the user passes reduced-motion: true, the recording must show the reduced variant. The animations skill calls this skill twice (default + reduced) to validate both paths.
6. No live URLs without consent. Recording staging or production captures real user data into a video file. Refuse unless the user has explicitly named the staging / production host.

Anti-patterns (one-liners — full lists in linked rules)

• Recording with headed: true and submitting the result as evidence (rules/recording-script.md).
• Sizing the viewport to the element to "auto-crop" — distorts layout (rules/cropping.md).
• Skipping await context.close() and reading a half-written .webm (rules/recording-script.md).
• Multiple page.goto() calls in one recording — the second navigation appends to the same video and confuses the viewer.
• Recording at localhost:3000 without checking the dev server is up (rules/preflight.md).
• Hard-coding selectors that drift (div > div:nth-child(3)) instead of data-testid or role (rules/interactions.md).
• Transcoding to .gif for anything over 4 s — the file balloons past 10 MB (rules/cropping.md).
• Committing .agent/recordings/ into git.

Definition of Done

• Preflight passed — Playwright, Chromium, and (if cropping requested) ffmpeg are present.
• Inputs echoed back and confirmed.
• record.mjs written from the template, no manual edits to the Playwright API surface.
• Script exited 0 and printed VIDEO=<path>.
• .webm exists at the printed path and is > 0 bytes.
• If cropping requested, bbox.json is non-empty and the cropped output exists.
• Delivery summary printed (or path-only return if called by another skill).
• .agent/recordings/ is in .gitignore (or covered by an existing pattern).