Communitygithub.com

josueh04/product-video-skills

鎖定產品的原始碼來源,確認已釘選的提交版本確實用於生產環境,並將影片簡報中的每個畫面對應到其路由、元件、i18n 字串與狀態,最終寫入該影片的 SOURCES.md。

product-video-skills 是什麼?

此技能「Source Recon」旨在解決一個常見問題:影片中呈現的每個像素與每句話,都需與正確的程式碼版本核對。它透過一套嚴謹的流程,確保程式碼來源的精確性與可追溯性。首先,它會以唯讀方式從指定的 Git 儲存庫或本地路徑擷取原始碼,並鎖定其提交版本(commit hash)至 `sources.lock` 檔案,避免後續引用時因程式碼變動而失效。接著,它會透過部署標籤、工作流程設定或團隊確認等方式,交叉驗證鎖定的版本是否確實為生產環境中運行的版本,以排除「分支名稱不等於生產版本」的陷阱。然後,技能會為影片簡報中的每個畫面啟動獨立的探索子代理(Explore subagent),在鎖定的唯讀原始碼中找出其對應的路由、元件檔案、i18n 字串、狀態邏輯以及使用的圖示與素材,並透過引用格式(`<role>/<path>:<line>@<short sha>`)精確標記來源位置。最後,它會將所有發現整理成結構化的 `SOURCES.md` 檔案,包含來源鎖定資訊、生產環境確認狀態、表格化的畫面對應關係,以及無法在程式碼中找到的「無碼參考」清單。當程式碼變更時,它也能透過 `changed_since.py` 工具比對鎖定版本與最新版本的差異,迅速找出受影響的影片,並引導用戶進行更新,確保所有影片素材與生產程式碼始終同步。此技能主要用於 Claude Code 等支援技能(skill)的 AI 代理平台。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

原始碼偵查 (Source Recon)

影片中的每個像素與每句話稍後都需要與程式碼核對,因此程式碼必須是正確的程式碼。在這些技能誕生的製作環境中,主要的前端 checkout 曾落後生產環境約兩個月,而當時的當前程式碼卻放在另一個沒人關注的 worktree 裡長達三天。在有人發現之前,同一個影片的三個版本都是從舊程式碼重建的。這個技能的存在就是為了讓這種事不再發生:先鎖定原始碼,證明它們是生產環境版本,然後將畫面對應到檔案。

以唯讀方式工作。 你只能讀取程式碼;永遠不要編輯、check out、fetch 或在使用者的儲存庫中建立 worktree。他們的工作樹可能包含未提交的工作,而 checkout 或 fetch 會改變他們未要求你改變的狀態。

1. 鎖定原始碼

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/source-recon/scripts/fetch_sources.py" <product_dir>

它會讀取 product.yaml 中的 sources:,並根據角色 (role) 執行:

  • url::將分支 shallow-clone 到 sources/.git-cache/<role>.git 並匯出。
  • path:(指向 Git 儲存庫):使用 git archive 匯出 <branch> 和 origin/<branch> 中較新的那個。當本地分支落後或分歧、origin 的 refs 超過一週未 fetch、或同一儲存庫的其他 worktree 比匯出版本更新時,它會發出警告。
  • path:(不是 Git 儲存庫):直接複製並根據其檔案 hash 鎖定("pinned": false,因此對它的引用可能會無預警失效;建議優先使用 Git 來源)。

匯出的內容會以唯讀方式存放在 sources/<role>/,而 sources.lock 會記錄此次提交。若某個已鎖定的角色在磁碟上遺失(例如產品儲存庫的全新 clone),它會在其鎖定的提交還原,因此引用能持續指向相同的行數。請閱讀它印出的每一行 note:,並在繼續之前處理它們:每一條 note 都代表一個可能導致匯出版本非生產環境的原因。

所有下游的引用都會使用 <role>/<path>:<line>@<short sha> 格式,其中路徑相對於儲存庫根目錄(因此 sources/<role>/<path> 存在),sha 是鎖定的那個。

2. 證明它是生產環境版本

分支名稱不是證明。生產環境版本是部署管線最後一次構建的內容。在對應任何畫面之前,需依以下優先順序確定哪個提交是線上版本:

  1. 發行紀錄:發行標籤、部署日誌、部署儲存庫中的「last deployed sha」檔案。
  2. 部署管線設定:它從哪個分支構建,以及其構建參數(內建於構建中的環境變數可能改變品牌或隱藏功能)。
  3. 團隊確認已部署的最新分支,並與 git worktree list、分支日期和 merge-base 進行比對。

閱讀 references/freshness.md 以了解確切指令與陷阱(過時的遠端 refs、功能開關、改變渲染結果的構建參數)。如果你無法確認生產環境提交,請在 SOURCES.md 的開頭說明(「production commit unconfirmed」),並向用戶提出一個封閉式問題並建議答案,例如:「將 origin/develop(最新,包含主線)匯出為生產環境版本?建議:是,因為這是部署工作流程構建的內容。」

當用戶確認了不同的分支,請修改 product.yaml 中的 branch: 並執行 fetch_sources.py <product_dir> --refresh --role <role>(如果影片已引用此來源,請先執行 changed_since.py,見第 6 節)。

3. 對應每個畫面

從影片的 BRIEF.md(章節)和 COVERAGE.md 取得畫面與狀態。為每個畫面(或共享元件的少量畫面組)啟動一個唯讀的探索子代理 (Explore subagent),並平行執行。給予每個代理 references/recon-prompt.md 中的提示,並指向 sources/<role>/(鎖定的匯出版本,絕不是用戶的 checkout),以確保它回傳的每個行號都與鎖定版本相符。

每個子代理會回傳(附上引用):路由、頁面與子元件(模板、邏輯、樣式檔案)、影片語言中的 i18n 鍵與確切字串、決定渲染內容的狀態(預設值、標誌、功能門控、空狀態、權限檢查)、正在使用的圖示集與素材,以及任何看起來未發布、受門控或受限制的內容。

然後,親自對照你擁有的任何參考資料(錄影、復原的畫面截圖、文件),抽查每個畫面的兩三組字串。字串不同代表匯出版本非生產環境,或畫面被隱藏在功能開關之後;在撰寫 SOURCES.md 之前解決此問題。

4. 撰寫 SOURCES.md

每個影片一個檔案,位於 videos/<video>/SOURCES.md:

# Sources: <video>

Locked: frontend main@1a2b3c4 (2026-01-12), backend main@5d6e7f8 (2026-01-10)
Production: confirmed by <release tag v4.2.0 | deploy workflow builds main | team confirmation>

| screen | route | components | citation |
|---|---|---|---|
| Board, empty | /board | BoardPage > TaskList > EmptyState | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 |

## Board, empty
- Strings: `board.empty.title` "Nothing planned yet" (frontend/src/i18n/en.json:88@1a2b3c4)
- State: renders when `tasks.length === 0` (frontend/src/pages/board/TaskList.tsx:41@1a2b3c4)
- Icons: lucide `calendar-plus` (frontend/src/pages/board/EmptyState.tsx:9@1a2b3c4)
- Flags or gates: none found
- Not found: <anything the brief needs that the code does not have>

## No-code references
<what exists for each screen without code, see section 5>

沒有引用的畫面不應放入影片中。將其列在「Not found」下並告知用戶;發明一個不存在的畫面是審查者最無法容忍的錯誤,因為這會展示一個不存在的產品。

5. 列出無碼參考資料

對於程式碼無法呈現的畫面(第三方 UI、執行時期輸出、不在儲存庫中的後端,或完全沒有前端程式碼),列出可用的資料,優先順序如下:references/ 中已分析的螢幕錄影、可從過去對話記錄中復原的畫面截圖、與生產環境一樣建置的本機應用程式實例、公開文件與截圖。請勿在此自行擷取畫面;那是 ui-reference-capture 的工作。永遠不要依賴審查者的個人瀏覽器。

6. 當程式碼變更時

"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/source-recon/scripts/changed_since.py" <product_dir> [--offline]

它會比對每個鎖定的提交與目前分支的最新版本,並列出所有引用了變更檔案的影片(以及組件檔案)的 SOURCES.md、TRUTH.md、規格或 video/src/,並標記那些行數已變更的引用。它不會移動任何東西。在任何 --refresh 之前執行此工具:它比較的是鎖定版本與最新版本,而 refresh 會使它們相等,因此之後變更的列表就會消失(此時腳本會印出提示訊息)。向用戶顯示該列表,然後,如果他們想要新的程式碼,請執行 fetch_sources.py --refresh、為受影響的畫面重新執行 ui-spec-from-code,以及為受影響的行數重新執行 product-truth。沒有引用到變更內容的影片則保持不變。

規則與原因

  • 讀取匯出版本,引用鎖定版本。 來自不同 checkout 的行號會在下次 refresh 後默默指向錯誤的程式碼。
  • 永遠不要印出在程式碼中發現的機密。 前端程式碼經常包含金鑰和 token。僅回報檔案與行號,並將其視為安全問題告知用戶。
  • 未發布、受門控或受限制的功能也是事實。 在 SOURCES.md 中標記它們(gate: <flag>,restricted: <who sees it>)。product-truth 會決定影片是否可以展示它們,通常需要審查者的同意。
  • 避免真實資料。 儲存庫中的測試用固定資料或種子檔案可能包含真實客戶名稱。引用它們的結構,而不是它們的值。

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

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.

相關技能