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.

By Beau Johnson·

Quick answer

ffmpeg-skill is a free, open-source (MIT) Agent Skill and MCP server that lets Claude Code, Codex, Cursor or any MCP client edit video with FFmpeg on your own machine. Install it with npx ffmpeg-skill setup, then ask your agent to keep two parts of a video and make a 60-second Reel: it measures the file, cuts, crops to vertical, exports and checks the result against the platform's specs.

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. 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 --version
  2. 2.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 setup
  3. 3.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-full
  4. 4.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 doctor
  5. 5.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

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 Skool

More free guides