videofeedback

A Claude Code skill for analyzing screen recordings. Share a .mov or .mp4 with your agent and get a structured breakdown of what's happening — UI state changes, interaction sequences, bugs, and visual anomalies — without needing to describe it in text.

Why

Describing UI behavior in text is lossy. "The modal flickers when you click the button" doesn't tell Claude where the flicker happens, what it looks like, or what state precedes it. A 10-second screen recording does. This skill extracts key frames via FFmpeg, reads them into Claude's context, and produces a frame-by-frame analysis anchored to specific moments in the recording.

Requirements

• macOS
• Claude Code
• FFmpeg (brew install ffmpeg)

Installation

Copy SKILL.md into your project's skills directory:

mkdir -p .claude/skills/screen-recording
cp SKILL.md .claude/skills/screen-recording/SKILL.md

Claude Code will automatically detect and register the skill on next launch.

Usage

/screen-recording path/to/recording.mov
/screen-recording path/to/recording.mov "focus on the hover state at 0:08"

If you omit the focus hint, Claude will ask what to look for before proceeding.

Recordings under 3 minutes work best. For longer recordings, use QuickTime's trim tool (Edit -> Trim) to isolate the relevant segment first.

How it works

1. Checks for FFmpeg
2. Gets video duration — warns if over 3 minutes
3. Creates a timestamped directory inside your project (screen-recordings/<timestamp>/)
4. Runs scene-detection frame extraction (threshold 0.1, calibrated for subtle UI transitions)
5. Falls back to 1fps uniform sampling if scene detection yields fewer than 3 frames
6. Generates a contact sheet overview image
7. Reads all frames into Claude's context
8. Produces a structured analysis of the interaction sequence

Notes

• Retina displays: macOS Retina recordings are 2x logical resolution. The scale=1280:-1 filter normalizes this automatically.
• drawtext timestamps: The Homebrew FFmpeg build does not include libfreetype, so timestamp overlays are not available. Frames are numbered sequentially; Claude correlates them to timestamps using duration and frame count.
• Temp files: Extracted frames are written to screen-recordings/ in your project root. Claude will remind you of the path at the end of the session so you can remove them.

Related

• aieyes — screenshot-grounded development via MCP (for live sites, not recordings)