Claude Eye: frame-by-frame animation analysis
You can't watch a video, but you can read images. This skill turns a video into a set of timestamped frames, has you look at each frame and record what every animated element is doing, and then turns those observations into a timeline that shows exactly when things fall out of sync. Timing bugs in CSS/JS animations are usually 100-300 ms off, which is too fast to see by eye but easy to see in a frame table.
Scripts live next to this file in scripts/. They need only Node 18+ and ffmpeg/ffprobe, with no npm install. Below, <skill> means this skill's directory.
1. Check prerequisites
Run ffmpeg -version. If it's missing, tell the user and give the install command for their OS (Windows: winget install Gyan.FFmpeg or choco install ffmpeg; macOS: brew install ffmpeg; Linux: sudo apt install ffmpeg). They will need a new terminal afterward. Don't install it yourself without asking.
2. Extract frames
node <skill>/scripts/extract_frames.mjs <video> --fps 5 --out ./claude-eye-output [--start S] [--end S] [--width 960]
This writes frames/frame_NNNN.png plus a manifest.json that maps each frame number to its timestamp. Always take timestamps from the manifest, never compute them in your head.
Budget your image reads. Every frame you read costs context, so aim for about 40 frames or fewer per pass:
- Short clip (under ~8 s): 5 fps across the whole thing is fine.
- Longer clip, or you don't know where the problem is: do a coarse pass first (
--fps 1or2over the whole video) to find where things move. Then re-extract only that window at higher fps (--start/--end,--fps 10-15) into a separate--outdirectory. Report the fine pass. - If the user names a moment ("around 3 seconds", "when the title comes in"), go straight to that window.
The default 960 px width is enough to judge opacity and position. Use a larger --width only if the elements are tiny.
3. Look at the frames and record observations
Read the frames in order with the Read tool. For each frame, note every visible text/UI element that is animating or could be: titles, subtitles, buttons, images, highlight spans, overlays, and so on.
Keep selector names stable across frames: pick a descriptive kebab-case name the first time you see an element (hero-title, subtitle, cta-button) and reuse exactly that name in every later frame. The timeline joins frames by name, so hero-title in one frame and title in the next become two different elements and the analysis falls apart. Include an element at 0% once it has appeared or is known to exist. That makes the "hidden → transitioning-in" points visible.
For each element, estimate:
opacity_percent(0-100). Judge it against the background and against the element's fully visible look in later frames. Also count partial reveals: a clip-path or mask wipe that is 40% revealed counts as 40.state: one ofhidden(≤10%),transitioning-in(rising),visible(≥90%),transitioning-out(falling). Compare with neighbouring frames to tell "in" from "out".- Optional:
has_gradient,has_blur, andnotesfor things like movement ("translateY ~20px above final position"), scale, blur amount, or color change. Movement and scale matter as much as opacity, so record them innoteswhen you see them.
Write all of it to <out>/frames.json:
[
{
"frame": 1,
"elements": [
{ "selector": "hero-title", "opacity_percent": 0, "state": "hidden" },
{ "selector": "subtitle", "opacity_percent": 0, "state": "hidden" }
],
"overall_state": "pre-animation",
"observation": "Blank hero area; nothing rendered yet."
}
]
frame must match the manifest's frame numbers. Timestamps are filled in from the manifest. For long runs, write the file in chunks as you go instead of holding 40 frames in memory.
Opacity from a compressed video is approximate. A difference of ±10% between frames is noise; patterns across several frames are the signal.
4. Build the report
node <skill>/scripts/build_report.mjs ./claude-eye-output --context "what the animation is supposed to do"
This produces report.md (summary, opacity timeline table, per-element timing, transition points, desync events, observations) and analysis.json. A desync is a frame where some elements are fully visible while others are still transitioning, with more than 40 points of opacity spread between them. Use --spread N to make that stricter or looser.
5. Interpret: this is where you add value
The script finds when things happen. Your job is to say why and what to change:
- Replace the
<!-- RECOMMENDATIONS -->section ofreport.mdwith specific findings. Read the element timing table: for example, "subtitlestarts 200 ms afterhero-titleand reaches full opacity 400 ms later, which points to a longer duration plus a delay." Convert frame gaps to milliseconds using the frame spacing (1/fps). - If the user's source code is available, find the CSS/JS for these elements (
transition,animation,@keyframes,transition-delay, framer-motion/GSAP configs) and point to the exact lines that explain the observed timing. Propose the concrete fix. - Mention your timing precision (±1 frame = ±1/fps s). If a conclusion depends on a gap smaller than one frame, re-extract that window at a higher fps before claiming it.
Then give the user a short summary in chat: what animates, the key timings, each desync with its timestamp and likely cause, and the fix. Include the path to report.md.
Not just opacity
The report pipeline is built around opacity/visibility, but the same frame-reading approach works for other questions, such as layout shift, an element jumping, flicker (one frame of wrong state), a loader spinning when it shouldn't, or easing that looks linear. For those, still extract frames and read them. You can skip build_report.mjs and answer directly with frame-referenced timestamps from the manifest.