Communitygithub.com

/reel:面向Claude Code的视频制作技能

指导AI代理如何规划、构建或剪辑“短视频”,最终输出一个完成的视频剪辑。流程遵循/reel步骤:先定方向,再剪辑,最后强制交付。当新任务需要此技能时使用。

reel:面向Claude Code的视频制作技能 是什么?

`/reel` 是一个基于ffmpeg构建的分层工具,专门为Claude Code等AI代理设计的视频制作技能。它提供了一套严谨的、代码强制执行的五步交付流程:先写brief并注册、试音、检查渲染、审查、交付。核心原则是“方向先行,再行剪辑”,意味着在开始任何编辑工作前,必须先由`director`代理撰写BRIEF文档和故事板,并在交付前进行对照审查。该技能支持可配置的输出尺寸(默认1080x1920垂直格式),并提供了丰富的命令用于素材检查、计划编写、预览渲染和最终交付检查。它通过JSON格式的标准化输出(如brief.json, plan.json, reviews.json)与AI代理交互,并利用Bash钩子(Hook)强制执行交付流程,确保每个步骤(如voice audition)都被正确完成。无论是独立剪辑还是从Shotcut等工具导入的项目,只要是需要对外发布的视频,都应遵循此流程。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shuaige121/reel/tree/HEAD/skills/reel

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

/reel:面向Claude Code的视频制作

一个基于ffmpeg构建的分层工具。你(Claude)负责审视素材,决定呈现什么并编写计划;代码负责处理构图几何、渲染和检查。输出尺寸可配置(默认为1080x1920的垂直格式)。

命令和文件格式记录在reel仓库的docs/ENGINE.md中。在执行第一条命令之前,请先阅读它:cat "$(reel --root)/docs/ENGINE.md"。reel <command> --help 会列出所有选项。每个命令都会打印一个JSON对象({"ok": true, "result": ...} 或 {"ok": false, "error": {"code": ..., ...}}),并且在失败时以退出码1结束。

工作顺序:方向先行,再行剪辑

对于任何用户之外的人将会观看的视频,请遵循SOP.md:S0素材摄入,S1源打包,S2资产清单,S3-S4 一个 director 代理编写 direction/BRIEF.md 和故事板,然后立即开始剪辑(默认情况下,G1审批步骤不会阻塞流程),最后进入下面的交付关卡。在S7阶段,一个独立的 director 代理会根据BRIEF审查剪辑结果。作为插件安装后,该代理被命名为 reel:director。

  • 将原始素材的路径提供给导演,而不是你自己的结论。
  • 如果已存在经过审批的BRIEF,并且目的、受众和素材范围没有改变,请遵循它。
  • 如果用户说视频很无聊或没有意义,请回到S3阶段重新构思整个作品;不要仅仅重新剪辑。

交付关卡(强制)

每个步骤都由代码强制执行:跳过任何一步,你都无法交付最终剪辑。

  1. 先写brief($P/brief.json,模板见下文)并注册它:reel register brief.json。交付语言、最终版或样片、交付文件夹以及不得更改的内容:如果你无法填写这些,请询问用户。一旦注册,Bash守卫钩子会拒绝向交付文件夹写入 cp/mv/ffmpeg 等操作。
  2. 试音。 没有默认语音。选择一个符合brief的语音,渲染一个10-20秒的样片,然后运行 reel voice check sample.mp3 --script sample.txt --brief brief.json。本地的Whisper会转录样片并与文本进行比较(--lang 默认为 en;对于中文配音,请传递 --lang zh,它会通过无声调拼音进行比较,因此同音字拼写不会算作错误);只有当错误率低于或等于10%时,才会将审批写入 brief.voice.approved(by: claude,并附上转录文本作为证据)。如果用户听过,请直接记录他们的确切措辞。
    • 语音转文字(STT)证明单词被正确且清晰地朗读。它不能证明语音适合该作品:在你的回复中说明你选择的语音,并在下一版本中更换语音(如果用户不喜欢)。
    • 新的语音需要新的检查。macOS 的 say 语音仅用于内部草稿,绝不可用于最终交付的视频。
  3. 检查渲染结果: reel check final.mp4 --plan plan.json --brief brief.json [--profile vertical-strict|project-profile.json] [--text caption.txt]。
    • 退出码1意味着它无法交付。请阅读 result.gate.blockers(技术性失败:即使是样片也无法交付)和 result.gate.pending_review(需要审阅者检查的项目)。
    • 不要仅仅依赖 ok。result.gate.not_covered 列出了未被检查的项目(例如屏幕上的文字,因为没有OCR);永远不要说这些项目已通过检查。
  4. 审查。 查看每一个 needs_review 项目(reel scrub,逐帧抓取)并为每个项目编写一条带有时码观察的审查记录。自己观看整个剪辑并签署 final_watch(每个镜头至少一帧);从头到尾听一遍并签署 final_listen(代理签名需要带有时码的观察记录;如果用户听过,请将他们的确切措辞记录为 quote)。当你签署了这两项后,即可将其作为最终版交付:收据上写着 approved_by: agent,你的回复会说“最终剪辑,由Claude审查,您尚未观看”。用户的反馈将成为下一个版本的基础。reviews.json 的格式在 docs/ENGINE.md 中。
  5. 交付: reel deliver final.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json。
    • 如果最终条件未满足,它会失败并显示 DELIVERY_NOT_FINAL,并列出原因。此时只能使用 --sample:文件名会带有 sample-pending-review,并且你在告知用户时必须称其为样片。
    • 一个版本号只能交付一次;旧版本永远不会被删除或覆盖。只有当用户明确要求移除旧版本时:reel register brief.json --remove,删除,然后重新注册。
  6. 说“完成” 需要一个状态为 final 的收据(reel receipt <receipt.json> 会重新验证它)。否则,请说明真实状态:“未完成”、“样片待审”、“语音未试音”。停止钩子(Stop hook)会阻止声称完成但没有匹配收据的情况。
  7. 由项目自身的渲染脚本(如 build_*.py)制作,或在其他工具中合成并导出的视频,也需经过步骤3-6。
{"version": "reel.brief.v1", "name": "spring-promo", "language": "en", "deliverable": "final",
 "delivery_root": "~/Videos/deliveries/spring-promo", "must_not_change": ["end card credit"],
 "voice": {"mode": "recorded"}, "profile": "default"}
  • voice.mode: none(无语音)、recorded(真实录音)、tts 或 clone(后两者还需要 voice_id 以及由 reel voice check 写入的 approved 块,或者带有 quote、sample 和 sample_sha256 的人工审批)。
  • delivery_root 必须是一个已存在的绝对路径(或以 ~ 开头)。它不能是home文件夹、桌面、文档、下载、iCloud Drive根目录、项目文件夹或其父目录。
  • 静音版本使用项目配置文件:{"extends": "default", "audio": "silent"}。
  • 配置文件:default(通用的起始阈值)和 vertical-strict(1080x1920 30 fps, -16 LUFS, 严格)。将项目差异放在一个使用 extends 的项目配置文件中;在 allow 中注册预期的长停顿并附上原因;将禁用词(旧产品名、占位文本)添加到 text.extra_banned 中。

在每个Bash调用的开头

每个Bash调用都会启动一个新的shell,因此请在每个调用的开头使用:

REEL_PROJECT=spring-promo                      # 此项目的名称
command -v reel >/dev/null || { echo "reel is not on PATH (enable the plugin, or run ./install.sh --link)" >&2; return 1 2>/dev/null || exit 1; }
command -v ffmpeg >/dev/null || { echo "ffmpeg not found" >&2; return 1 2>/dev/null || exit 1; }
P="${REEL_PROJECTS_DIR:-$HOME/reel-projects}/$REEL_PROJECT"; mkdir -p "$P/preview" && cd "$P"

所有输出文件都位于 $P 中,绝不要在临时文件夹中;下面的相对路径都是相对于 $P 的。

制作剪辑

你做决策(哪些镜头、哪个主体、摄像机运动、节奏);感知、几何、渲染和检查由代码完成。完整的命令语法在 docs/ENGINE.md 中。

  1. 素材 放入 $P(资产、observations.json、plan.json、预览、渲染和检查报告都存放在那里;每个计划一个文件夹)。
  2. 脚本和语音。 撰写配音脚本,选择符合brief的语音并通过试音(交付关卡第2步)。生成 voice.mp3(或 .wav),如果需要字幕,则生成 voice.vtt。对于出版作品,优先使用真实录音或其许可证覆盖所用场景的语音;对于纯音乐作品,将 audio.voice 指向音乐轨道(它是时间轴锚点)。
  3. 查看并选择目标: reel inspect(列出每个文件)→ reel frame(读取带有0-1网格的图像,并读取主体边界框)→ reel observe 注册它,或 reel locate --query ... --check-png ... (OWLv2;在使用检测结果前,先查看检查图像)。
  4. 编写 plan.json (EditPlan v1):camera: [] 保持画面静止;zoom_to 配合 observation_id 推近到已注册的主体上;当主体在视频中移动时使用 track;transition_out 用于转场。不要让一个视频镜头跨越 inspect 报告的镜头切换点。audio.voice 是必需的,并且相对于 src_dir 解析。
  5. 验证和预览: reel validate → reel compile → reel preview plan.json s2 --out preview/s2.mp4 --sheet preview/s2.png,然后阅读联系表来评判摄像机运动。
  6. 渲染: reel render plan.json --out "$P/final.mp4" --sheet "$P/preview/final.png" --where local(仅当用户配置了远程GPU并明确要求时才使用 --where remote)。通过渲染检查仅意味着文件未损坏;继续执行交付关卡步骤3-6。

其他入口点,每个在 docs/ENGINE.md 中都有相应章节:

  • 检查并更改时间轴: reel timeline(--format text 或 --png 多轨道图像)、reel scrub(每个剪辑点周围的帧)、reel edit / undo / history、reel preview --range(带声音的低分辨率预览)。
  • 跟随节拍剪辑: reel beats music.mp3 --out beats.json → reel snap plan.json --beats beats.json --mode downbeat;然后使用 reel timeline --png --beats 检查每个剪辑点。需要 ./install.sh --beats。
  • 高亮叙述网页: 使用 kind: "web" 的镜头;文本位置来自DOM(无OCR),因此高亮句子必须与页面文本完全匹配;reel words voice.mp3 提供逐词计时。需要 ./install.sh --web。
  • Shotcut项目: reel mlt project.mlt --video-only;--dupes 查找使用了两次的源素材。

可用功能:计划组装、主体边界框亚像素推进、跟随移动主体、xfade转场、嵌入字幕、背景音乐、调色和LUT、网页镜头、OWLv2主体搜索、技术检查、关卡式交付。

未内置功能:缓动转场、帧插值、语音克隆。

远程GPU(可选)

--where remote 部分由代码强制执行。

  • 仅当用户配置了 REEL_REMOTE(一个ssh目标地址)并明确要求时才使用它;否则使用 --where local 进行渲染。
  • VRAM使用量默认限制在80%。当任务需要更多时,工具返回 NEED_USER_APPROVAL:首先告知用户,并且只有在用户同意的情况下才添加 --allow-over-80。GPU利用率达到50%或更高表示有其他人在使用;不要占用。
  • 一次只能运行一个reel GPU任务(远程文件锁)。不要更改功率限制。切勿重启或关闭主机。
  • reel remote probe 报告远程主机信息;reel remote setup-vision 会在远程主机上安装一个带有torch和OWLv2权重的独立venv。

配套文件

  • SOP.md:方向先行的工作流程、角色、步骤和退出条件。
  • director 代理(存储在仓库中的 agents/director.md):brief、故事板和审查。
  • 仓库中的 docs/ENGINE.md:命令、EditPlan、brief、审查记录、收据和配置文件。

相关技能