# Reviewing Ffmpeg Skill Changes

Review a change to the ffmpeg-skill repository for the failures its own contract makes...

- Repository: https://github.com/kajisho5/ffmpeg-skill (4279 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add kajisho5/ffmpeg-skill --skill reviewing-ffmpeg-skill-changes -g -a claude-code -y`
Codex: `npx skills add kajisho5/ffmpeg-skill --skill reviewing-ffmpeg-skill-changes -g -a codex -y`
Cursor: `npx skills add kajisho5/ffmpeg-skill --skill reviewing-ffmpeg-skill-changes -g -a cursor -y`
Gemini CLI: `npx skills add kajisho5/ffmpeg-skill --skill reviewing-ffmpeg-skill-changes -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add kajisho5/ffmpeg-skill`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.

```bash
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*.

The rest: https://github.com/kajisho5/ffmpeg-skill/blob/HEAD/.claude/skills/code-review/SKILL.md