FFmpeg Skill Reviewer
Review FFmpeg skill changes for contract violations and documentation gaps.
Installation
- Make sure Claude is on your device and in your terminal.
Skills load from
~/.claude/skills/when Claude Code starts up β so you need it on your machine first. If you don't have it yet, install it once with the command below, then runclaudein any terminal to verify.One-time setupnpm i -g @anthropic-ai/claude-codeAlready have it? Skip ahead.
- Paste into Claude Code or into your terminal.
This copies the whole skill folder into
~/.claude/skills/reviewing-ffmpeg-skill-changes-kajisho5/β the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Works for every skill.What this command does
- Makes a new, empty temporary folder.
- Downloads the skill's folder,
.claude/skills/code-review, fromgithub.com/kajisho5/ffmpeg-skill(branchmain), the GitHub repository it's listed from. You get the version that is there now, not a copy we keep. - Copies that folder to
~/.claude/skills/reviewing-ffmpeg-skill-changes-kajisho5/. - Deletes the temporary folder.
Installing runs none of the skill's files; it only downloads and copies them. When you later use the skill, Claude follows its SKILL.md and may run scripts that come with it. Read them first.
Faster alternative (instruction-only skills)
Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates β they won't be downloaded and the skill will fail when it tries to load them.
Quick install (SKILL.md only)Sign up to copy - Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from
~/.claude/skills/). New skills are picked up on startup. - Just ask Claude.
Skills auto-activate when your request matches the skill's description β no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the βWhat this skill doesβ section above.
Prefer to read the source first? Open on GitHub.
When Claude uses it
Review a change to the ffmpeg-skill repository for the failures its own contract makes possible β a claim in a result document that is true at one layer and false at the layer a caller reads, a new flag that reaches the code but not the contract/docs/demo surfaces, a "bug" that docs/design-decisions.md already decided with a pinning test, a fix with no regression test, a new runtime dependency or a raw ffmpeg shell call that breaks the scope boundary, a SKILL.md line added without one trimmed, a review that re-derives findings from a summary instead of the tree at the reviewed commit. Use when asked to review a PR or diff in this repository, when authoring code here and needing a pre-commit check, or when triaging an external review or audit report about this codebase.
What this skill does
Reviewing ffmpeg-skill Changes
This repository has an unusual failure mode, and a review that misses it looks
thorough while catching nothing. The product is a JSON result document that an
agent reads instead of watching the video. A change can be correct at the FFmpeg
layer, correct at the Python layer, and still ship a lie at the layer that
matters: status: "completed" next to a non-zero exit, verified: true for
something the tool never measured, a cut described as lossless when the keyframe
snap moved it 1.24 s. The 0.9.1/0.10.0 "honesty fix" (cut.py's mode /
keyframe_snapped / duration_delta_seconds, check.py's reason, render.py's
check-stage exit code) exists because three such claims shipped and were caught
after the fact. Review the claim, not just the code.
The second failure mode is re-reporting decisions. Three review rounds on
2026-09-12 re-reported entries in docs/design-decisions.md, which is why that
file exists.
Establish the review base first
Read the tree at the commit under review, not a summary of it and not your own working copy if it has moved.
git fetch origin && git log --oneline -1 origin/main
git diff --stat origin/main...HEAD # what the branch actually changes
git show origin/main:docs/design-decisions.md | head -40
At least one earlier review reported committed media that is not in git and colour flags that were already validated β both came from reading a summary rather than the tree. Before reporting any finding, name the file and line you read it at, and confirm the symbol still exists there.
Check the claim at the layer the caller reads
For every writing tool touched, trace the success document it prints and ask whether each field is something the tool measured.
| field | the review question |
|---|---|
status | can this be completed while the exit code is non-zero? (die() must set failed) |
verified | is it the conjunction of steps the tool actually ran, or an assumption? |
reencodes_* | was a copy fallback taken and reported, or silently assumed not taken? |
dropped_non_av_streams | did the timeline move (track must be dropped, true) or stay (kept, false)? |
keyframe_snapped, duration_delta_seconds | for cut: is the measured divergence reported, not rounded away? |
mode | does it name the path actually taken (copy vs re-encode)? |
error.kind | input / ffmpeg / output / missing_tool / timeout / verification / interrupted β is it the one that happened? |
error.retryable | must stay false; a true here invites a blind retry loop |
--dry-run claims matter too: info() rewrites wrote X to [dry-run] would write X, and analysis_only tools (check, sync, multicam, scenes,
cropdetect, report, silence, loudness, stabilize) do run FFmpeg to
measure. overlay is one only for a multi-line --text on FFmpeg 8.0, 8.0.1
or 8.1.0 (it measures each line on a generated frame); otherwise its dry run
runs no ffmpeg. probe is not one of them (ffmpeg_execution: none). A change that makes a writing tool print a write claim under
dry-run is a defect.
See references/result-honesty.md for the code pointers and the exact test names
that pin each of these.
Refuse to report what the repo already decided
Grep docs/design-decisions.md before writing any "this looks wrong" sentence.
Each entry names the rationale and the test that pins it. If the change under
review is about one of them, the report must say which sentence there no longer
holds β otherwise it is a re-report and will be closed as one.
Also grep before claiming a gap, because several checks are centralised:
grep -rn "validate_color(" scripts/ # colour flags are validated at tool level, not per call site
grep -rn "apply_common()" scripts/ # --quality range check happens once, here
grep -rn "time_arg(" scripts/ # the single time parser; a tool parsing time itself is the bug
Score the change against the repository's rules
A change that is correct in isolation can still be unshippable here. Verify each applicable rule against the tree:
- Contract first.
python3 scripts/_contract.py --jsonis the source of truth for tool names, flags, dry-run semantics and error kinds.README.mdandSKILL.mdrestate it and are tested against it. A new flag that exists only in a script is half shipped; extend the generator, never hand-duplicate a schema. - Every surface, or it is not shipped. A
featupdatesREADME.md(tool table, contract table, gotchas),SKILL.md,references/scripts.md,docs/contract.mdandCHANGELOG.md. Seereferences/surfaces.md. SKILL.mdstays under 30,000 bytes β enforced bytest_skill_md_stays_under_the_30kb_budget, not a convention. Adding a line means trimming one, and the PR should say which.- A demo, or the feature is invisible. Every script under
scripts/must appear in some demo's command line (a test asserts it); afeatadds a before/after entry todemos/build.pyand regeneratesdocs/demos.mdwithpython3 demos/build.py --docs. Tools whose whole output is a table/JSON/HTML go inINSPECTIONinstead. - A regression test, or the fix is not done.
CONTRIBUTING.mdis explicit: a fix without a test that would have caught the original bug is not finished. - Stdlib-only, Python 3.10+. No new runtime dependency; every script must work
with nothing but
ffmpeg/ffprobeonPATH. - Scope boundary. No AI/LLM content judgement, no cloud or API keys, no raw
ffmpeg/ffprobeshell invocation outsidescripts/*.py, no mutation of input files, no creative decisions on the caller's behalf. - Within-major discipline. Contract-shape changes wait for the next major and
ship first as parallel keys (as
hdr_signaldid before 2.0). A PR that changes the meaning of an existing field in a minor or patch release is a finding.
Run the gate, then read it honestly
npm test # tests/run_parallel.py: test_all.py's nine modules + tests/test_contract.py
npm run release-check # packaging + installer + MCP + doctor + full suite
python3 scripts/_contract.py doctor # what this machine can actually run
CI is a three-OS matrix (Linux/macOS/Windows) across FFmpeg 6.1, 7.1 and
8.x/9.x. A change that passes locally on one FFmpeg major is not verified. Report
a red check as its own statement β never a parenthetical under a "done" claim β
and confirm green after the run finishes rather than predicting it. See
reproducing-ci-locally in this repo's .claude/skills/.
Two traps specific to reviewing here:
- Never quote the release bump's skip-CI marker in a PR body. A squash merge copies it into the merge commit and skips every workflow.
references/process-pitfalls.mdis a maintainer diary and is not in the npm package; the other reference files are. Packaging claims belong againstpackage.jsonfilesandbin/install.jsPAYLOAD.
Write the review
Order findings by what they cost: a false claim in a result document first, then a missing surface or test, then style. For each, give file and line at the reviewed commit, the concrete failure it causes, and the smallest fix. State plainly which checks you ran and what you did not verify β an unrun check reported as passing is the same defect as an overstated result document, one artifact over. Defer deep security audits to a dedicated security pass; this skill reviews quality, scope and claim-honesty.
Additional Resources
Reference Files
references/result-honesty.mdβ the JSON contract, the fields that carry claims, and the test that pins each one.references/surfaces.mdβ the full surface inventory a change must touch, and how to check for drift.references/review-checklist.mdβ the runnable pre-commit and pre-merge checklist with exact commands.references/reviewer-findings.mdβ the twenty questions an outside reviewer kept asking across 353 findings (#92 to #435). Read it before every push; add a question when a finding fits none of them.
Note for this repository (ffmpeg-skill)
This skill is repo-local and intentionally duplicates none of
writing-defect-reports, verifying-external-behavior or
reproducing-ci-locally (all in .claude/skills/); it points at them instead.
Its distinguishing subject is the review of a claim β the emit()/die()
document β which is where this codebase's shipped defects have actually come from.
Related skills
Generative Code Art
anthropics
Create algorithmic art with p5.js using randomness and interactive parameters.
Poster & Visual Design
anthropics
Create original posters and visual art in PNG and PDF formats.
Claude API Helper
anthropics
Build, debug, and optimize Claude API applications with caching and model migration support.
MCP Server Builder
anthropics
Build protocol servers that connect language models to external APIs and services.