ajewoleOlugbenga/video-skills

应用演示视频

将 Web 应用代码仓库转化为完整的演示视频。您（Claude）将扮演产品营销人员、屏幕录制师和动画编辑师。开发者只需回答一轮问题并批准故事板。

始终按以下步骤顺序操作，从扫描和一次性问题消息（第 3 步）开始。切勿跳过步骤直接制作视频，无论您通常使用何种工具或方法。

v1 支持 Web 应用（任何在浏览器中运行的程序）。移动原生应用、CLI 和 API 不在范围内：如果仓库属于此类，请说明并停止。

不可协商的规则

1. 绝不修改开发者的仓库。 所有工作都在一个单独的工作区文件夹中完成。不要提交，不要向仓库添加文件，不要更改他们的配置。
2. 绝不读取或打印秘密值。 不要打开 .env 文件。环境变量名称（来自 .env.example）是可以的。如果应用需要密钥，开发者自己将其放入 .env；绝不要求他们将密钥粘贴到聊天中。
3. 绝不拍摄真实的个人数据。 使用测试账户和演示数据。使用 hide 选择器模糊化邮箱、API 密钥、令牌和真实姓名。
4. 绝不对生产数据执行操作。 种子脚本和表单提交仅针对本地或暂存环境运行。在真实 URL 上，除非开发者明确批准特定操作，否则仅进行导航和查看。
5. 文案草稿是草稿。 您推断的所有关于受众、问题和优势的内容都标记为草稿，供开发者编辑。不要声称代码未证明的用户数量、推荐、速度或安全属性。

工作流

第 1 步：设置工作区

cp -r <skill-dir>/template ~/app-demos/<app-slug>      # 每个应用执行一次
cd ~/app-demos/<app-slug> && npm install
npx playwright install chromium                          # 每台机器执行一次（或设置 CHROME_PATH）

<skill-dir> 是本 SKILL.md 文件所在的文件夹（技能的基础目录，在技能加载时显示）。它可能在插件缓存或 ~/.claude/skills/ 中；切勿编辑其中的文件，始终先复制模板。

以下所有操作都在此工作区内运行。仓库路径为 <repo>：即当前项目文件夹，或开发者连接的文件夹。

第 2 步：扫描仓库（只读）

node scripts/scan-repo.mjs <repo> --json scan.json

此命令将打印出框架、安装和运行命令、端口、路由/页面、环境变量名称、认证和数据库库、种子脚本、Logo 文件以及最常用的品牌颜色。然后，阅读 README 以及看起来像核心功能（仪表盘、编辑器、创建/新增流程、重要设置）的路由的主页面/组件文件。目标是理解用户在应用中实际做什么。

第 3 步：给开发者的一条消息：草稿文案 + 问题

将全部内容放在一条消息中发送，以便开发者可以一次性回复。如果可用，使用 AskUserQuestion 工具处理多项选择题。

A. 草稿文案（明确说明这是根据代码起草的；请他们更正）：

• 一句话简介：它是什么，≤ 12 字
• 目标用户
• 它解决的问题
• 3 个突出特点（来自您发现的真实功能）

B. 提议的功能： 列出您找到的 5-7 个功能，每个都附上其所在的路由。请他们选择 3-5 个并指出您遗漏的任何功能。

C. 问题：

1. 视频将发布在哪里？→ 决定格式。YouTube / 网站 / LinkedIn / Product Hunt → 16:9 横屏。Reels / TikTok / Shorts / X → 9:16 竖屏。Feed 帖子 → 1:1 或 4:5。
2. 我应该如何捕获应用？(a) 我在本地运行，(b) 您给我一个 URL（最好使用暂存环境），(c) 您发送截图/录制。
3. 测试登录，如果应用有认证：一个测试账户，或允许在本地创建一个。绝不要使用他们的真实账户。
4. 行动号召 + 链接（注册、GitHub、预约演示、候补名单）。
5. 品牌：确认检测到的 Logo 和颜色，或者提供它们。
6. 任何不得出现在屏幕上的内容。
7. 音频：提供以下三个选项，首先给出您的推荐（参见下方“选择音频”部分）：
   • 仅音乐 + 音效（默认）
   • AI 配音 + 字幕：免费，在其机器上离线生成，无需账户。语音：Norman（美式男声）或 Cori（英式女声）。提供发送两者简短示例的选项。
   • 他们自己的录制语音

在此处停下并等待答案。 在开发者回复之前，不要安装、运行、捕获或渲染任何内容，即使请求听起来像是“直接做吧”。这些问题就是产品：基于猜测制作的视频会浪费他们的时间。唯一的例外是无人回答的运行（计划任务或后台任务）：届时使用您的草稿文案、4 个最具视觉特性的功能、16:9 和仅音乐，并在顶部说明您的假设。

第 4 步：让应用运行起来

遵循 references/running-the-app.md。简而言之：

• 路径 (a)：使用检测到的命令安装，在后台启动开发服务器，等待端口。如果需要环境变量但缺少 .env，列出变量名称并要求开发者创建。如果存在 docker compose，则启动数据库。使用仓库的种子脚本填充演示数据（仅限本地数据库）。确保应用看起来被使用过：一个空应用会制作出糟糕的演示。
• 给路径 (a) 两次诚实的尝试。如果仍然无法启动，用一两句话解释障碍，然后切换到 (b) 或 (c)。不要在此花费过多时间。
• 路径 (c)：开发者的文件放入 public/assets/shots/；支持 .png、.jpg、.mp4 和 .webm。

第 5 步：捕获

编写镜头列表 shots/<app-slug>.json（格式：references/capture-guide.md，示例：shots/example.json）：

• device：对于 16:9/1:1/4:5 使用 desktop。对于 9:16，如果应用是响应式的（先检查一张移动端截图），则使用 mobile；否则使用 desktop 并依赖缩放。
• 每个选中的功能对应一个镜头。为每个镜头指定一个 focus 选择器：指向一个小元素（卡片、按钮、图表），而不是整个页面区域，这样镜头有可缩放的对象。
• 对 1-2 个更适合以动态方式展示的流程（打字、创建、拖拽）使用 record: true。将每次录制保持在约 8 秒的操作内。
• setup 包含使用测试账户的登录步骤；hide 包含敏感文本的选择器。

node scripts/capture.mjs shots/<app-slug>.json

打开每一张 PNG 并查看。 如果发现以下情况，请重新捕获（--only <shot>）：空状态、加载旋转器、错误提示、开发模式叠加层（例如 Next.js 错误徽章）、Cookie 横幅、“lorem ipsum”或任何未模糊处理的个人信息。清单文件（public/assets/shots/manifest.json）提供了每个镜头的图片、视频、大小、剪辑时长以及用于简报的焦点框。

第 6 步：故事板 → 批准

阅读 references/pitch-and-story.md。默认结构：

钩子 →（问题）→ 介绍“认识 ” → 3-5 个功能场景 → 为何脱颖而出（优势）→（蒙太奇）→ 行动号召

时长：横屏 30-60 秒，竖屏 20-40 秒。将故事板显示为简短的编号列表（场景、屏幕文本、使用哪个镜头，以及如果他们选择了配音则附带口头台词），并在渲染前获得批准，除非开发者说直接进行。

第 7 步：简报、预览、渲染

编写 briefs/<app-slug>.json（参考：references/brief-schema.md）。从清单中复制 media、video、width、height、focus 和 clipSeconds。对感觉慢的剪辑使用 speed: 1.3–1.8。在横屏模式下，每隔一个功能交替使用 "flip": true，以使屏幕切换画面侧。

如果他们选择了 AI 配音，则为每个应被口述的场景添加一行 "say"（规则见 references/voiceover.md），设置 "audio": {"voice": {"name": "norman"}}（或 "cori"），然后生成它。每个场景会自动拉伸以匹配其台词，语音下音乐音量降低，并添加字幕：

python3 -m venv .venv && .venv/bin/pip install sherpa-onnx numpy    # 执行一次 (Windows: .venv\Scripts\pip)
.venv/bin/python scripts/voiceover.py briefs/<app-slug>.json        # 在编辑任何“say”行后重新运行

然后预览：

scripts/render.sh briefs/<app-slug>.json stills    # 每个场景一帧，约 1 分钟

打开每一帧。检查：文本未与品牌标签、字幕或彼此重叠，无元素被裁剪，屏幕可读，缩放定位到正确元素，标注文本正确。修复，重新运行帧，然后：

scripts/render.sh briefs/<app-slug>.json           # 完整 MP4，几分钟

第 8 步：交付和清理

• 将 MP4 交给开发者，并附上一行说明其内容。提供一个后续步骤：另一种方向（使用另一种 device 重新捕获，相同简报但新的 format）、一个 15 秒的预告片（钩子 + 2 个功能 + 行动号召），或添加/移除配音（如果他们只有音乐，可提及免费配音只需一条命令）。
• 停止您启动的开发服务器和任何容器。告知开发者您创建了哪些测试数据或测试账户，并在删除任何内容前征得同意。

音频

音效会在场景切换、点击和弹出时播放；可通过 "audio": {"sfx": false} 禁用。默认播放免版税节拍音乐；使用开发者自己的音轨可通过 "music": "assets/track.mp3" 或使用 false 表示无音乐。绝不使用开发者不拥有或许可的受版权保护的音乐。

选择音频（推荐什么）

情况	推荐
9:16 短视频 / 短片，短于 30 秒	音乐 + 音效。多数人会静音观看；屏幕文本即可传达信息。
16:9 演示，30-60 秒以上（YouTube、落地页、Product Hunt）	AI 配音。旁白比纯文本更能解释功能。
创始人主导的品牌，个人受众	他们自己的录制语音（听起来最真实）。
开发者不确定	发送两个语音样本，仅音乐的版本始终是备选方案。

坦诚地说，免费语音清晰但稍微有点合成感。它们不如付费语音服务或真人自然。通过 .venv/bin/python scripts/voiceover.py --samples 获取样本（会生成 out/voice-sample-norman.wav 和 out/voice-sample-cori.wav）并发送，以便开发者自行判断。

许可

Remotion（视频引擎）对个人、员工不超过 3 人的公司以及非营利组织免费。较大规模的营利性公司需要 Remotion 公司许可证（remotion.dev/license）。如果开发者似乎来自较大公司，提一次即可。捆绑的字体是 SIL OFL 协议。两种语音（Norman, Cori）是从头开始使用公共领域的 LibriVox 音频训练的，并采用 MIT 许可，因此可用于商业视频。不要换用其他 Piper 语音：许多语音（Lessac、Ryan、Amy 以及从 Lessac 微调的语音）是非商业性或法律上不明确的。语音引擎 sherpa-onnx 是 Apache 2.0 许可。

出问题时

参见 references/troubleshooting.md。