reelbench-skills: Claude Code and Codex skills that turn a finished video into a shot-by-shot breakdown

The problem: shot breakdown is tedious, and models are bad at counting frames

Breaking a finished video into a shot table means writing down, for every cut, how long the shot ran, what framing it uses, what the camera does, and what is on screen. Doing that by hand for a three minute piece is slow. Handing the whole job to a language model is worse, because a model reading a video description will invent cut points and durations that do not match the file.

reelbench-skills splits the work along that seam. The README describes video-shots as pulling a finished film apart into a per-shot analysis table covering duration, shot size, category, camera movement, frame content and rhythm, and it states the division of labour directly: cut points and durations are measured by ffmpeg, and the model only judges the few things that need judgement, with 15 quality gates checked off one by one. That is the design argument of the repository. Measurement is deterministic; interpretation is not, so the two are kept apart.

The audience is narrow and specific. These are skills for Claude Code and Codex, so you need one of those agents installed. The README says the dependencies are only node 18 or newer and ffmpeg with ffprobe, with zero npm dependencies and zero API key, using the current session quota. There is no server component, no database, and no account.

How video-shots works: ffmpeg measures, the model judges, 15 gates check the result

The mechanism visible in the repository is a pipeline that produces a set of files rather than a chat answer. In demo-report, the README lists shots-report.html as the interactive report, shots.json as the main shot data for 53 shots, shots.md as a Markdown shot table, track.json as a per-frame difference motion curve described as machine evidence, and frames/ holding two keyframes per shot, 106 images in total.

That file layout is the architecture. track.json is the raw signal from frame differencing, which is where cut locations come from. shots.json is the structured result after the model has labelled each shot. The HTML report is a view over both, and the README notes it is a single file with an embedded player that highlights the current shot during playback, jumps to a shot when clicked, and offers a searchable, filterable, sortable shot table in list and card views with first and last keyframes side by side. It states the page has zero external dependencies and opens offline by double-clicking.

The 15 quality gates are the part worth scrutinising. The README says they are checked off one by one, which implies a checklist pass over the output rather than a probabilistic score. It does not publish the criteria for those gates, so you cannot tell from the repository alone what would fail and what would merely be flagged. Treat the gate count as a claim about process, not a guarantee about accuracy.

The second skill, video-sync, takes the opposite direction. It composites a video with its shot information: footage on one side, the shot sheet on the other, with the information switching as the shot changes and the table scrolling and highlighting in step. The README says horizontal videos stack top and bottom while vertical videos sit side by side, and that changing the layout means editing one CSS file.

Installing reelbench-skills and running a first breakdown

The README gives a clone-and-install path. The install script symlinks the skills into ~/.claude/skills/ and/or ~/.codex/skills/, whichever is present, and the README states that a git pull takes effect immediately afterwards because the links point at the working copy.

git clone https://github.com/eternityspring/reelbench-skills.git
cd reelbench-skills
./scripts/install.sh

The script accepts flags for narrowing the target. Use --claude to install only into Claude Code, --codex for codex only, a skill name such as video-shots to install a single skill, and --uninstall to remove the symlinks.

./scripts/install.sh --claude
./scripts/install.sh --codex
./scripts/install.sh video-shots
./scripts/install.sh --uninstall

If you would rather not use symlinks, the README offers a plain copy, noting that a skill is self-contained and works once copied.

cp -r skills/video-shots ~/.claude/skills/

Before any of this, confirm the two dependencies are on the path. The README names node 18 or newer and ffmpeg with ffprobe, and gives the macOS install line.

brew install node ffmpeg

The quickest way to see what the output looks like without running anything is to open the committed demo. The README says demo-report/ is the complete output of running the pipeline on demo-video.mp4, a 202.9 second AI short, yielding 53 shots, an average shot length of 3.83 seconds, 15.7 cuts per minute, and all 15 quality gates green. Cloning the repository and double-clicking demo-report/shots-report.html shows the report before you spend session quota on your own footage.

The long take problem, and where the shot table stops being useful

The repository documents its own failure case rather than hiding it. The README describes demo-report-en/, the same pipeline run with --lang en on a 287.4 second English clip, producing 46 shots with an average length of 6.25 seconds and a longest shot of 46.92 seconds. It then states plainly that scene detection did not land a single cut in that stretch, because it really is one unbroken take.

That is honest, and it is also the boundary of the tool. A shot table is a description of editing structure. Where there is no editing, there is nothing for the detector to find, and the model has no cut to label. If your material is long interviews, screen recordings, or single-take performances, video-shots will hand you a table with one row and a very large duration, which is correct and nearly useless.

The dependency on ffmpeg and ffprobe is another practical limit. Those are not always installable in restricted environments, and the README does not document a fallback. There is also no release artefact: the repository has no published releases, so the install path is git clone and the update path is git pull. Nothing in the README describes version pinning, rollback, or how a change to a skill would be reverted if a newer commit produced different labels on the same footage. That is a real gap for anyone who wants reproducible reports across months.

Finally, the repository is HTML-first. The primary language listed for the project is HTML, and the deliverable is a single-file interactive page. If your downstream consumer is a spreadsheet, a database, or a Python script, shots.json and shots.md are the useful outputs and the HTML is overhead.

How this differs from running scene detection yourself

The obvious alternative is to call ffmpeg's scene detection filter directly and write the shot list yourself, then label shots with whatever model you already use. That gives you full control over the threshold and no dependency on an agent session. What it does not give you is the labelling layer, the keyframe extraction, the report, or the quality checklist, and you would be rebuilding the file contract that shots.json and track.json already define.

A second alternative is a general video understanding model that accepts a file and returns a description. That approach collapses measurement and interpretation back together, which is exactly what this repository separates. The README's framing, that ffmpeg measures cut points and durations while the model judges only the editorial fields, is a direct argument against that design.

The difference in practice is where errors land. With a pure model approach, a wrong cut point and a wrong framing label look the same in the output. Here, a wrong cut point shows up as a mismatch between track.json and the frames, which is checkable, while a wrong framing label is a judgement call you can argue with. For a shot breakdown that someone will edit against, that distinction matters more than raw capability.

Maintenance, licence and what an upgrade actually costs

The repository is not archived and the last push was on 2026-09-14, three days before this writing, so the working tree is current. There are no published releases, which means there is no version number to pin and no changelog to read before pulling. Upgrades arrive as commits to main, and because the install script symlinks the skills into ~/.claude/skills/ or ~/.codex/skills/, a git pull changes the installed skill immediately. That is convenient and it also means an update can change output formatting or labelling behaviour with no intermediate step. If you need stable reports, copy the skill directory instead of symlinking it, since the README confirms a copied skill is self-contained.

The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. Apache-2.0 also requires that you keep the licence and notice files when redistributing, and state significant changes. If you fork the skills and ship them inside a product, those obligations travel with the fork. None of this is legal advice; read LICENSE in the repository if the distinction matters to your organisation.

The cost side is small. Zero npm dependencies means no lockfile to audit and no transitive supply chain. The only recurring cost is session quota, since the README states the skills use the current session's allowance rather than a separate API key. The README also mentions a paid WeChat group for AI video discussion, which is a community channel and not part of the software.

Editorial conclusion

Adopt reelbench-skills if you already run Claude Code or Codex and want a repeatable shot breakdown without wiring up a video pipeline yourself: node 18 or newer plus ffmpeg and ffprobe are the whole dependency list, and the install script symlinks the skills so a git pull takes effect immediately. Skip it if you need a hosted service, a Python library, or automatic shot classification you can trust without review; the README is explicit that the model only judges the editorial fields while ffmpeg measures cuts and durations. Before relying on it, clone the repository, open demo-report/shots-report.html, and compare its 53 shots against the 202.9 second demo video yourself, then run the same command on a long unbroken take to see how the detector behaves when there is nothing to cut.

Frequently asked questions

Official sources

1. eternityspring/reelbench-skills on GitHub
2. Issues
3. License: Apache-2.0
4. README