ffmpeg-skill 是一个专门为 Claude Code、Cursor、Codex 等 AI 编程助手设计的 Agent Skill。它的核心想法很简单：不让 Agent 自己拼 FFmpeg 命令，而是给它 28 个经过严格工程化的工具脚本，每个工具都有明确的输入输出契约，执行前先探测文件、执行后自动验证结果。全在本地跑，不需要云服务，不需要 API Key，不需要 Python 依赖——只用 Python 3.9+ 标准库和 FFmpeg 5.0+。
它到底解决了什么问题？
ffmpeg-skill 的 README 里有一段话特别有共鸣："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 的 Agent 还是会瞎猜——假设帧率、选容器不支持的编码、把只需流复制的文件重编码一遍、不看结果就说搞定。ffmpeg-skill 就是专门治这些问题的。它给 Agent 立了几条铁规矩：
规矩一：先探测，再动手
任何操作之前，必须先跑 probe.py。这个脚本会测出真实的帧率（还能检测可变帧率 VFR）、分辨率、旋转方向、色深、HDR 格式（包括 Dolby Vision）、色彩标签、所有音轨。Agent 从这些真实数据出发，而不是从文件名猜。
规矩二：能无损就不重编码
cut.py 和 loudness.py 默认优先用 -c copy 流复制。只有在必须帧精准剪切、需要用滤镜、或者容器/编码不兼容时才重编码，而且会报告一个 precision 字段告诉你精确到什么程度。
规矩三：先 dry-run，再执行
每个工具都支持 --dry-run。跑一下看看会执行什么 FFmpeg 命令，不会真的动文件。还有 --json 输出结构化结果，里面包含输出文件的 probe 信息；--fast 出个预览质量的快速版本先看看效果。
规矩四：执行完必须验证
跑完了不是直接说"好了"。而是要重新 probe 输出文件，确认时长、分辨率、帧率、音轨都对得上。如果画面变了（加了字幕、叠加了水印、裁了画面），还要跑 look.py 生成一张联系表（contact sheet）让 Agent 自己看。
规矩五：原文件永远不覆盖
输出文件都是新的 _.扩展名。有测试会对输入文件做 hash，跑完之后再 hash 一遍，确保没被改过。
28 个工具
分析检测类
- probe.py：全方面体检——时长、帧率（含 VFR 检测）、分辨率、编码、HDR 格式、色彩标签、所有音轨
- scenes.py：场景切换检测、音频峰值检测、高光片段候选
- look.py：从视频里截帧生成联系表 PNG，让 Agent "看到"自己做了什么
- doctor：能力检测——列出 FFmpeg 有哪些编码器、滤镜、封装器
- contract：输出机器可读的完整工具契约（JSON 格式）
编辑类
- cut.py：单段/多段剪切，默认流复制无损，需要帧精确时才重编码
- join.py：拼接多段视频，还能加转场，自动统一尺寸/帧率/音轨
- silence.py：自动检测静音/空白然后跳切，口语视频必备
- fit.py：调整时长（变速或裁剪）、适配纵横比
- crop.py：精确按像素裁剪矩形区域
- insert.py：把静图变成带 Ken Burns 推拉效果的视频片段
- background.py：生成纯色/渐变背景视频
- reverse.py：倒放
- stabilize.py：两轴防抖
音频类
- audio.py：人声清洗链路、FFT 降噪、压缩器/限制器、背景音乐 sidechain ducking
- sync.py：两路录音对齐（音频互相关，精度 1ms）、时钟漂移校正
- loudness.py：EBU R128 响度标准化
画面叠加类
- caption.py：烧录 SRT/ASS 字幕，支持字体/大小/颜色/描边/位置，可选本地 Whisper 自动转写
- overlay.py：Logo/水印/标题叠加，画中画，绿幕抠像
- graphics.py：下三分之一字幕条、章节标签、进度条、倒计时
- color.py：HDR10/HLG/Dolby Vision → SDR BT.709 色调映射，3D LUT
导出与交付类
- export.py：预设导出（YouTube/Reels/TikTok/X），ProRes 母版，HEVC，GIF 预览
- check.py：交付前合规检查
- verify.py：对输出文件做最终验证
- render.py：项目级渲染——把多个步骤写进 project.json
- proxy.py：生成低分辨率代理文件
- batch.py：批量处理文件夹
快速入手
# 为 Claude Code 安装
npx ffmpeg-skill
# 为 Cursor 安装
npx ffmpeg-skill --cursor
# 为 Codex 安装
npx ffmpeg-skill --codex
# 三个都装
npx ffmpeg-skill --all装完先跑一下 doctor 检查环境：npx ffmpeg-skill doctor。它会告诉你 FFmpeg 有哪些能力、哪些工具能用、哪些滤镜缺。
而且这套工具脱离 Agent 也能跑：
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
python3 $S/export.py input.mp4 --preset reels --jsonSPEC 契约驱动 + 自动 MCP
这个项目有个挺有原创性的设计，作者叫它 SPEC（Self-Producing Execution Contract）。普通的 Agent Skill 就是一堆提示词 + 一些脚本，Agent 能不能用对全靠运气。但 ffmpeg-skill 把每个工具的输入输出都变成了机器可读的 JSON Schema，而且这个 Schema 不是手写的——它直接从每个脚本的 argparse 解析器里自动生成。
MCP 支持也是自带的。跑 mcp/server.py 就是一个标准 MCP stdio 服务端，Claude Desktop、Cursor、任何 MCP client 都能直接连上，所有 28 个工具自动变成 MCP tools。
视频制作 Agent 生态
作者 kajisho5 的 GitHub 上有一整套视频制作 Agent 相关的仓库：
- ffmpeg-skill：执行层——裁剪、测量、导出文件，报告 JSON
- video-production-agent：决策层——决定剪哪里、审批成片、规划整个编辑
- AI-video-production-OS：编排层——跨仓库的 Capability 调度
- video-editing-skill / audio-production-skill：编辑层——在 workspace 上构建类型化的编辑图
- media-analysis-skill / transcription-skill / subtitle-skill 等：各司其职的专业模块
ffmpeg-skill 在这个生态里是"手"——它不会决定"这个高光够不够精彩"，但只做一件事：给我明确的参数，我就严格执行，然后把结果告诉你。
写在最后
FFmpeg 本身已经很强了，网上也不缺各种"FFmpeg 速查表"。但把 FFmpeg 工程化成一套给 AI Agent 用的、可验证的、不会猜的工具集，ffmpeg-skill 是做得比较完整的。你手里有素材、又懒得背 FFmpeg 参数的话，装上它，跟 Agent 说一声就行。