Free guide
ffmpeg-skill: Give Claude Code a Video Editor That Measures Its Work
A free, open-source skill that gives your coding agent 42 small FFmpeg tools and a rule to measure every file before and after it edits. What it does, how it works, how to set it up, and the fine print.
The short version
- Its makers say an agent that "knows FFmpeg" still guesses: it assumes a frame rate, picks a codec the container can't hold, and reports done without opening the result. This skill makes it measure instead.
- Every job starts by probing the real file, then 42 typed tools edit and check it (cut, join, silence removal, captions, reframing, loudness, export, platform checks). No tool overwrites your original.
- It's trending on GitHub this week (+3,598 stars, 9,400+ total on Nov 22). It runs locally with no cloud and no API keys. Version 4.6.2 shipped Nov 22.
How it actually works
Scissors vs a tailor
Your agent can already write an FFmpeg command, the same way anyone can pick up scissors. A tailor measures first. ffmpeg-skill hands your agent the tape measure: a fixed workflow of probe, edit, check and verify, written into the skill file it reads and enforced by the tools.
Measure first, then cut
Every job starts with probe.py, which measures duration, frame rate (including variable frame rate), resolution, colour and every audio stream. The agent decides from those numbers, not from the file name. Then a typed tool does the job, with no shell strings and no raw filter graphs, and it copies streams losslessly when nothing needs re-encoding.
Check against the platform
After the edit, the output is probed again and graded against the destination's limits with check.py (Reels, TikTok, Shorts, YouTube, X, LinkedIn, Facebook, podcast), using the tool's own delivery table, and look.py renders a contact sheet so the agent can look at what it made. We ran its tools by hand on one of our own videos: the 60-second Reel passed 13 Reels checks with zero failures and one warning (no subtitle track).
It tells you what it couldn't check
Every writing tool lists what it did not measure, like whether the framing or the picture looks right. In our run, the crop step warned that motion or detail sat outside the part of the frame it kept, and suggested a pad or blurred fill instead. It was right: our contact sheet showed text cut off at the edges. Nothing in the repo detects faces, subjects or text, so the final look is still your call (or your agent's eyes on the contact sheet).
How to set it up
1.Check you have Node and Python
The installer needs Node 16 or newer, and the tools need Python 3.10 or newer (standard library only). FFmpeg 6.1 or newer is required; the setup command installs it if it's missing.
node --version python3 --version2.Install it with one command
setup installs the skill for every agent it finds on your machine (Claude Code, Cursor, Codex), installs FFmpeg when it doesn't run (it prints the package-manager command before running it), and ends with a doctor check.
npx ffmpeg-skill setup3.Or install it for one agent, or as a plugin
On a Mac, the README recommends Homebrew's ffmpeg-full, because the plain ffmpeg formula lacks the subtitles, drawtext and zscale filters.
# Claude Code only (~/.claude/skills/ffmpeg-skill) npx ffmpeg-skill # Cursor / Codex / all three npx ffmpeg-skill --cursor npx ffmpeg-skill --codex npx ffmpeg-skill --all # As a Claude Code plugin (Claude Code 2.1.275 or later) /plugin install ffmpeg-skill --marketplace kajisho5/ffmpeg-skill # FFmpeg on macOS brew install ffmpeg-full4.Check the machine
doctor lists which FFmpeg parts each tool needs and whether your build has them. Read its tools field for the per-tool answer: one missing filter turns the overall ok to false even when most tools still work.
npx ffmpeg-skill doctor5.Give it its first job
This is the README's example request. Swap in your own file and times. The agent should probe, cut, crop to 9:16, export, check and show you a contact sheet.
Take interview.mp4, keep 0:45-1:20 and 5:00-5:25, and make it a 60-second Reel.
The fine print
- Free and open source under the MIT license. Your agent and its model are billed as usual.
- Local first: the tools send no telemetry and make no network calls, and read no API key. The one exception is optional speech-to-text for captions: an engine you install yourself (like faster-whisper) may download its model the first time.
- It measures files, not taste. Each tool lists what it couldn't verify (picture content, subject framing, caption legibility), and the default vertical crop is a plain centre crop: nothing detects faces or subjects. Look at the contact sheet before you post.
- 12 core tools are marked stable in 4.x; the other 30 are beta and may rename a flag after one release of notice. Releases are frequent and nothing updates by itself: re-run npx ffmpeg-skill@latest setup to update.
- The demo clips on the repo's site are mostly AI-generated with Google Veo (the people and places don't exist), plus three phone clips.
FAQ
Is ffmpeg-skill free?
Yes. It's open source under the MIT license and runs on your own machine with no cloud and no API keys. You still pay for whatever agent or model you use with it.
Does ffmpeg-skill work with Claude Code?
Yes. npx ffmpeg-skill installs it to ~/.claude/skills/ffmpeg-skill, or install the plugin with /plugin install ffmpeg-skill --marketplace kajisho5/ffmpeg-skill (Claude Code 2.1.275 or later). It also works with Cursor, Codex, Gemini CLI and any MCP client.
Can it turn a horizontal video into a vertical Reel or TikTok?
Yes. fit.py --aspect 9:16 crops, pads or blur-fills to vertical, and render.py --template tiktok (or reels, shorts) does the whole delivery, keeping captions clear of the app's buttons. The crop is centred unless your agent picks an anchor after looking at the contact sheet.
Does it upload my videos anywhere?
No. Its privacy page says the tools send nothing and make no network calls. Your media is read from and written to the paths you give.
What is the difference between ffmpeg-skill and Remotion?
ffmpeg-skill edits footage you already have (cutting, reframing, loudness, captions, checks) with FFmpeg. Remotion renders new video from code. The same author has a separate remotion-ffmpeg-skill that combines them.
Sources
- ffmpeg-skill on GitHub
- ffmpeg-skill website and demos
- Every before/after demo with its command
- ffmpeg-skill on npm
- Releases and changelog
Facts checked 2026-11-22 against the ffmpeg-skill README, LICENSE and PRIVACY.md at v4.6.2, the release list, npm (4.6.2), the GitHub API (9,409 stars) and GitHub Trending weekly (+3,598), plus our own sandboxed run of its tools on one of our videos.
Want help building with tools like this?
Join the Shipping Skool community free. Paid members get live bootcamp calls every week and weekly-updated courses.
Join Shipping SkoolMore free guides
Grok Bot + QuickBooks: Ask Who Owes You, Approve the Invoices
Grok Bot now connects to Intuit QuickBooks in the US. Ask about cash flow or who still owes you, let it draft the invoices for you to approve, and set one rule so sends stop for your OK.
How Lean Checked the Claude-Assisted Riemann Hypothesis Proof
An Anthropic mathematician says he proved the Riemann Hypothesis working with Claude, and wrote the whole proof in Lean. Here's how a computer checks a proof like that, and how to try Lean yourself today.
Chrome DevTools MCP: Let Your Coding Agent See the Page It Builds
Google's free, open-source way to give your coding agent a real Chrome window and the DevTools you already use. What it does, how it works, how to set it up, and the fine print.