项目简介
reelbench-skills 是一组面向视频工作的 Claude Code 与 Codex skill。目前项目包含 video-shots 和 video-sync，分别用于成片拉片分析，以及制作随镜头切换同步更新分镜信息的视频。
项目仅依赖 Node.js 18 或更高版本，以及 ffmpeg 和 ffprobe。它没有 npm 依赖，也不要求额外配置 API Key，而是使用当前 Claude Code 或 Codex 会话的额度。
两项核心能力
video-shots：逐镜头拉片分析
video-shots 会把完整视频拆成逐镜头分析表，记录时长、景别、类别、运镜、画面与节奏等信息。镜头切点和时长由 ffmpeg 测量，模型负责判断需要语义理解的内容，最后通过 15 道质量门逐项检查结果。
生成的报告是一个没有外部依赖的单文件交互页面，可以离线双击打开。页面包含内嵌播放器、播放同步高亮、点击镜头跳转、镜头节奏带、搜索、筛选、排序、列表与卡片视图、首尾关键帧、统计分布、出场人物及质量检查。
窄屏设备也可以浏览镜头表，便于在不同尺寸的屏幕上检查分析结果。
video-sync：合成带分镜信息的视频
video-sync 用于把成片与分镜信息组合到同一个视频画面中。视频镜头切换时，对应信息会同步更新，镜头列表也会自动滚动并高亮当前项目。
- 横版素材可采用上下叠放布局。
- 竖版素材可采用左右并排布局。
- 布局集中在一份 CSS 中，便于统一调整。
安装前准备
开始前请确认系统已经安装以下工具：
- Node.js：版本不低于 18。
- ffmpeg：用于视频处理和镜头切点测量。
- ffprobe：通常随 ffmpeg 一起安装，用于读取媒体信息。
macOS 用户可以通过 Homebrew 安装：
brew install node ffmpeg还需要至少安装 Claude Code 或 Codex 之一。安装脚本会检查当前环境，并把 skill 链接到已存在的对应目录。
安装 reelbench-skills
克隆并自动安装
首先克隆仓库，然后执行安装脚本：
git clone https://github.com/eternityspring/reelbench-skills.git
cd reelbench-skills
./scripts/install.sh默认情况下，脚本会根据本机环境，将 skill 软链接到 ~/.claude/skills/ 和／或 ~/.codex/skills/。
选择安装目标
如果只希望安装到特定工具，可以使用对应参数：
./scripts/install.sh --claude
./scripts/install.sh --codex第一条命令只安装到 Claude Code，第二条只安装到 Codex。
只安装一个 skill
如果当前只需要拉片能力，可以按名称安装：
./scripts/install.sh video-shots同理，可根据实际需要选择仓库中提供的其他 skill。
不使用软链接
每个 skill 都是自包含的，因此也可以直接复制到目标目录：
cp -r skills/video-shots ~/.claude/skills/复制方式简单直接，但仓库更新后需要重新复制；软链接方式则可以让更新立即反映到 Claude Code 或 Codex 的 skill 目录。
基本使用流程
使用 video-shots 分析成片
- 确认
video-shots已安装到当前使用的 Claude Code 或 Codex。 - 准备需要分析的视频文件。
- 在当前会话中明确要求使用
video-shots对视频进行拉片，并说明期望的输出语言。 - 等待流程完成后，优先打开生成的 HTML 报告检查镜头划分、关键帧和质量结果。
- 如需后续处理，可读取 JSON、Markdown 或运动曲线数据。
可以在会话中使用类似下面的任务描述：
请使用 video-shots 对这个视频进行逐镜头拉片，输出镜头时长、景别、类别、运镜、画面与节奏分析，并检查质量门。仓库中的英文广告示例使用了 --lang en，生成的报告内容为英文。需要英文产物时，可在任务中明确语言，并参考该参数设置。
理解拉片产物
仓库提供的 demo-report 来自一条 202.9 秒的 AI 短片《啥是AI》。示例共识别 53 个镜头，平均镜长为 3.83 秒，每分钟 15.7 次切换，并通过全部 15 道质量门。
示例目录展示了典型产物的组织方式：
demo-report/
├── shots-report.html
├── shots.json
├── shots.md
├── track.json
└── frames/shots-report.html：单文件交互式拉片报告，可直接双击打开。shots.json：逐镜头拉片的主数据。shots.md：Markdown 格式镜头表。track.json：逐帧差分得到的运动曲线，作为机器测量证据。frames/：每个镜头的首尾关键帧；53 镜示例中共有 106 张图片。
建议先在 HTML 报告中完成可视化检查，再根据后续自动化需求使用 shots.json 或 track.json。
使用 video-sync 制作同步展示视频
- 准备成片和对应的分镜信息。
- 确认
video-sync已安装。 - 在 Claude Code 或 Codex 会话中要求使用该 skill 合成视频。
- 根据横版或竖版素材选择上下叠放或左右并排布局。
- 生成后检查镜头切换、信息更新、列表滚动与高亮是否同步。
任务描述可以写成：
请使用 video-sync 将这条视频与分镜信息合成。镜头切换时同步更新信息，并让镜头列表自动滚动和高亮。仓库示例展示了一个 30 秒英文广告片与 5 镜分镜信息的合成结果，输出尺寸为 1280×1296。可以在 demo-sync 示例目录中查看相关文件。
进阶技巧
利用软链接快速更新
如果通过安装脚本创建了软链接，只需在仓库中执行：
git pull更新内容会立即对已链接的 skill 生效，不需要再次复制文件。这种方式尤其适合持续跟进项目版本。
按需安装，减少环境干扰
只使用 Claude Code 时加上 --claude，只使用 Codex 时加上 --codex。如果仅处理拉片任务，也可以只安装 video-shots，让 skill 目录保持精简。
优先检查机器证据
拉片结果出现疑问时，可以结合 track.json 中的逐帧差分运动曲线，以及每镜首尾关键帧进行复核。项目将切点和时长交给 ffmpeg 测量，有助于把可量化部分与模型判断部分分开。
利用报告进行快速复核
播放视频时观察当前镜头是否正确高亮，再利用搜索、筛选和排序定位特定景别、类别或人物。点击镜头可以跳转到对应时间，点击关键帧则可以查看大图。完成检查后，再查看质量检查区域是否全部通过。
调整 video-sync 布局
video-sync 的布局集中在一份 CSS 中。需要适配不同画幅时，可以从横版的上下布局或竖版的左右布局开始调整，而不必分散修改多处样式。
卸载软链接
如果不再需要这些 skill，可以执行：
./scripts/install.sh --uninstall该命令用于取消安装脚本创建的软链接。
总结
reelbench-skills 把视频拉片和分镜同步展示封装成可供 Claude Code 与 Codex 使用的 skill。借助 video-shots，可以获得带机器测量证据、关键帧和质量检查的交互式报告；借助 video-sync，可以制作镜头切换与分镜信息同步的视频。项目依赖少、无需额外 API Key，并支持软链接更新和离线查看报告，适合构建可复核的视频分析工作流。