ffmpeg-skill

Give your coding agent a video editor.

Local FFmpeg · No cloud · No API keys · Python standard library
Claude Code · Cursor · Codex · MCP

npx ffmpeg-skill

ffmpeg-skill is an Agent Skill for Claude Code, Cursor, Codex and any agent that reads SKILL.md. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships 42 tools that do the actual work with ffmpeg / ffprobe: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.

If ffmpeg and python3 are on your PATH, it works: offline, on footage you would rather not upload.

SPEC (Self-Producing Execution Contract), coined by this project's author kajisho5: each tool's input_schema — the part of its contract and MCP tool definition that has to track the CLI flag-for-flag — is never hand-authored beside the code. It's derived, at run time, from the same argparse parser that already defines the CLI, and CI fails the build if any of it drifts. → full explanation

Standalone, and in an ecosystem

Standalone, this is a local FFmpeg engine: probe → edit → verify, npx ffmpeg-skill and nothing else. No API key, no account, no other repo required. Everything above and below this section describes that standalone tool, and none of it changes if you never read the rest of this one.

In kajisho5's wider video-production ecosystem, this repo is 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, or what makes a highlight interesting — those are a brain's job, sitting in front of this engine, not inside it.

Other repos in the ecosystem — media-analysis-skill, transcription-skill, subtitle-skill, thumbnail-skill, color-grading-skill, motion-graphics-skill, qc-skill — read this repo's contract --json, its tools' --json output and doctor, the same way any agent framework would; this repo does not call into any of them. The dependency runs one way.

Contents Standalone, and in an ecosystem · Why · Quick start · How it works · Design principles · Tools · Audio · Built for agents · FFmpeg compatibility · Tested on real footage · Install · Requirements · Development · Docs

Why

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. ffmpeg-skill exists to take the guessing out:

• Real files first. Every job starts with probe.py; the agent decides from the measured duration, fps, resolution, colour and audio layout, not from the file name.
• Structured tools, not shell strings. Each operation is a script with typed arguments. Nothing runs through a shell; no filter graph is accepted from the caller.
• A contract the agent can read. contract --json states, for every tool, what it takes, what it writes, which FFmpeg components it needs and how the result is verified. The MCP surface is derived from it.
• Verification after execution. The result is probed, checked against the destination's spec and, when the picture changed, looked at as a contact sheet.
• Local first. No cloud, no API keys, no Python dependencies. Optional local transcription is used when a whisper is installed, never required.

Quick start

# 1. install the skill for Claude Code (Cursor: --cursor, Codex: --codex, all three: --all)
npx ffmpeg-skill

# 2. check the machine: ffmpeg, ffprobe and every FFmpeg component the tools need
npx ffmpeg-skill doctor

# 3. (for agent frameworks) read the machine-readable contract
npx ffmpeg-skill contract --json | head -40

Already installed? re-run npx ffmpeg-skill to refresh ~/.claude/skills/ffmpeg-skill. Copies are not updated automatically.

doctor's overall ok and a single tool's usable: no are different signals: ok means nothing required by every tool is missing, but a plain Homebrew ffmpeg on macOS can still be ok while caption.py specifically can't run (no subtitles filter) — check doctor --json's tools field for the per-tool answer, not just ok.

Then talk to your agent:

"Take interview.mp4, keep 0:45–3:10 and 5:00–6:30, and make it exactly 60 seconds for Reels."

The agent runs probe.py, cut.py --segments 0:45-3:10,5:00-6:30, fit.py --duration 60 --aspect 9:16 --fit crop, export.py --preset reels, check.py --platform reels and look.py, then reports "final.mp4: 59.98 s, 1080×1920, 30 fps, AAC stereo" with the contact sheet it inspected.

The tools also work on their own, from any shell:

S=~/.claude/skills/ffmpeg-skill/scripts
python3 $S/probe.py input.mp4 --compact
python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run    # print the plan, run nothing
python3 $S/export.py input.mp4 --preset reels --json                 # structured result with a probe of the output

On Windows in Git Bash, python3 is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes python (or the py launcher) instead — replace python3 with python above if you see a "command not found". bin/install.js and doctor/contract already handle this for you; only the raw script examples above need it spelled out manually.

More requests and the commands behind them: examples/README.md. To see everything run end-to-end on generated footage: npm run demo.

How it works

flowchart TD
    U[User request] --> A[AI agent<br/>Claude Code · Cursor · Codex]
    A -->|reads| S[SKILL.md<br/>workflow, request → tool map, report format]
    A -->|runs| T[Structured tool<br/>scripts/&lt;name&gt;.py, typed argparse flags]
    T --> C[Contract<br/>input schema · role · capabilities · verification policy]
    C --> D[Capability detection<br/>doctor: available / missing / unknown]
    D --> F[FFmpeg execution<br/>no shell, stream copy when possible]
    F --> V[Verification<br/>probe · check · look.py contact sheet]
    V --> R[Structured result<br/>--json: status, output, commands, probe]
    R --> A

Over MCP the same tools are reached through a transport that holds no tool table of its own:

flowchart LR
    M[MCP client<br/>Claude Desktop · Cursor · any client] --> P[mcp/server.py<br/>stdio JSON-RPC]
    P -->|tools/list| C[Contract-derived ToolSpecs<br/>names · order · inputSchema]
    P -->|tools/call| T[scripts/&lt;name&gt;.py]
    C -.derived from.-> K[scripts/_contract.py]
    T -.described by.-> K

Names, order and inputSchema in tools/list are translated from each tool's argparse parser at start-up, so a new flag or a new script appears in MCP with no edit to mcp/. A test copies the skill, adds, removes and edits a script, and reads tools/list again to prove it.

Design principles

These are the rules the skill file gives the agent and the code enforces. Together they are what separates this from a list of FFmpeg one-liners.

1. Probe first. No tool decides from the file name. probe.py measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.
2. Lossless when possible. cut.py, join.py and loudness.py stream-copy what they do not need to touch. Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.
3. Plan before render. Every tool takes --dry-run (print the ffmpeg command lines, write nothing), --json (structured result with a probe of the output), --fast (preview quality), --progress (percent and ETA), --timeout (a hung ffmpeg is killed and reported, never waited on forever; Ctrl-C or SIGTERM likewise stops the running ffmpeg, removes its partial output and reports kind: interrupted) and --overwrite (explicit consent before an existing output is replaced). A test runs every tool under --dry-run behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
4. Machine-readable contract. contract --json describes all 42 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, mutates_input: false. provides lists all 42 by a cross-repository Capability id (ffmpeg-skill.cut, ffmpeg-skill.loudness, ...) for kajisho5/AI-video-production-OS's CapabilityContract.provides — see docs/contract.md.
5. Contract-derived MCP. mcp/server.py builds its tools/list from the contract. Tool names, order and inputSchema cannot drift from the scripts; a test keeps the two byte-identical.
6. Capability detection. doctor reads ffmpeg -encoders / -filters / -bsfs and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.
7. Unknown is not missing. When a listing cannot be read (a layout the parser does not know, ffmpeg exiting non-zero) the affected capabilities are unknown: never missing, never silently available. An installed filter is not reported absent; a failed detection is not a pass.
8. Verify the result. The output is probed, and when the picture changed (captions, overlays, crops, colour, transitions) the agent runs look.py and inspects the PNG. The report is not finished until its Look: line names that image; audio-only jobs say Look: not needed. "Inspects" means the calling agent's own vision, not a feature of this skill: look.py only renders a PNG; nothing in this repository detects faces, products, subjects, or "the interesting part" of a frame or a scene. When a crop or reframe needs to keep a specific part of the frame (fit.py --fit crop --crop-x/-y, see Tools), it is the multimodal agent looking at that PNG and choosing the anchor — a non-visual caller (a script, a CLI user without eyes on the sheet) has to supply that decision itself, and the default is a plain centre crop. Likewise scenes.py --highlights ranks candidate scenes by a measured proxy (--rank-by audio or --rank-by duration), never by content; it is the agent that turns a look at the sheet into a judgement.
9. Keep originals. No tool overwrites its input. Outputs are new files named <input>_<operation>.<ext> unless told otherwise, and a test hashes every input after the run.

Tools

42 public tools, all Python 3.9 standard library, all with --help, --dry-run, --json, non-zero exit and a reason on stderr on failure.

Analysis and inspection

Editing

Audio

Picture

Delivery

Orchestration

Not tools, but part of the surface: mcp/server.py (the MCP transport) and scripts/_contract.py (contract --json, doctor). Per-flag reference for every tool: references/scripts.md.

Audio is a first-class input

WAV, FLAC, MP3, M4A/AAC, OGG and Opus go through probe, cut, join, silence, loudness, audio, sync and check --platform podcast with the same commands as video. The output extension picks the codec: -o out.wav writes PCM, -o out.flac FLAC, -o out.mp3 MP3, -o out.m4a AAC.

• Extraction. An audio extension on a video input drops the picture: audio.py talk.mp4 -o talk.wav, or --voice -o talk.m4a to clean it on the way. --audio-stream N picks a track; probe lists them under audio_streams.
• Join. join.py intro.wav episode.m4a outro.wav -o full.flac resamples every clip to one rate and channel layout and crossfades them (--transition none for a butt join). Audio and video inputs cannot be mixed in one join.
• Sample-accurate trims. cut.py talk.wav --start 1.2345 --end 2.3456 --accurate trims at the sample; the JSON reports precision (packet for a stream copy, sample for PCM / FLAC, codec_frame when a lossy encoder frames the audio again, frame for video) and the measured duration_error_ms. A .wav never receives compressed packets.
• Typed dynamics. audio.py --compress --comp-threshold -20 --comp-ratio 4, --limit --limit-ceiling -1, --gate --gate-threshold -45. Each flag is one documented option of FFmpeg's acompressor, alimiter or agate, range-checked before ffmpeg runs; no filter string is accepted from the caller.
• Loudness. loudness.py talk.wav -I -16 --tp -1.5 -o talk.m4a for podcast levels; check.py talk.m4a --platform podcast measures LUFS and true peak.

Picture tools (fit, caption, overlay, graphics, color, export, scenes, look) refuse an audio file with "input has no video stream" instead of inventing a picture.

Built for agents

What is SPEC?

This project's author, kajisho5, coined SPEC (Self-Producing Execution Contract) for the pattern this skill's tool layer is built on: each tool's input_schema — the part of its contract that has to track the CLI exactly, flag for flag — is never hand-authored side by side with the code. It is derived, at run time, from the one thing that actually has to be correct for the CLI to work at all: the script's own argparse parser.

Concretely, scripts/_contract.py's _capture_parser() imports every tool script and intercepts its parse_args() call to get the live, fully-built parser object — flags, types, choices, defaults, required/positional, mutually exclusive groups, all of it. input_schema is built straight from that object. (The rest of a ToolSpec — role, capabilities, inputs, outputs, output_schema — comes from a hand-authored table, TOOL_META, since those facts aren't things a parser can express; only input_schema is parser-derived.)

• The contract's input_schema for every tool is generated from the live parser directly.
• The MCP server (mcp/server.py) carries no schema of its own; tools/list is translated straight from the contract, input_schema included.
• The docs (docs/contract.md's field reference, this README's tool table) describe the same shape. tests/test_contract.py runs on every CI run and fails the build if any of them drift out of sync with what the code actually does — it catches drift, it doesn't fix it for you.

The result: add a flag to a script's argparse block, and input_schema and the MCP tool definition follow with no second edit; if a docs page or a TOOL_META entry falls behind, CI catches it rather than letting it drift silently. There is no separate input_schema file to forget to update, and no version of "what CLI flags does this tool accept" that can quietly go stale.

Machine-readable contract

npx ffmpeg-skill contract --json            # or: python3 scripts/_contract.py --json
npx ffmpeg-skill contract --json --static   # without environment detection

The contract is generated from the code that runs, not maintained beside it. For each of the 42 tools (ffmpeg-skill/<name>) it states:

contract_version (1.0) is separate from the skill version, so a consumer can pin the shape and read the version for provenance. The document also states the invocation mapping (structured arguments → argv), the JSON shapes for success and failure ({"status": "failed", "error": {"kind": "input | ffmpeg | output | missing_tool | timeout | verification | interrupted", "message": …}}), and that no tool runs a shell or executes anything other than the named script, ffmpeg and ffprobe. Field-by-field reference: docs/contract.md.

MCP

{"mcpServers": {"ffmpeg-skill": {"command": "python3", "args": ["/Users/you/.claude/skills/ffmpeg-skill/mcp/server.py"]}}}

On Windows, python3 is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes python (or the py launcher) instead — if your MCP client reports the server failed to start, change "command" above to "python" (or the full path from where python).

mcp/server.py is a stdio JSON-RPC transport with no tool table of its own. tools/list is derived from the contract at start-up: the same 42 names, the same order, and inputSchema translated from each tool's input_schema. tools/call maps structured arguments to argv and runs the named script; a raw argv form is accepted for compatibility and marked non-canonical. python3 mcp/server.py --list prints the tools; --call probe '{"inputs": ["a.mp4"]}' runs one from the shell.

Capability detection

npx ffmpeg-skill doctor          # human-readable
npx ffmpeg-skill doctor --json   # available / missing / missing_optional / unknown / detection / errors / tools / gpu_encoders

doctor reads ffmpeg -encoders, -filters and -bsfs and resolves every capability the contract declares against this machine's build. Three states per capability: available, missing, unknown. Exit 0 when everything required is available, 1 when something required is missing, 2 when nothing is proven missing but a required capability is unknown. With detection on (the default), contract --json carries the same lists under capabilities. doctor --json's tools field folds that down to one answer per tool — {"caption": {"usable": "no", "missing": ["filter:subtitles"], "fix": "..."}, ...} — so "is doctor overall ok" and "can I run caption.py on this machine" are answered separately: a plain Homebrew ffmpeg is ok for tools that don't need subtitles/drawtext/zscale, while caption's own usable is "no".

doctor --json's gpu_encoders reports which GPU-backed encoders (nvenc, videotoolbox, qsv, vaapi, amf) this ffmpeg build was compiled with — read from -encoders alone, so it proves the capability shipped, not that the GPU/driver on this machine will actually accept a job (that needs a real encode, which doctor's introspection never runs). No tool here uses one yet — every tool still assumes CPU x264/x265 — so this is purely informational and never affects ok or any tool's usable. GPU-accelerated encoding stays deliberately off the roadmap until there's a real-hardware-verified design for it (build-presence alone is not proof a job will succeed) — not a promised feature, just an honest "not yet, and not without proof it actually works."

Gotchas and best practices

The short list for humans. The agent-facing version, with the reasoning, is the "Things that look right but are wrong" and "Gotchas" sections of SKILL.md.

• Variable frame rate (phone and screen recordings). probe.py flags it; every re-encoding tool conforms to a constant rate automatically, and cut.py switches to frame-accurate mode on its own because copy-cuts on VFR land on the wrong frame. Choose the rate yourself with fit.py input.mp4 --fps 30 when the measured average is odd.
• Lossless cuts snap to keyframes. A stream-copy cut can start up to one GOP earlier than asked. cut.py re-encodes when the snap exceeds 0.5 s (--tolerance changes the limit). For a strictly lossless file pass --tolerance -1, and expect the cut to land on the nearest earlier keyframe; the JSON result lists them under nearest_keyframes.
• HDR stays HDR. When the probe reports HDR (HDR10, HLG, Dolby Vision, BT.2020), the tools keep it rather than flatten it. Convert deliberately with color.py --to-sdr before H.264 deliverables or LUT work. export.py platform presets are SDR and warn on HDR input.
• Loudness targets. −14 LUFS / −1 dBTP for YouTube and social platforms (the loudness.py default), -I -16 --tp -1.5 for podcasts, -I -23 for broadcast. A clip measured at −40 LUFS or below is room tone, not content; raising it raises the noise. Check true peak as well as LUFS: check.py file --platform podcast measures both.
• Frame changes first, text second. Captions and overlays burned before a crop or resize end up off-frame. Reframe, then caption.
• Cropping 16:9 to 9:16 discards 70 % of the width. fit.py --fit crop centres by default; pass --crop-x/--crop-y toward the subject, or pad with --fit pad --pad-fill blur. Look at the contact sheet before deciding.
• Non-Latin captions need a font with the glyphs. Without one you get boxes, not an error. Name it (caption.py --font "Noto Sans CJK JP") or point at the file (overlay.py --font-file /path/to/NotoSansCJK-Regular.ttc).
• Silence detection finds nothing? The default threshold is −35 dBFS. The tool prints a hint with the track's measured level; raise the threshold (silence.py --threshold -25) or shorten --min-silence.
• Sync results carry a confidence. Below 0.3, or an offset near the edge of the analysis window, is probably wrong: enlarge --analyze-seconds or find a clap. Recordings over ten minutes from separate devices need sync.py --fix-drift.
• Long chains belong in a plan. Three hand-chained re-encodes lose quality and are hard to change; render.py runs the whole edit from one JSON file, and --dry-run shows every ffmpeg command before anything is written.

FFmpeg compatibility

The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:

FFmpeg 8 shortened the flag column of ffmpeg -filters. A parser anchored on the old width matches nothing on FFmpeg 8 and, if "nothing matched" is read as "nothing installed", reports every filter missing; that is what 0.9.0 did on macOS and Windows. Since 0.9.1 rows are recognised by their io-spec token (A->A, AA->A, |->V, N->N), so the flag width, the legend and the separator do not matter, and a listing that still cannot be read yields unknown rather than missing. The captured listings live in tests/fixtures/ with their provenance; CI uploads each runner's listing and doctor --json as an artifact so a new layout is visible before it bites.

Tested on real footage

python3 tests/corpus.py --fetch --verify     # ~1.4 GB download, then verify (slow on 4K)
python3 tests/bench_sync.py --cases 100
python3 tests/bench_silence.py
python3 tests/bench_scenes.py

Benchmarks live in tests/bench_*.py, agent evals in evals/, results by iteration in evals/results/.

Install

npx ffmpeg-skill              # Claude Code   → ~/.claude/skills/ffmpeg-skill
npx ffmpeg-skill --cursor     # Cursor        → ~/.cursor/skills/ffmpeg-skill
npx ffmpeg-skill --codex      # Codex         → ~/.agents/skills/ffmpeg-skill (Cursor reads this location too)
npx ffmpeg-skill --all        # all three
npx ffmpeg-skill --project    # this project  → ./.claude/skills/ffmpeg-skill
npx ffmpeg-skill --dir ./my-skills
npx ffmpeg-skill --uninstall  # remove from the selected targets (--codex also clears the older ~/.codex/skills location)

As a Claude Code plugin (no Node needed, updates with claude plugin update):

claude plugin install kajisho5/ffmpeg-skill

The plugin namespaces the skill as ffmpeg-skill:ffmpeg-skill; the manifest is .claude-plugin/plugin.json and its version follows every release automatically.

Without Node: clone this repository and copy SKILL.md, scripts/, references/ and mcp/ into your agent's skills directory.

After installing:

npx ffmpeg-skill doctor           # every required FFmpeg component present?
npx ffmpeg-skill contract --json  # what the agent framework will see

FFmpeg itself:

Requirements

• FFmpeg 5.0+. Always required: libx264, aac, and the drawtext, subtitles (libass), loudnorm, xfade, acrossfade, scdet, silencedetect and tile filters. Needed only by the flags that use them: libx265, prores_ks, libzimg / zscale, libmp3lame, libopus, libvorbis, the ass filter. doctor tells you which are present. The apt and gyan.dev builds carry all of them; some Homebrew bottles lack libass / libfreetype / libzimg, which doctor reports as missing.
• Python 3.9+, standard library only
• Node 16+ only for the npx installer

doctor's own introspection calls (ffmpeg -filters/-encoders/-bsfs/-version) time out after 10s and report failed rather than hanging forever — those are meant to be fast. Every tool's actual media-processing ffmpeg invocation (cut, fit, caption, ...) runs under --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT, 0 = none): past the limit the process is killed, its partial output removed, and the failure reported as kind: timeout (exit 124) — a legitimately long --accurate re-encode should raise the limit rather than run unbounded. -nostdin is always passed, so a hung ffmpeg process waiting on stdin cannot happen.

Stability

1.x keeps every tool name, CLI argument, JSON output key and exit code working: nothing is removed or renamed, and nothing optional becomes required, until 2.0. The full list of what is promised and what is not, and the three-step deprecation policy, is in docs/contract.md. It is enforced by a test that pins every tool's argument names against a snapshot, so a breaking change fails CI instead of slipping into a patch.

Development

npm test                      # tests/test_all.py (end-to-end incl. VFR, rotated, 5.1, HDR10, drifting sources) + tests/test_contract.py
npm run release-check         # pack, install, contract from the installed copy, MCP == contract, doctor, tests, contract evals
npm run demo                  # generate footage, run every tool, rebuild assets/demo.gif
python3 evals/run.py --list   # agent eval prompts (see evals/)
node bin/install.js --dir /tmp/skills   # try the installer without touching ~/.claude

CI (.github/workflows/ci.yml) runs on every pull request and on pushes to main, on Ubuntu (FFmpeg 6.1, Python 3.9 and 3.13), macOS (Homebrew FFmpeg 8.x) and Windows (gyan.dev FFmpeg 9.x), plus two Linux jobs on FFmpeg 5.1.1 (static build) and 7.1 (Debian trixie container), and uploads each runner's FFmpeg listings as an artifact.

tests/test_contract.py runs on all three OSes, but a handful of its tests build a fake ffmpeg as a #!/bin/sh script on a PATH shim to force specific FFmpeg 6/7/8/9 fixture layouts through doctor's parser — that technique isn't portable to Windows, so test_dry_run_never_runs_ffmpeg_and_writes_nothing and the whole DoctorDetectionTests class (fixture-driven layout parsing) are individually skipIf'd there and show as skipped, not silently absent, in the Windows job's log. Everything else — contract schema, reencodes_*, doctor.tools, MCP derivation, and every tool exercised through the contract, including cut.py's provenance fields — runs against the real Windows ffmpeg on every PR. See references/ci-platform-pitfalls.md for this and other per-OS behaviour differences already diagnosed, before spending a CI cycle re-diagnosing a platform-only failure.

Releasing is fully automated end to end, including the version number itself — a PR doesn't need to touch package.json, docs/contract.md, or CHANGELOG.md at all. Once a PR merges to main, .github/workflows/release.yml takes it from there: if nobody bumped the version by hand, it resolves the next version (.github/scripts/resolve_version.py) from the labels on every PR merged since the last tag (minor/feature/enhancement → minor, fix/bug/patch → patch, an unlabeled PR defaults to patch; a PR whose only labels are chore, ci, docs or dependencies is not releasable, so a merge that changes no shipped file releases nothing). Most PRs don't need a label added by hand: release-drafter.yml's autolabel job applies one automatically from the PR's title/changed files (Fix ... → fix, Add .../feat ... → feature, docs/.md/.github//build(deps) changes → chore) as soon as it's opened — add a label yourself only to override that. A major version is never chosen automatically: no label rule produces major, and the workflow refuses to auto-bump across a major boundary even if someone applies that label — a real major release is a deliberate package.json bump in a PR, which the manual path below already handles. It bumps package.json and docs/contract.md, writes a CHANGELOG.md section listing those PRs (and any issues they closed), and pushes that commit to main itself. Either way — auto-bumped or hand-bumped in the PR — it then creates the vX.Y.Z tag, publishes a GitHub Release with notes extracted from CHANGELOG.md's matching section, and publishes the package to npm. A PR that still wants to write its own version bump and CHANGELOG.md prose (e.g. to explain the "why" of a release by hand) can — the automation only fills in when nobody made that call already. A push to main with nothing new to release is a no-op. npm publishing needs an NPM_TOKEN repo secret (an npm access token with publish rights on this package) — without it the tag and GitHub Release still happen, only the npm step is skipped. A repo that depends on this one (an editing skill, an agent) should pin an ffmpeg-skill version by tag or npm version, not by tracking main — a merged-but-not-yet-released commit on main can be ahead of the last published npm version for the few minutes between merge and this workflow completing.

Contributing a change: see CONTRIBUTING.md.

Docs

Support

If this skill saves you time, you can help keep it maintained through GitHub Sponsors. Issues and pull requests are just as welcome.

License

MIT