Communitygithub.com

josueh04/product-video-skills

启动新产品视频制作流程:创建 videos/<video>/ 目录,编写 BRIEF.md、功能覆盖矩阵 (COVERAGE.md) 和声明清单 (CLAIMS.md),提议章节,然后等待审核人员签署。不执行构建。仅在用户输入 /video-new 时运行。

product-video-skills 是什么?

该技能是一个用于 AI 编码代理(如 Claude Code)的严格引导式视频创建工具。其核心目的是通过在构建任何内容之前,让审核人员书面签署两个关键文档(功能覆盖矩阵和声明清单),来消除代价高昂的返工循环。它首先提示用户定义视频目标(受众、核心信息、时长和关键功能),然后自动生成一个带有章节提案的 BRIEF.md、一个跟踪每个功能是否已在屏幕上展示的 COVERAGE.md,以及一个包含定位声明和需要批准声明的 CLAIMS.md。该技能会强制进行审核签核,并且在获得适当签署之前,严格禁止执行任何构建工作。此方法源自一个真实的生产环境,在该环境中,未经记录的变更导致了大量版本迭代。

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

在你喜欢的 AI 中提问

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

文档

/video-new

在开始构建任何内容之前,先写下视频必须解释的内容以及可以声明的信息,并让审核人员签署这两项。然后停止。

为什么存在这个技能:在开发这些技能的生产环境中,有9次版本迭代(共26次)是因为视频没有解释审核人员关心的某个功能。没有人预先记录这些功能,因此每个功能都在审核中才暴露出来,导致一次完整的渲染和 QA 周期,然后还必须手动应用到每一个其他视频上。定位和声明同样导致了另外3次版本迭代。预先签署的两份文档比这些轮次中的任何一次都要便宜。

开始之前

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"

找到产品:当前目录上方最近的包含 product.yaml 的文件夹。如果没有,告知用户先运行 /product-new(你不能代劳运行:它是由用户调用的)。读取 product.yaml、kit/RULES.md 以及 videos/ 中任何同级视频的 BRIEF:同级视频的覆盖矩阵和声明清单是最佳的起始点,并且不同视频之间的演员表必须保持一致。

视频 ID 来自参数(小写、数字、短横线)。如果 videos/<video>/ 已存在,则停止:现有视频应通过 /video-review 推进,绝不要重新开始。

1. 询问视频用途

一条消息,最多四个问题,每个都附带建议的默认值:

  • 谁观看以及在哪里发布(宣传片、简短产品演示、文档页面、新手引导、落地页循环)。
  • 观看者之后必须相信或能够做什么(一句话)。
  • 大致时长(默认值:宣传片 90 秒,演示 30 秒,文档 120 秒,教程 240 秒,循环 15 秒)。演示是宣传片的精简版,只聚焦一到两个功能:相同的开场、结束画面和结尾徽标,更少的章节。当审核人员说“快速演示”或要求时长低于 45 秒时选择它。
  • 审核人员认为哪些功能最重要。要求按名称提供,并询问其中哪些必须演示工作状态而不仅仅是提及。

2. 创建文件夹

"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/video-new/scripts/new_video.py" <product_dir> <video> \
  --format <format> [--title "<title>"] [--duration <s>]

它会复制 _template/video,填充 BRIEF 的 frontmatter(标题、视频、格式、时长、语言和来自 product.yaml 的审核人员,版本 1)并将两个签名都留空。它会拒绝重复的 ID。

3. 编写三份文档

在编写之前,请阅读 references/sheets.md 以了解每份文档的格式和已完成的示例行。

  • BRIEF.md:意图(引用用户自己的话)、受众、建议的章节、备注(包含视频将使用的所有虚构姓名和数字,来自产品演员表,未经询问不得新建),以及一个空的 v1 变更日志条目。
  • COVERAGE.md:每个功能一行,包含“必须在屏幕上解释?是/否”、解释该功能的章节以及证明(观看者看到的内容)。一个仅在结束画面上命名的功能未被覆盖:这正是导致最多版本迭代的差距。包括可配置的部分(设置、触发器(包括计划的)、转接、后续操作),因为这些正是审核人员在事后反复要求的功能。
  • CLAIMS.md:定位行(来自 product.yaml,绝不要来自营销文档)、要避免的短语(never_say 加上用户添加的任何内容)、每个需要批准的叙述声明、批准的口号,以及标准产品名称与其旧版字符串的对照。

对照你在 sources/ 和文档中看到的内容检查每个声明和功能。如果产品没有实现用户要求的功能,请用一个封闭式问题和推荐选项来说明(“仅展示已存在的”通常是正确的默认选项)。不要将无法通过代码验证的功能写入矩阵。

4. 提议章节

将章节表格添加到 BRIEF.md 中。每个章节一个想法,每个章节一个框架,每个“必须解释”的功能都映射到一个章节。以上下文开场(产品名称和一行说明它是什么),绝不要直接从 UI 中间开始。默认情况下以 1 倍缩放显示整个页面;深度缩放曾两次在原始制作中被否决。以广度(产品还能做什么)结束,然后是结尾徽标。

5. 停止并请求签名

向用户展示以下内容,一条消息内包含:

  1. 覆盖矩阵(“是”行)和章节表格。
  2. 定位行、需要批准的声明和建议的口号。
  3. 最多三个封闭式决策,每个附带默认值(例如口号、演员表名称、省略某个功能)。说明沉默的含义:即接受默认值。

然后请审核人员签署。审核人员要么亲自将其姓名写入 BRIEF.md 中的 coverage_signed_by 和 claims_signed_by,要么以其自己的方式告知你以其名义签署,然后你运行:

"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/video-new/scripts/sign.py" <video_dir> \
  --coverage "<reviewer name>" --claims "<reviewer name>"

绝不要主动签署,绝不要因为文档“看起来完整”就签署,绝不要使用审核人员未提供的姓名签署。签名是审核人员对矩阵将作为其评判视频标准的声明。sign.py 拒绝处理空的矩阵或缺少定位行的情况;不带任何标志时,它只显示状态。

即使在同一消息中用户签署了,也不要在此处构建、渲染、录制旁白或派遣子代理。构建由 /video-build 负责,由用户输入。这个分离能防止代理在未签署的 BRIEF 上启动昂贵的构建。

报告

项目值
视频videos/<video>/,格式,目标时长
覆盖需要在屏幕上解释的 N 个功能,仅列出的 M 个,章节
声明定位,等待批准的声明
决策最多三个封闭式问题及其默认值
签名未签署(或由谁签署)

下一步,签署后:/video-build <video>。

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

Coordinate the build of one or more signed videos of the current product with subagents (source recon, product truth, UI specs, voice, one builder per video), re-run QA itself, then deliver. A light coordinator that never builds itself. Run only when the user types /video-build.

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.

相关技能