Communitygithub.com

josueh04/product-video-skills

检查机器、安装 Product Video Skills 工作台的固定视频工具链(HyperFrames CLI、其渲染 Chrome 和来自同一版本的 Agent 技能、Python 环境、用于 QA 的语音模型),然后运行自检。可以安全重复运行。`/video-setup check` 仅报告,不执行安装。

product-video-skills 是什么?

该技能旨在将 Product Video Skills (PVS) 工作台从全新克隆状态一键设置为可通过测试的状态(输出 `passed N, failed 0`)。它通过 `setup.sh` 脚本自动检查系统依赖(Node.js 22+、Python 3.9+、ffmpeg、Git)和工具链完整性,并安装缺失组件,包括固定版本的 HyperFrames CLI(约 128 MB)、渲染用的 Chrome 浏览器(约 195 MB,可缓存)、同一版本的 Agent 技能、PyTorch 等 Python 包(约 339 MB)以及 Whisper `small.en` 语音模型(484 MB)。安装过程完全幂等,可以安全重复运行;支持 Claude Code、Cursor 等 AI 代理平台。用户只需同意一次,即可自动处理所有故障修复,无需手动干预。

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

在你喜欢的 AI 中提问

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

文档

/video-setup

将工作台从全新克隆一步设置为 passed N, failed 0。setup.sh 完成实际工作;你的任务是解释它、获得用户同意、运行它,并将每个 FAIL 行转化为对应的修复方案。

首先找到工作台路径(在工作台目录或产品文件夹内均可):

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

使用用户的母语与其沟通。保持简洁:他们需要的是能正常工作的环境,而不是产品介绍。

使用参数 check

运行 bash "$PVS_HOME/setup.sh" --check 并显示结果。此操作不会安装任何内容、不下载任何文件、也不写入任何数据。对于每个 FAIL 行,给出其修复方法(行末尾指明了修复方式)。到此为止。

否则

1. 报告机器状态

首先运行 bash "$PVS_HOME/setup.sh" --check。它会为每个检查项输出一行结果:ok(通过)、warn(警告)或 FAIL(失败),并附上精确的修复方法。

  • 如果 Machine(机器)部分下的任何行失败(如 node 22+、python 3.9+、ffmpeg、git),则无法继续安装。将行中给出的修复方法(例如 brew install ffmpeg)告知用户,请他们在自己的终端中运行,然后重新执行检查。安装系统软件包是用户自己的决定,除非用户主动要求,否则不要自行运行 brew 或 apt。
  • Claude Code 上的 warn 仅仅是提示性信息。
  • Toolchain(工具链)部分下的 FAIL 行是安装脚本需要修复的部分。这在首次运行时属于正常现象。

2. 说明将要下载的内容,并征询一次同意

用一条简短的列表告知用户,只列出检查报告中缺失的部分:

组件大小安装位置
固定版本的 HyperFrames CLI 及其依赖约 128 MBnode_modules/
HyperFrames 用于渲染的 Chrome 构建约 195 MB(已缓存则跳过)HyperFrames 缓存目录
来自同一发布标签的 HyperFrames Agent 技能几 MBvendor/hyperframes/skills/
Python 包(主要是用于语音转文字的 torch)约 339 MB.venv/
QA 使用的 Whisper small.en 语音模型484 MB~/.cache/whisper/

只问一个封闭性问题:“现在安装这些组件吗?(是 / 否)”。安装应通过首次 /video-setup 一步完成,不要分成多次确认。

3. 执行安装

如果用户回答“是”,则运行 bash "$PVS_HOME/setup.sh" --yes(--yes 是用户已给出的回答)。首次运行需要几分钟时间,所有组件缓存后只需几秒;设置超时时间至少为 10 分钟。该命令是幂等的:重复运行只会重新安装缺失的部分。

4. 处理每个 FAIL

每个 FAIL 都标明了其修复方法。常见情况如下:

FAIL处理方法
npm install failed网络或注册表问题。显示它引用的日志文件的最后几行,然后重新运行安装脚本
hyperframes browser ensure failed在工作台目录运行 npx hyperframes browser ensure --force,然后重新运行安装脚本
could not clone heygen-com/hyperframes网络或 GitHub 访问问题。检查 git ls-remote https://github.com/heygen-com/hyperframes,然后重新运行安装脚本
python3 -m venv failed在 Debian 或 Ubuntu 上:sudo apt install python3-venv(由用户运行)
pip install -r requirements.txt failed显示日志尾部。比固定版本更新的 Python 可能需要更新的 wheel 包;请报告这一问题,而不是修改固定版本
hyperframes doctor: ...该行指明了失败的检查项及其修复方法。版本号、Docker 以及可选的本地语音和音乐检查会被故意忽略
tests/run.sh: passed N, failed M运行 bash "$PVS_HOME/tests/run.sh" 并显示失败的测试及其输出

绝对不要通过运行 hyperframes upgrade 或 hyperframes skills update 来“修复”FAIL。工作台固定了单一 HyperFrames 版本,并从同一标签获取技能,因为不同版本 CLI 与技能对合成合约的理解不一致。版本变更需要通过 tests/run.sh 的拉取请求来实现。守卫钩子也会阻止这两个命令。

5. 语音密钥

安装脚本会从 .env.example 创建 .env,并告知你 ElevenLabs 密钥是否已设置,但不会输出密钥本身。如果密钥为空,请告知用户:

  • 在自己的编辑器中打开 .env(位于工作台文件夹内),将密钥粘贴到 ELEVENLABS_API_KEY= 之后。切勿在聊天中操作:聊天内容会被存储到对话记录中。如果用户仍然在此处粘贴了密钥,请告知他们立即轮换密钥。
  • 如果没有密钥,产品 product.yaml 中的 voice.provider: say 会使用 MacOS 自带的免费语音,足以用于草稿和测试。

绝对不要自行打开、读取或打印 .env 文件。 设置和守卫钩子会禁止这些操作,脚本会通过 lib/pvs.py 自行加载密钥。

6. 结束确认

确认输出最后几行为 passed N, failed 0 和 Setup done。然后用一行给出下一步操作:/product-new <slug> 来创建产品,或 /video-ask 查看当前状态。

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

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.

相关技能