What is ffmpeg-skill? Video editing with a coding agent: setup, 42 tools and example requests

FFmpeg is a program that can do anything with video and audio, but its commands are hard to memorize. A coding agent "knows" FFmpeg but often guesses: it assumes the frame rate, picks a codec the container can't carry, re-encodes a file that only needed cutting, and says "done" without opening the result. That is the problem the README describes. ffmpeg-skill gives the agent 42 ready-made tools that measure, have clear limits and check their own results: the agent first measures the file, then runs the right tool, and finally measures and checks the output.

Who it helps: content teams and agencies producing Reels, TikTok, Shorts or podcasts; anyone who wants to split an interview, training or meeting recording into short clips; people who already use Claude Code, Cursor or Codex and want their video work done in the same place. It is not a video editing program (timeline, drag and drop): you write a request and the agent runs the tools.

The skill does not decide what to cut, which scene is interesting or what the captions say; those are decisions for the agent or for you. The README draws this line explicitly: the skill is the "hands", the "brain" that decides is elsewhere.

• Protects your source: no tool overwrites its input; the output is a new file. An existing output file is only replaced with --overwrite.
• No free-form shell commands: every operation is a Python script with typed options; it does not accept FFmpeg filter strings or raw arguments from outside.
• Tells you what your machine can do: npx ffmpeg-skill doctor lists which components (libx264, libass, loudnorm…) your installed FFmpeg has and which tools can't be used.
• Fixed report format: when the job is done it says Done:, otherwise Failed:; anything left incomplete goes in the note.

Every tool shares common options: --dry-run (show the plan), --json (structured result with the output's measurements), --fast (preview quality), --progress, --timeout (stops a stuck FFmpeg, default 1,800 s) and --overwrite. Audio files (WAV, FLAC, MP3, M4A, OGG, Opus) are handled with the same commands; visual tools reject an audio file with "no video stream" instead of inventing an image.

First, FFmpeg must be installed on your computer (the skill does not bring FFmpeg with it); then you install the skill into your agent. Setup is done once; the copy does not update itself.

• FFmpeg: 5.0 or later; 6.1+ recommended (5.x has been considered outdated since 2.14.0, and version 3.0 will require 6.1).
• Python: 3.9 or later, standard library only (installs no extra packages); 3.10+ recommended.
• Node: 16+ only for the npx install.
• What runs during setup: the npx package carries no extra dependencies and no install script (postinstall); the installer copies the SKILL.md, scripts/, templates/, references/, docs/ and mcp/ folders into the target folder.

After setup you talk to your agent as usual; the skill kicks in on its own when you mention a video or audio file. The examples below come from the README; the outputs are described as far as the README describes them.

What you get: according to the README, the agent measures (probe.py), cuts the two ranges (cut.py --segments 0:45-3:10,5:00-6:30), fits the result to 60 seconds and 9:16 by cropping (fit.py --duration 60 --aspect 9:16 --fit crop), exports with the Reels preset (export.py --preset reels), checks it against the Reels rules (check.py --platform reels) and produces a contact sheet (look.py). The report ends with a line like "final.mp4: 59.98 s, 1080×1920, 30 fps, AAC stereo", along with the image it reviewed.

What you get: the TikTok template crops the file to 9:16, places the captions word by word above TikTok's description bar and clear of the like column, brings the audio to −14 LUFS, exports with the TikTok preset and checks the file it wrote with check.py --platform tiktok. --template all produces every platform from the same edit and lists what was produced in a _pack.md table; --dry-run shows the plan without writing anything. Templates: tiktok, reels, shorts, youtube, x, linkedin, facebook, podcast.

What you get: based on the audio tools in the README, the agent removes the silences (silence.py), brings the audio to the podcast target (loudness.py … -I -16 --tp -1.5 -o … .m4a) and reports LUFS, true peak, chapter markers and channel count with check.py --platform podcast. Because an audio file has no visual step, the report says "Look: not needed".

Before a long job, say "show me the plan first, don't run it": every tool lists only the commands it would run with --dry-run. For edits with three or more steps, the README recommends a single project.json with render.py (re-encoding at every step costs quality).

!The skill does not bring FFmpeg with it; a vulnerability in your installed FFmpeg stays in your version until you update it. doctor warns about known high-severity vulnerabilities; keep FFmpeg up to date.

Yes. It is MIT-licensed and free; it requires no account, subscription or API key. It can be used for commercial work too (MIT asks you to keep the license notice). The developer accepts optional support through GitHub Sponsors. The only money goes to the agent you use (a Claude Code, Cursor or Codex subscription): because the skill does the processing on your computer, it adds no extra cost.

This license summary is not legal advice. Usage rights for the videos, music and fonts you process apply separately.

What it can't do (README FAQ): no face or object tracking; a moving logo or burned-in captions that change position are not removed (only a fixed, known rectangle is blurred); GPU encoding only with VideoToolbox on Apple Silicon.

If you installed it as a plugin, remove it from the Installed tab of the /plugin panel in Claude Code. FFmpeg and Python are separate programs and are not removed along with the skill.