Communitygithub.com

josueh04/产品视频真实性验证

为视频旁白中的每一句和每个画面,从锁定的源代码或文档中生成引用,标记UI可见性与后端逻辑,剔除或重写无依据的内容,并输出 TRUTH.md 文件,供 truth_check.py 验证。

产品视频真实性验证 是什么?

该技能专为产品视频制作设计,确保视频中的每一句旁白和每一个画面都能在源代码或官方文档中找到确凿依据。它通过将叙述拆解为可验证的声明,并行启动只读子代理搜索代码库和文档,对每个声明进行可见性分类(UI、后端、文档或设计素材)和结论判定(已背书、已批准、需重写、需删除等)。最终生成结构化的 TRUTH.md 表格,并通过 truth_check.py 严格检查任何缺失、陈旧或无源的条目。此技能适用于任何脚本或叙述编辑阶段、语音生成前、构建前,以及当有人询问“我们能这么说吗?”、“这是真的吗?”、“产品真的能做X吗?”等情况。它支持 Claude Code 等 AI 代理平台,依赖 source-recon 对源码进行锁定,确保引用的行号和提交哈希准确无误。使用它可显著降低视频中虚假或夸大陈述的风险,避免因后期返工而浪费版本。

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

在你喜欢的 AI 中提问

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

文档

产品真相

一个展示了产品做不到的事情的产品视频,比没有视频更糟糕。在制作这些技能的生产流程中,代价最高的时刻都是真实性失败:一个手工制作的徽章,尺寸和产品名称都是错的;一个被叙述为“等待通话结果”的工作流,而产品只通过一个单独的触发器返回结果;一个被重贴标签为已确认预订的测试电话,但没人做端到端验证;一份公司文档的标题与团队已同意的定位相矛盾。每一个问题都是在后期由评审者发现,并导致了一个版本的返工。

此技能让检查变得明确和机械化:每一句旁白和每一个画面都在 TRUTH.md 中有一个对应的行和源引用,而 truth_check.py 会拒绝任何缺少、过时或无依据的行。

输入

  • videos/<video>/audio/lines.tsv(叙述文本,每句话一个行 ID)
  • videos/<video>/SOURCES.md(来自 source-recon:画面及其对应代码)
  • videos/<video>/BRIEF.md、COVERAGE.md、CLAIMS.md(视频必须解释的内容、定位、应避免的措辞、需要批准的声明)
  • product.yaml:positioning、never_say、names(规范名称到遗留字符串的映射)、banned_terms
  • sources/<role>/ 和 sources.lock(由 source-recon 锁定;如果缺失,先运行 source-recon,因为引用必须指向锁定的提交)

1. 列出声明

将 lines.tsv 中的每一行拆解成其做出的声明。例如,“Acme Tasks 读取你的日历并将过期任务移到明天”包含两个声明:它读取日历,以及它移动过期任务。此外,根据 SOURCES.md 和章节,为每个画面和屏幕上的操作添加一个声明(例如,“点击‘计划我的一天’会打开带有三个建议的计划器”)。

写下这些声明所引发的问题,措辞要能让代码回答:是什么触发了这个?存储了什么?有哪些选项?用户在哪里看到什么?哪些操作仅发生在服务器上?

2. 从代码和文档中回答它们

并行启动只读子代理,每个产品领域一个(前端行为、每个后端、文档),使用 references/product-facts-prompt.md 中的提示。将它们指向 sources/<role>/,切勿指向用户的检出目录,这样它们的行号才能与锁定的版本一致。它们只能从代码或文档中回答,引用每个事实,并在无法找到时说“未找到”。

3. 对每个声明进行分类

可见性含义视频可以
ui由前端渲染;引用模板或 i18n 行展示它并叙述它
backend在服务器上为真,屏幕上没有任何显示叙述它,但绝不为它绘制 UI
docs只有文档这么说引用文档 URL 叙述它;同时在可能时检查代码是否同意
mock一个设计素材,非产品 UI(如电话屏幕、结束卡、生成文本)展示它,但在 BRIEF 中标记为设计素材
结论含义
backed来源明确支持此说法
approved需要签核(受限、未发布、或 CLAIMS.md 列出的声明),且评审者在 CLAIMS.md 中已批准
needs-approval真实,但受限、被门控、未发布或在 CLAIMS.md 中列出;等待评审者
rewrite部分真实;你在备注中提出有依据的措辞
cut不真实,或未找到来源
unbacked尚未检查
mock仅适用于可见性为 mock 的情况

只有 backed 和 approved 能通过叙述行的检查。受限功能(仅对某些角色、计划或内部团队可见)、功能开关后的功能或未合并分支上的功能,在评审者在 CLAIMS.md 中确认同意之前,均为 needs-approval,且 BRIEF 中需注明其受限状态。这在源生产流程中确实发生过:一个只有内部员工才能看到的功能应评审者要求被展示,并做了相应标记。

4. 修复不成立的部分

  • 重写 部分真实的句子,使其成为来源支持的最强版本。保留作者想要表达的意思;将机制改为真实的机制。
  • 删除 没有来源的内容。不要将其模糊化;模糊的声明仍然是声明。
  • 绝不让标签漂移。 一个标记为“示例性”的设计素材,在后续美观修改时不能丢失该标签,除非重新检查无标签版本所做出的声明。
  • 定位优先于文档。 如果一份演示文稿或 PRD 说了 never_say 或 CLAIMS.md 禁止的内容,规则优先,句子必须更改。
  • 仅使用当前名称。 使用 product.yaml names 中的规范名称,即使实时 UI 或代码仍显示遗留字符串。用 grep 搜索 lines.tsv、规格和模板中每一个遗留字符串和每条 banned_terms 条目(竞争对手、团队避免在屏幕上显示的第三方供应商、真实客户),并修复每个命中。

5. 当请求与产品冲突时

当简报或评审者要求代码不支持的东西时,不要构建假的,也不要默默放弃。提出一个包含选项和建议默认值的封闭式问题,每轮最多保留三个这样的问题,因为开放式的否决清单通常无人回应,而沉默会变成无人做出的决定。“只做真实的”模式:

简报显示 Acme Tasks 自己预订了会议室。但代码仅创建任务并链接房间的日历 (frontend/src/rooms/LinkRoom.tsx:22@1a2b3c4);实际预订发生在日历应用中。选哪个?

  1. 只做真实的(推荐): 显示链接步骤并说“链接房间的日历”。
  2. 将日历应用的预订屏幕作为设计素材展示(已标记),并叙述为日历的步骤。
  3. 放弃这个节拍。

将答案记录在 CLAIMS.md 中,并据此设置结论。

6. 编写 TRUTH.md

# 真相:<video>

锁定版本:前端 main@1a2b3c4,后端 main@5d6e7f8。检查日期:2026-01-12。

| id | 句子 | 来源 | 可见性 | 结论 | 备注 |
|---|---|---|---|---|---|
| N1 | Acme Tasks 根据你的日历计划你的一天。 | frontend/src/planner/plan.ts:31@1a2b3c4; https://docs.example.com/planner | ui | backed | |
| N2 | 过期任务在午夜移到明天。 | backend/jobs/rollover.py:12-30@5d6e7f8 | backend | backed | 不在屏幕上显示 |
| screen:board | 包含三个任务的面板,其中一个过期 | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 | ui | backed | |
| screen:call | 与客户的电话通话 | (设计素材) | mock | mock | 在 BRIEF 中标记 |

## 未解决问题
1. <带有推荐答案的封闭式问题>

每个 lines.tsv 的行 ID 对应一行,句子需要精确复制(检查时会比较它们,因此在真相验证通过后编辑一行会导致失败,直到重新验证)。每个画面对应一行,ID 为 screen:<name>,需与 SOURCES.md 匹配。多个引用放在一个单元格内,以分号分隔。

7. 检查它

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/product-truth/scripts/truth_check.py" <video_dir>

检查会在以下情况失败:一个行没有对应的 TRUTH.md 行;句子已更改;叙述行的结论不是 backed 或 approved;引用的角色未锁定;引用的 SHA 与锁定的版本不一致(代码已移动,需重新验证);引用的文件不在导出中;或引用的行号超出文件末尾。修复每个失败;不要编辑检查脚本。

向用户报告:多少行和画面已背书,你重写和删除了哪些(带原因),哪些在等待批准,以及未解决的问题。

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

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

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.

相关技能