ffmpeg-skill 开源：让 Claude Code、Cursor 真正会剪视频，而不是瞎猜 ffmpeg 参数

用过 Claude Code、Cursor、Codex 这类编程 Agent 的人大概都试过让它们「顺便剪个视频」。结果往往是：Agent 猜一个帧率、选一个容器根本装不下的编码格式、明明只需要流复制却整段重编码，剪完还不打开看一眼就报告「完成」。

GitHub 上的开源项目 ffmpeg-skill 就是冲着这个痛点来的：给 Agent 一套固定工作流和趁手的工具，让它从「假装会 ffmpeg」变成「真的会剪」。

核心思路：probe → edit → check → verify

ffmpeg-skill 是一个面向 Claude Code、Cursor、Codex 以及任何读取 SKILL.md 的 Agent 的「Agent Skill」。它教给 Agent 一条铁律式的工作流：

  1. probe（先探测）：每个任务都从 probe.py 开始，Agent 根据实测的时长、帧率、分辨率、色彩和音频布局做决策，而不是根据文件名瞎猜；
  2. edit（能无损就无损）：优先流复制，避免不必要的重编码；
  3. check（边剪边校验）：每一步都有结构化输出可检查；
  4. verify（验证输出）：剪完必须真的打开结果确认，而不是口头报告「done」。

内置 42 个工具，覆盖 90% 的剪辑任务

项目内置 42 个工具，全部基于本地 ffmpeg / ffprobe 完成：

  • 基础操作：剪切、拼接、去静音、适配时长与画幅、格式转换、改分辨率；
  • 字幕与动效：字幕烧录、卡拉OK字幕、叠层与运动图形；
  • 调色与音频：HDR→SDR 与 LUT、音频清理、响度归一（-14 LUFS）、带漂移修正的音画同步、类型化动态处理；
  • 进阶场景：多机位剪辑、成片交付检查、整个剪辑项目的工程化渲染、批量文件夹处理。

所有命令输出结构化 JSON，方便 Agent 解析和串联。整套工具同时以 MCP 工具形式暴露（默认只广播 12 个核心工具以节省上下文，设置 FFMPEG_SKILL_MCP_FULL=1 可列出全部 42 个）。

几个值得学的设计细节

本地优先，零依赖云服务。只要 PATH 里有 ffmpeg 和 python3 就能跑：离线可用、不需要 API Key、不需要注册账号，素材也不用上传——对有隐私要求的 footage 很友好。

SPEC 自产契约。每个工具的 input_schema 不是手写维护的，而是在运行时从定义 CLI 的同一个 argparse 解析器推导出来的，CI 会在两者漂移时直接让构建失败。CLI 参数和 MCP 工具定义因此永远一致。

53 组前后对照 demo 全部可复现。官方文档里所有示例图都由 python3 demos/build.py 从合成素材生成，每一帧你都可以自己重建验证。

上手方式

# 前置：本地装好 ffmpeg（Ubuntu: sudo apt install ffmpeg / macOS: brew install ffmpeg）
npx ffmpeg-skill

装好后直接用自然语言下指令即可，比如「把这段视频的前 30 秒剪出来」「合并这 3 个片段」「压到 10MB 以内」「0:15 到 0:20 做成 GIF」「右下角加水印」「0.5 倍慢放」「加 2 秒淡入淡出」——Agent 会把意图翻译成正确的 ffmpeg 命令，复杂剪辑还能自动串多条命令。

小结

ffmpeg-skill 的价值不只在「让 Agent 会剪视频」，更在它示范了一套让 Agent 干真活的工程范式：先测量再决策、结构化工具而非 shell 字符串、输出必须验证。这三条放到任何 Agent + 命令行工具的组合里都成立。做 AI 工作流的人，值得把它的 SKILL.md 翻出来读一读。

本文整理自 GitHub 开源项目 ffmpeg-skill（kajisho5/ffmpeg-skill）README 及公开资料（纯文本来源标注，无外链）