Communitygithub.com

josueh04/产品视频构建技能

协调一个或多个当前产品签名视频的构建,使用子代理(源复核、产品真实信息、UI规格、语音、每个视频一个构建器),自行重新运行QA,然后交付。一个轻量级协调器,从不自行构建。仅当用户输入 /video-build 时运行。

产品视频构建技能 是什么?

该技能是一个轻量级协调器,用于自动构建产品演示视频。它将构建流程拆分为多个阶段(源复核、产品真实信息、UI规格、语音、合成与渲染、QA、交付),并派遣专门的子代理完成各阶段工作,而主代理本身从不执行构建。该方法基于生产实践:当主代理仅负责协调时,修复效率提升了3倍(70分钟内完成3次修复)。技能支持多视频并行处理,通过文件检查子代理进度,并自行运行QA(使用 render-qa 技能检测渲染问题,如0.3秒闪烁或裁剪的模态框)。仅在用户输入 /video-build 时激活,要求先通过门控检查(BRIEF.md 签名),然后分波次派遣子代理,最后生成包含版本、时长、QA结果和交付文件的报告。设计用于 Claude Code 等 AI 代理平台,通过将状态保存在文件中而非代理内存中来避免上下文溢出。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/video-build

在你喜欢的 AI 中提问

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

文档

/video-build

你是协调器。你需要检查门控条件,按阶段派遣子代理,通过文件验证每个阶段,自行重新运行QA,交付并报告。你不会编写合成代码、规格说明或旁白,也不进行渲染。

为什么拆分:在生产中,当主代理自行构建视频时,其上下文填满了8次,其中一次在修复过程中间。当它仅进行协调(汇总、编写简报、审查证据、交付)时,70分钟内完成了3次修复。协调也是质量门控所在:子代理报告“干净”的渲染,而协调器自身的QA随后捕捉到了0.3秒的闪烁和裁剪的模态框。

0. 查找工作

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
PY="$PVS_HOME/bin/pvs-py"; S="$PVS_HOME/skills/video-build/scripts"   # 使用时引用两者
  • 带有 <video>:当前产品中的 videos/<video>/。
  • 不带:你所在的视频文件夹,否则是产品中所有工作表已签名且当前版本无交付的视频。在派遣任何内容之前,显示该列表并通过一个封闭问题确认。

对每个视频运行 "$PY" "$S/stages.py" <video_dir> 并显示表格。已完成的阶段将被跳过,因此 /video-build 可以从中途停止的构建中恢复。

1. 门控

"$PY" "$S/stages.py" <video_dir> --require signoff。如果 BRIEF.md 中的任一签名是空的,则停止并告诉用户缺少什么以及如何签名(审阅者写他们的名字,或告诉您运行 /video-new 中的 sign.py)。这是防止最昂贵的返工(审阅者希望解释的功能但无人记录)开始构建的检查。

--draft 是唯一的例外,且仅当用户输入了它:可以构建、渲染和QA检查草稿,以便审阅者在签名前看到结果,但 deliver.py 会拒绝它。在报告中说明这一点。

还要自行阅读 product.yaml、kit/RULES.md、BRIEF.md、COVERAGE.md 和 CLAIMS.md:你需要它们来编写子代理提示并判断其结果。不要深入阅读其他内容。

2. 派遣

使用 Agent 工具后台子代理。每个阶段的提示在 references/stage-prompts.md 中,构建器提示在 references/builder-prompt.md 中;在首次派遣前阅读它们并填充所有占位符。在每个子代理报告后,在启动任何依赖它的操作之前运行 "$PY" "$S/stages.py" <video_dir> --require <stage>。

波次阶段子代理需要写入
1源复核每个视频1个,source-recon签名sources.lock,SOURCES.md
2真实信息每个视频1个,product-truth源复核TRUTH.md
2规格每个屏幕1个,ui-spec-from-code(或用于无代码屏幕的 ui-reference-capture)源复核specs/<screen>.md
3语音每个视频1个,script-and-voice真实信息audio/lines.tsv,clips/,timings.json
4合成 + 渲染每个视频1个构建器,ui-demo-composer + seek-safe-motion规格,语音video/,renders/<video>-v<N>.mp4
5QA你渲染qa/REPORT.json
6交付你QAdeliveries/

波次跨视频并行运行,且在同一波次内(真实信息和所有屏幕的规格同时进行)。多个视频共享一台机器:在每个提示中说明没有代理会杀死它未启动的进程,并且渲染在其他代理运行时可能会变慢。

在第1版的波次3之前,如果语音提供商是付费的,通过一条消息向用户展示旁白计划:章节表、标语、语音,最多三个封闭决策(含默认值)。录制旁白会消耗共享配额,而审阅者不喜欢的语气或名字在录制前更改成本最低。如果用户已表示直接通过,则跳过此步骤,并在最终报告中列出选项供否决。

当子代理运行时,不要用消息轮询它们。通过文件检查进度(修改时间、$STAGES、渲染日志的尾部),并在它们发送问题时回答。审批上报给用户,决策下传:如果子代理请求只有用户才能允许的事情(下载、新资源源),则向用户提出一个封闭问题并转达答案。

如果子代理停止响应,启动一个新的,使用相同的提示并加上“之前的代理在 处停止;从文件继续”。状态驻留在文件中,而不是代理中。

3. 你自己的QA,无论构建器报告了什么

"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/render-qa/scripts/qa.py" <video_dir> <mp4> \
  --strip <name>:<t0>:<t1> ...

加载 render-qa 技能以了解如何读取结果。围绕每个章节标题、每个模态框和结束画面添加一条 strip,以锁定交接(时间来自构建器的章节表)。然后自行查看 qa/REPORT.md、每个联系表和每条 strip。对照 COVERAGE.md 检查旁白:每个“是”行必须在其章节中解释。

如果任何内容失败,将确切的问题发送回构建器(在其存活状态下使用 SendMessage,压缩修复格式见 references/stage-prompts.md),或者如果构建器已消失,则使用 $PVS_HOME/skills/video-review/references/fix-prompt.md 中的提示启动修复程序(读取文件;不要调用该技能,它是由用户调用的)。在新渲染上重新运行此步骤。永远不要交付你未自行QA的渲染。

4. 交付

"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/render-qa/scripts/deliver.py" <video_dir> <mp4> --archive-previous

它会拒绝草稿、失败的报告或sha256与文件不匹配的报告。不要绕过拒绝:修复原因。永远不要覆盖已交付的文件;deliver.py 会提升名称并发出警告,你应说明。

5. 报告

整个批次一张表,然后最多三个封闭决策:

视频版本时长章节覆盖率已解释QA交付为

在其下方:哪些是真实的、哪些是假设的、任何未验证的内容、名称/语音/标语供否决,以及下一步步骤(/video-review 带审阅者注释)。使用用户的语言、简短、表格优先。

何时读取参考文件

  • references/stage-prompts.md:在派遣波次1到3之前,以及任何修复请求时。
  • references/builder-prompt.md:在派遣波次4之前。

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

josueh04/product-video-skills

Extract, once per product, everything every video of it reuses and write it to kit/ and product.yaml (design tokens, font subsets as woff2, icon subsets as SVG from the product's own icon packages, logos in light, dark and app-tile variants from the repo, a fictional cast proposed once for veto and then frozen, the canonical-names map, pronunciations, banned terms and the read-only tool list). Use it when a product is set up or its kit is missing or incomplete, when a video needs an icon, font or logo that is not in kit/ yet, when someone asks for demo names, fake customers, phone numbers or emails, when a brand word is mispronounced or an old product name shows up, and when checking that demo data is fictional.

josueh04/product-video-skills

Interview the user about a product, then create products/<slug>/ with its own git history, a filled product.yaml and linked skills, fetch its sources and build its kit. Run only when the user types /product-new.

josueh04/product-video-skills

Back every sentence of a video's narration (audio/lines.tsv) and every screen it shows with a citation into the pinned source code (role/path:line@sha) or a docs URL, mark what is visible in the UI versus backend-only, flag restricted or unreleased features, and cut or rewrite anything unbacked; writes the video's TRUTH.md and checks it with truth_check.py. Use it whenever a script or narration is drafted or edited, before voice is generated, before a build, when someone asks "can we say this?", "is this true?", "does the product really do X?", when a reviewer asks for a feature or a claim the product may not support, and when a source document (pitch deck, PRD, marketing page) makes claims the video wants to repeat.

josueh04/product-video-skills

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

josueh04/product-video-skills

Write a product video's narration and turn it into voice clips with word timings, pronunciation fixes, sound effects and even loudness. The script becomes a table of moments and then audio/lines.tsv (one clip per sentence, with role and speed columns); tts.py voices it with ElevenLabs or the free macOS say voice, maps brand respellings back to the on-screen spelling, normalizes every clip and writes audio/timings.json for the composer; make_sfx.py builds typing tracks from real keystrokes and places recorded click and pop sounds. Use it whenever a video needs a script, narration, voice-over, lines.tsv, timings.json, TTS, a new take, a voice or casting choice, a pronunciation fix ("it says the name wrong"), a changed sentence, a tone note ("too hype", "sounds cut off"), audio levels, a click at the end of a clip, typing or click sounds, or when the build stage asks for the voice. Also use it for silent loops, which still need a moment table and SFX.

josueh04/product-video-skills

The animation rules that keep HyperFrames' parallel render workers from dropping, flashing or flickering elements, plus a static lint (lint_motion.py) that finds the violations in a video's template before it costs a render. Use it whenever you write or edit GSAP tweens, timelines, cursors, camera moves, typing, scrolls or pop-ups in a HyperFrames composition or a video's src/template.tpl, whenever a render shows flicker, stutter, an element that vanishes on some frames, a title that flashes, or a "WORKER PATTERN" line from scan_render.py or qa.py, and whenever the preview looks right but the MP4 does not. Also use it to review someone else's timeline code before rendering.

josueh04/product-video-skills

Pin a product's source code (read-only exports in sources/ plus sources.lock), confirm that the pinned commit is what runs in production, and map every screen of a video brief to its route, components, i18n strings and state, written to the video's SOURCES.md. Use it whenever a video needs to know where a screen lives in the code, when sources/ is missing or stale, before ui-spec-from-code or product-truth start on a video, after the product's frontend changed ("what changed", "which videos are affected", "refresh the sources", "is this checkout current", "which commit is in prod"), and when there is no code and you need an inventory of the no-code references (recordings, recovered captures, docs) a screen can be rebuilt from.

josueh04/product-video-skills

Compose a narrated product demo in HyperFrames: the stage (the product UI rebuilt at its real viewport and scaled to 1080p, camera, rack focus with veil, chapter titles, cursor and clicks, typing, streaming text, pop-ups, toasts, scrolls, end screen and lockup) and the build.py that anchors every beat to a word of the narration. Use it whenever you write or edit a video's video/build.py, src/template.tpl or src/app.css, place a beat on a word, add a chapter, a click, a pop-up or a push-in, frame a screen, build the end screen or lockup, snapshot setup beats, or render a draft or delivery MP4 of a product video in this workbench. Also use it when someone says "the cursor is off", "too zoomed in", "too fast", "it feels chaotic", "the title flashes", "sync the UI to the voice", or asks for a walkthrough, demo or pitch video of a UI.

josueh04/product-video-skills

Gather pixel references for UI that the code cannot show, or to check a rebuild against the real thing, using frames and timed OCR text from screen recordings, captures recovered from past Claude Code session transcripts, a local instance of the app built like production, and web research for third-party apps, plus side-by-side parity images and contact sheets. Use it whenever someone hands over a screen recording (.mov or .mp4) of the product, when a screen has no usable source code (a stale checkout, another company's UI such as a sign-in page, calendar or CRM, runtime output from a backend not in the repos), when asked "what does it really look like", "match the recording", "how long does that animation take in the app", "compare our render to the real app", or when screenshots from an earlier session might already exist. Never uses the reviewer's personal browser.

josueh04/product-video-skills

Turn a product's real frontend code into 1:1 rebuild specs for a video, one read-only subagent per screen, each returning static HTML, CSS with every variable resolved to its literal value and cited (role/path:line@sha), every state, transitions with exact durations and easings, icons from the code's own icon sets, and the exact i18n strings; plus resolve_tokens.py to write the product's design tokens to kit/tokens.css. Use it whenever a screen of the product has to appear in a video, when writing or fixing video/src/app.css or the template markup, when someone asks for exact sizes, colors, fonts, paddings, animations or icons of a screen, when a rebuilt screen "looks off" next to the real app, and when the design tokens or theme of a product need extracting. Framework adapters cover Angular with PrimeNG (proven), React, Vue, Tailwind and plain HTML (unproven).

josueh04/product-video-skills

Say where this session stands in the Product Video Skills workbench (setup state, which product and video the current folder belongs to, the stage of every video) and the exact next command to type. Also answers "how do I..." questions about the workbench from its docs.

josueh04/product-video-skills

Start a new video of the current product - create videos/<video>/, write BRIEF.md, the feature coverage matrix (COVERAGE.md) and the claims sheet (CLAIMS.md), propose chapters, then stop for the reviewer's sign-off. Never builds. Run only when the user types /video-new.

josueh04/product-video-skills

Turn a batch of reviewer feedback on the product's videos into one table per video, fix every video that got notes in parallel (one subagent each) while keeping approved parts, re-run QA and parity, bump versions and deliver. Run only when the user types /video-review.

josueh04/product-video-skills

Check this machine and install the pinned video toolchain of the Product Video Skills workbench (HyperFrames CLI, its rendering Chrome and its agent skills from the same release, the Python environment, the speech model for QA), then run the self-check. Safe to run again. `/video-setup check` only reports.

相关技能