kajisho5/ffmpeg-skill surged on GitHub trending in mid-November 2026—on the order of 6000+ stars with hundreds gained in a single day—by promising coding agents a local video editor with 42 FFmpeg tools, a machine-readable contract, and an MCP server for Claude Code, Cursor, Codex, and generic MCP clients. If your team lets agents touch marketing footage, screen recordings, or incident clips, this is exactly the kind of high-permission skill that belongs next to Cloudflare’s audit skill and Claude-BugHunter on your pre-install review queue—not because it is malware, but because it runs real binaries on real files.
| Question | Short answer |
|---|---|
| Am I affected? | Only if you run npx ffmpeg-skill or add its MCP server to a harness you use daily |
| Is there a fix? | No incident—risk is trust and scope. Pin a commit, run doctor, scan SKILL.md, isolate media projects |
| Does data leave my machine? | Core tools: no cloud. Optional local ASR engines may download model weights the first time you transcribe |
| What powers the agent? | ffmpeg/ffprobe subprocesses from Python wrappers—not free-form shell ffmpeg strings from the model |
| What should I do today? | npx ffmpeg-skill doctor, beam scan on the skill folder, and separate engagement vs personal laptops |
What shipped in the repository
The README describes ffmpeg-skill as an Agent Skill (a SKILL.md workflow) plus structured tools under scripts/. The agent is trained to follow probe → edit (lossless when possible) → check → verify instead of improvising filter graphs in a terminal.
The 42-tool surface
Tools span analysis (probe.py, scenes.py, look.py), editing (cut.py, join.py, fit.py, caption.py, …), audio, color, delivery (export.py, render.py with platform templates like tiktok, reels, shorts), and batch folder operations. Each script supports --dry-run, --json, --plan, and --overwrite with explicit consent semantics documented in the README.
SPEC: contract derived from argparse
The maintainer’s Self-Producing Execution Contract (SPEC) means MCP inputSchema is generated from the same argparse parser as the CLI. CI fails if schemas drift. Practically, when you upgrade the skill, MCP tool shapes track CLI flags automatically—good for honesty, but it also means new flags become agent-callable the moment you refresh the install.
MCP exposure:
tools/listreturns a default core of 12 tools to keep client context small.- Set
FFMPEG_SKILL_MCP_FULL=1to list all 42 intools/list. tools/callcan reach any tool by name either way.
The README documents stdio MCP through mcp/server.py and npx ffmpeg-skill as the install entry.
Verification discipline
The project brands itself verification-driven: outputs are re-probed, checked against destination specs, and visually inspected via look.py contact sheets when video changed. The maintainer also published a 2026 position paper on Zenodo arguing agents should not treat generation as completion without verification—while noting ffmpeg-skill itself is only partially conformant to its own ideal. That honesty is a useful signal: you still need human or agent vision on the PNG sheet.
Why agents need structured FFmpeg instead of shell strings
When a model “knows FFmpeg,” the failure mode is predictable: wrong container/codec pairings, re-encoding when stream copy would work, destroying audio channels, and declaring success without opening the output. The ffmpeg-skill README leans on verification-driven coding—each tool returns structured JSON with post-run probes so the agent can branch on status fields instead of guessing from stderr noise.
The contract --json output also lists required FFmpeg components per tool (libx264, libass, loudnorm, zscale, …). That is how doctor distinguishes “this filter is missing on your Homebrew build” from “this input file is corrupt.” Security teams should archive a golden doctor JSON per CI image so drift alerts when interns update FFmpeg via package managers.
Windows paths deserve explicit review: the README notes Git Bash may lack python3 unless installed from the Microsoft Store; bin/install.js handles detection, but raw script examples may need python instead. Agents following Linux-centric SKILL.md snippets on Windows have caused accidental partial installs in other trending skills—test your platform matrix before endorsing the skill org-wide.
Install mechanics and harness coverage
Documented install:
# System FFmpeg once (platform-specific; see README table)
npx ffmpeg-skill # Claude Code
npx ffmpeg-skill --cursor
npx ffmpeg-skill --codex
npx ffmpeg-skill --all
The README warns already-installed copies do not auto-update—re-run npx ffmpeg-skill to refresh ~/.claude/skills/ffmpeg-skill.
Post-install checks shipped by the maintainer:
npx ffmpeg-skill doctor
npx ffmpeg-skill contract --json | head -40
doctor distinguishes overall ok vs per-tool usable when optional FFmpeg components are missing—important on minimal Homebrew FFmpeg builds without subtitle filters.
Platform delivery templates
Beyond one-off cuts, render.py can target social delivery specs documented in the README—templates named tiktok, reels, shorts, youtube, x, linkedin, facebook, podcast, and audiogram, with --template all rendering a multi-platform pack and a markdown table of outputs. Each template encodes aspect ratio, loudness targets, caption placement, and platform-specific checks via paired check.py --platform … invocations.
For security reviewers, templates matter because they are deterministic code paths—easier to audit than a model-authored ffmpeg filter string—but they still invoke network-less yet powerful media operations (burned-in captions, reframes, loudness normalization). Treat render.py --overwrite like any other destructive flag in agent policy.
Tool families at a glance
| Family | Representative scripts | Agent risk notes |
|---|---|---|
| Analysis | probe.py, scenes.py, look.py | Read-heavy; look.py writes PNG sheets agents may upload elsewhere if unsupervised |
| Editing | cut.py, join.py, fit.py, silence.py | Can produce large intermediate files filling disks |
| Captions / ASR | caption.py --transcribe, silence.py --transcribe | Pulls optional local ASR engines; first run downloads models |
| Color / HDR | hdr.py, LUT tools in README | Complex filter graphs; failures surface as ffmpeg stderr |
| Delivery | export.py, render.py, batch.py | batch.py had path traversal class issues—stay on latest release |
| Sync / multicam | sync.py, multicam utilities | Long runtimes; agents may set aggressive --timeout values |
This table is a review aide, not an exhaustive permission model—read the contract JSON for the authoritative mutates_input and verification flags per tool.
Ecosystem, not a monolith
The README places ffmpeg-skill as “hands” in a wider video-production-agent ecosystem (brain/orchestrator repos named separately). Dependency is one-way: other skills read this repo’s contract JSON; ffmpeg-skill does not call out to them. For security review, treat the npm/npx package and git clone as the trust boundary you actually install—even if README mentions sibling repos.
Security: what went wrong before and what still can
Maintainer track record
SECURITY.md asks reporters to use GitHub private advisories. It cites a real fixed issue: batch.py recipe steps that could resolve outside scripts/ via absolute paths or ../ traversal (fixed in #124). That is the class of bug where agents batch-processing folders could touch unintended paths.
Only the latest published version is supported—no LTS branch.
Agent risks that remain after patching
Even with structured tools:
- Overwrite consent —
--overwriteis documented but agents may enable it when users say “replace the old export.” - Large file reads — probe and transcription paths read full media; optional ASR uses local engines (Parakeet, faster-whisper, etc.) with first-run model downloads.
- MCP breadth — enabling
FFMPEG_SKILL_MCP_FULL=1widens prompt surface for tool discovery. - Sibling skills — trending invites
install.sh --all-style patterns from other bundles; keep ffmpeg-skill scoped to media workstations.
Compare with NVIDIA Skillspector and Trail of Bits regression-hunt skills—trending repos benefit from the same three-tier gates (lint, sandboxed run, human sign-off) even when LICENSE is permissive.
What this means if you run AI coding agents
Install workflow we recommend
- Clone and pin —
git cloneand note the commit SHA beforenpxcopies files into~/.claude/. - Scan before copy — run Beam’s offline scan on
SKILL.md,mcp/, andscripts/(see skill scanning cookbook). - Doctor before demos —
npx ffmpeg-skill doctoron the target machine; file gaps in your internal FFmpeg component matrix. - Dry-run first — instruct agents to
--dry-runor--planbefore any destructive join/render. - MCP inventory — if you enable MCP, record whether
FFMPEG_SKILL_MCP_FULLis set in the server environment.
Commands worth standardizing
npx ffmpeg-skill doctor
python3 ~/.claude/skills/ffmpeg-skill/scripts/probe.py sample.mp4 --compact
python3 ~/.claude/skills/ffmpeg-skill/scripts/fit.py sample.mp4 --duration 60 --aspect 9:16 --dry-run
Replace paths with your install location; the README uses ~/.claude/skills/ffmpeg-skill/scripts after npx.
Trending mechanics and typosquat vigilance
The repo’s GitHub trending entry for week 47 of 2026 recorded a sharp one-day star spike—enough to trigger drive-by installs the same way Claude-BugHunter did. Verify kajisho5/ffmpeg-skill spelling, npx ffmpeg-skill package provenance, and npm publisher metadata before you paste install commands into a team channel. Typosquats often copy README marketing text while swapping postinstall scripts—this repo’s package.json should be part of your diff review, not only SKILL.md.
The repository ships .clusterfuzzlite, .snyk, and a 590-commit history (per GitHub)—signals of maintainer seriousness, not a substitute for your pin-and-scan discipline. If your organization already catalogs skills with vlt 1.5.0’s linked npm dependencies, add ffmpeg-skill as a high-file-count entry with FFmpeg binary dependency.
When to refuse install
- Shared laptops with production AWS/GCP keys in the same workspace where agents render untrusted downloads.
- CI runners where FFmpeg network or script filters are banned—agents may still invoke allowed tools if MCP is wired.
- Regulated footage without a data-handling memo—local processing avoids cloud APIs, but logs and JSON output may still contain paths and metadata Beam or your SIEM stores.
How Beam handles this
Beam fits before and during skill load:
beam add skill/beam scanapply 11 heuristic patterns plus MCP version-pin checks toSKILL.mdand JSON configs—catching curl pipes, credential patterns, and unpinned remote servers before copy.- Skill-load hooks on Claude Code can hold or block skills with prompt-injection-shaped findings when workspace policy is enforce.
- PreToolUse deny (Claude Code / Codex) can limit destructive shell outside the structured FFmpeg tools—useful when agents try to
rm -rfafter a failed render.
After install, runtime observability still answers a different question than review: whether the agent actually called batch.py on a parent directory or bypassed structured tools with raw shell. Beam’s agent monitoring cookbook describes retaining tool-call history locally so you can compare tools/call names against approved lists. That is especially useful when FFMPEG_SKILL_MCP_FULL=1 exposes dozens of seldom-used tools to the model.
Beam does not parse FFmpeg filter graphs, does not prove batch.py path rules hold on your version, and does not sandbox FFmpeg binaries. Pair Beam gates with maintainer doctor and pinned versions.
Related reading
- Agent skills specification and security review
- MCP security: practical guide
- Cloudflare security-audit skill for coding agents
- Claude-BugHunter trending offensive bundle
- VLT 1.5.0 skills link npm dependencies
explainx.ai’s cinecode write-up covers another FFmpeg-adjacent trending skill—useful background on why video-generation skills cluster on GitHub in November 2026.
Frequently asked questions
The FAQ in front matter answers what ffmpeg-skill is, install commands, cloud exposure, MCP tool counts, trending safety, FFmpeg requirements, overwrite behavior, and Beam’s role.
ffmpeg-skill version, tool count, and MCP flags match the kajisho5/ffmpeg-skill README on GitHub as of November 16, 2026. Beam is a local prototype; confirm hook coverage before enforce mode.

