Forty-two tools turn FFmpeg into an agent-sized interface
ffmpeg-skill is useful because it narrows a huge command-line program into named operations an agent can call safely. Its 42 Python tools cover probing, cuts, joins, captions, loudness, silence removal, crops, overlays, color work, multicam sync, platform exports, and project rendering. Each tool uses typed arguments rather than accepting an arbitrary filter graph. The same parser generates the command-line and MCP input schema, so a new flag cannot appear on one surface and disappear from the other.
The workflow is equally opinionated. Probe the input, plan the change, prefer stream copies, render only when needed, inspect the result, and report what was verified. Every tool supports a dry run, explicit timeouts, structured JSON, and an overwrite flag. Inputs remain untouched. Those constraints address common agent failures: inventing media properties, picking an invalid codec-container pair, or declaring success without opening the output. The contract documentation makes those behaviors readable by both people and software.
Zero npm dependencies do not include FFmpeg
The one-line installer can create the wrong impression. npx ffmpeg-skill copies the skill for Claude Code, while --cursor, --codex, and --all target other agent directories. The npm package has 0 runtime dependencies and its tools use Python's standard library. The actual media engine is a system prerequisite. You need Python 3.9 or newer plus FFmpeg 5.0 or newer, including named encoders and filters such as libx264, AAC, subtitles, loudnorm, xfade, and tile.
That separation is sensible because FFmpeg packaging differs across Linux, macOS, and Windows. It also means a successful npm install says little about whether captions, HDR conversion, or a specific export will work. The doctor command reads the local encoders, filters, and bitstream filters, then reports usability per tool. A plain Homebrew build can pass the overall check while captioning remains unavailable because libass is missing. Run doctor --json before giving an agent footage.
What happened when we ran it
Our sandbox installed commit df5d273 in 6 seconds, added 0 npm packages, and occupied 35 MB on disk. The repository contained 317 files and roughly 37,871 lines of source in a 19.2 MB checkout. There was no build script or target, so the build step was skipped. Npm audit found 0 known vulnerabilities: 0 critical, 0 high, 0 moderate, and 0 low.
The tests failed after 6 seconds. The runner reported 71 tests, with 1 failure, 16 errors, and 5 skips. The supplied log tail identifies the failure in test_build_one_demo_and_stay_under_the_preview_budget: it raised AssertionError: ffmpeg not on PATH, calling that a broken CI install step. The tail does not include the exception text for the 16 errors, so assigning all of them to the missing binary would be guesswork. Our result proves the npm layer installs cleanly, while the full suite needs the documented system tool.
Twelve default MCP schemas keep the context smaller
The MCP server lists a core set of 12 tools by default, although all 42 remain callable by name. Setting FFMPEG_SKILL_MCP_FULL=1 exposes every schema. That is a practical choice for agents because tool descriptions consume context before any footage is touched. The server also publishes five workflow prompts for reels, podcasts, multicam edits, delivery checks, and HDR jobs. Those prompts compose existing calls rather than creating hidden editing behavior.
The contract is the strongest part of the project. It records requirements, output shapes, verification policy, whether a visual check is needed, and that inputs are not mutated. It does not make the agent visually intelligent. look.py creates a contact sheet, then the calling agent must inspect it. Automatic highlight ranking uses measured audio or scene duration, not story value. A non-visual caller must supply crop anchors because the default is a center crop. This is execution infrastructure, not an editor's taste.
Version 2.3.1 is active, but outside-user proof is unfinished
Release v2.3.1 shipped on September 25, 2026, the same date as the last repository push, and fixed content checks in rendered plans. GitHub showed 1,431 stars, 117 forks, and 1 open issue when checked. Five CI workflow files cover multiple operating systems and FFmpeg versions. That activity supports the project's 2.x stability promise more than the star count does.
The remaining issue is unusually candid. Issue 143 asks for real installs on non-maintainer Windows, Cursor, Codex, and macOS machines, plus reviews by three working editors. It cites a prior Codex install path that stayed wrong through 23 releases because nobody with Codex had tried it. That is a fair warning. ffmpeg-skill is thoughtfully engineered and worth adopting for controlled local automation, but test your exact agent, FFmpeg build, and footage before making it part of a delivery pipeline.