The interesting thing about kajisho5/ffmpeg-skill is not that it edits video. It is that the repo treats its own tool descriptions as a build artifact. Each of the 42 tools has an input_schema that has to track the CLI flag-for-flag, and that schema is never hand-written next to the code. It is derived at run time from the same argparse parser that already defines the command line, and continuous integration fails the build if the two drift apart. The author calls this SPEC, a Self-Producing Execution Contract.

That single design choice is the story for anyone building agent tooling, because it attacks the failure mode that quietly breaks every “agent knows how to use X” product: the description of a tool and the tool itself diverging until the model confidently calls a flag that no longer exists.

What the repo actually ships

The headline is a local video editor for coding agents. Install with npx ffmpeg-skill, and it drops a skill into ~/.claude/skills/ffmpeg-skill for Claude Code, with --cursor and --codex flags for the other two clients. If ffmpeg and python3 are on the PATH, it runs offline with no API keys, no account, and no Python dependencies beyond the standard library. The 42 tools cover cutting, joining, silence removal, fit-to-duration and aspect, captions with karaoke animation, overlays, HDR to SDR conversion, LUTs, audio dynamics, loudness, multicam, sync with drift correction, and platform-specific exports.

Every tool is also exposed over MCP through mcp/server.py, a stdio JSON-RPC transport. By default tools/list advertises a core 12 to keep client context small; setting FFMPEG_SKILL_MCP_FULL=1 lists all 42, and every tool is reachable by name through tools/call either way. Names, order and inputSchema in tools/list are translated from each tool’s argparse parser at startup, so a new flag appears in MCP with no edit to the mcp/ directory. A test copies the skill, adds, removes and edits a script, then reads tools/list again to prove the derivation holds.

The workflow the skill file teaches is probe, edit losslessly where possible, check, verify. Every job starts with probe.py measuring duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth and HDR format, rather than trusting the filename. Then check.py validates against the destination’s spec and look.py renders a contact sheet the agent inspects. The repo’s own example: an agent asked to cut two segments into a 60-second Reel runs cut.py --segments 0:45-1:20,5:00-5:25 --accurate, fit.py --aspect 9:16 --fit crop, export.py --preset reels, check.py --platform reels and look.py, then reports “final.mp4: 60.00 s, 1080×1920, 30 fps, AAC stereo.”

The take: verification is the product

Plenty of agent skills wrap a CLI. What is rare is the repo admitting, in a paper, that it does not fully meet its own standard. The design discipline is written up as a position paper, “What Is Verification-Driven Coding? A Discipline for Not Trusting Generation,” by S. Kajiyama (2026), DOI 10.5281/zenodo.23720216. The paper scores ffmpeg-skill itself as only partially conformant with the discipline it defines. That admission is worth more than a launch post claiming perfection. It tells you the author is measuring against something real.

The “Why” section names the exact behavior the skill is built to stop. An agent that “knows FFmpeg” still guesses: it assumes a frame rate, picks a codec the container cannot hold, re-encodes a file that only needed a stream copy, and reports “done” without opening the result. The fixes are concrete. Structured tools with typed arguments, nothing run through a shell, no filter graph accepted from the caller. A machine-readable contract --json that states for every tool what it takes, what it writes, which FFmpeg components it needs and how the result is verified. And a doctor command that distinguishes the overall ok from a single tool’s usable, because one missing filter (a Homebrew ffmpeg without subtitles, or a build without libvidstab) turns ok false even though most tools still run.

That distinction matters for anyone deploying agents in production. The most common agent failure is not a wrong answer. It is a confident “done” on a broken output. A tool that probes its own result and hands back a contact sheet the model has to look at is a small, honest step toward catching that.

Where the repo draws its own line

The most interesting part of the README is the section on the wider ecosystem. This repo is described as “the hands”: it cuts, measures and exports files and reports back in structured JSON. It does not decide what to cut, whether a deliverable is approvable, what makes a highlight interesting, or what a caption should say. The user’s cue text is burned as written, never rewritten to fit. Those are “a brain’s job, sitting in front of this engine, not inside it.”

That separation is a useful stance in a moment when a lot of agent tooling tries to be both the model and the tool. The dependency runs one way. Sibling repos like remotion-ffmpeg-skill, transcription-skill and qc-skill read this repo’s contract and JSON output, and this repo calls into none of them. It is a component, not a platform.

The most common agent failure is not a wrong answer. It is a confident “done” on a broken output.

What it does not solve

Two honest gaps. First, transcription is optional and separate. caption.py --transcribe and, since version 1.17, silence.py --transcribe need a local speech engine (Parakeet, faster-whisper or openai-whisper) installed by the user, and both refuse with install instructions rather than guessing when one is missing. The engines run on the machine and audio is never uploaded, but the model weights download on first run. So “no cloud” is true for the editing and only true for the speech after a one-time download.

Second, the demo footage. The gallery is built by python3 demos/build.py from synthetic FFmpeg test sources, except three demos (reframe_talk, filler_en, pauses_en) that use two AI-generated clips of people who do not exist. The author is transparent about it, which is the right call, but it means the before/after examples are not real-world footage. Whether the tools hold up on a messy phone recording is not something the repo demonstrates.

What this means for builders

The transferable idea is not video. It is that an agent tool’s description should be generated from the tool, checked in CI, and verified against the tool’s actual output. If you are shipping MCP servers or agent skills, the pattern here is worth copying: derive the schema, fail the build on drift, probe the result, and let the model look at what it made. The repo also sets a reasonable bar for honesty by publishing a paper that grades its own work as incomplete.

The next thing to watch is whether the broader agent-tooling ecosystem adopts derived contracts or keeps hand-writing schemas that rot. npx ffmpeg-skill contract --json is a working example of the former. How many others follow is the open question.