Communitygithub.com

josueh04/product-video-skills

與使用者訪談產品的詳細資訊,建立包含獨立 Git 記錄的 products/<slug>/ 目錄,填入 product.yaml,連結技能,擷取原始碼並建置套件。僅在使用者輸入 /product-new 時執行。

product-video-skills 是什麼?

這項技能會引導使用者進行結構化訪談,以收集產品的詳細資訊,例如名稱、定位、原始碼儲存庫、品牌資產、虛構角色以及禁止使用的詞彙。接著,它會在「工作檯」(workbench)中建立一個新的產品目錄(products/<slug>/),初始化 Git 記錄,並根據訪談內容填入 product.yaml 設定檔。此技能會自動連結必要的 CLI 技能,並依序呼叫 `source-recon`(擷取原始碼)和 `product-kit`(擷取代碼、字型、圖示和品牌元素)這兩個以模型驅動的技能。它主要設計用於 Claude Code 等 AI 編碼代理程式,透過標準化流程來避免後續發生代價高昂的錯誤,例如角色姓名不一致或已過時的程式碼基底。此技能包含嚴格的防護措施,絕不會寫入產品目錄,也不會要求或儲存認證資訊。

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

在你喜歡的 AI 中提問

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

說明文件

/product-new

在工作檯中建立一個產品資料夾:進行簡短訪談,然後執行一個腳本寫入資料夾,接著由兩個模型調用的技能來填寫內容(source-recon 負責擷取程式碼,product-kit 負責擷取標誌、字型、圖示、商標、角色和名稱)。

為什麼要先進行訪談?在這些技能所源自的實際製作流程中,角色、產品名稱和定位都是逐一審查才定案的,而每一次審查都迫使我們重新渲染。在這裡收集到的每一個答案,都代表未來不會再發生的審查回合。

開始之前

從這個技能的實際路徑解析工作檯位置(它能從工作檯和產品資料夾中執行):

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

從參數中檢查 slug:長度為 2 到 40 個字元,僅包含小寫字母、數字或連字號,且以字母開頭。如果 $PVS_HOME/products/<slug> 已存在,則停止並告知使用者:絕不覆寫產品,因為它有自己的記錄和可能已簽署的摘要。如果使用者傳入了 --from examples/acme(或其他資料夾),則訪談只需詢問與該範例不同之處。

在連接任何儲存庫之前,先向使用者說明一次:Claude 會讀取產品的程式碼,這表示程式碼會作為上下文發送給模型。使用者應確保其公司允許這樣做。

1. 訪談

以訊息為單位,分批提出問題(每則訊息兩到三個問題),並使用使用者的語言。盡可能為任何你能推斷的項目提供預設值,以便使用者大多只需確認即可。完整的問題清單及每個問題背後的動機,請參閱 references/interview.md;請在提問前先閱讀。

  1. 產品:名稱、用一句話說明它是什麼(定位)、目標使用者是誰。
  2. 禁語:團隊拒絕使用的描述,即使公司文件中有用到也不行。
  3. 原始碼:針對每個原始碼(前端、後端、設計、文件),提供 Git URL 或本機路徑、正式環境使用的分支、應用程式目錄及框架(angular-primeng、react、vue、svelte、html、other)。詢問哪個分支是真正部署的:在原始製作流程中,一個過時的簽出就花費了實際的時間。
  4. 文件:URL、儲存庫路徑或 mcp:<name>(唯讀)。
  5. 品牌:僅當品牌資產(標誌和字型檔案)不在前端時才詢問。否則 product-kit 會自行找到。
  6. 虛構角色:提議一家公司以及兩到三位人員,需包含全名、555 開頭的電話號碼以及使用 example/.test 網域的電子郵件。用一個封閉式問題提供否決權,並以你的提案作為預設值。審查者對平淡或真實感過強的名字反應強烈,而一個在不同影片中姓氏會改變的角色,是一個會出貨的 Bug。
  7. 名稱與發音:官方名稱、現有 UI 中可能仍會顯示的舊版字串,以及品牌詞彙的發音方式。
  8. 禁止詞彙:競爭對手、供應商、真實客戶,以及任何絕對不能出現或被聽到的內容。
  9. 審查者:負責簽署每部影片的覆蓋率矩陣和索賠表的人員。

切勿要求提供 token、密碼或 SSH 金鑰,也絕不要提議儲存這些資訊。原始碼是使用機器上已有的 Git 存取權限來擷取的。如果 URL 中包含憑證(https://user:token@...),請要求使用者移除它們;腳本無論如何都會拒絕這類 URL。

2. 寫入資料夾

將答案寫入一個形狀類似 product.yaml 的暫存檔案(任何子集均可;請參閱 references/answers.example.json),且檔案必須位於儲存庫外部,然後執行:

"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/product-new/scripts/new_product.py" <slug> \
  --answers <scratch>/answers.json [--from examples/acme]

該腳本會複製 _template/product,然後將 --from 資料夾的內容覆蓋上去(因此,如果範例缺少某個檔案,例如 kit/RULES.md,仍然會取得範本的版本),將答案逐行合併到 product.yaml 中(範本的註解是使用者的文件,因此會保留),在範本沒有 CLAUDE.md 和 .gitignore 時寫入這兩個檔案,執行 scripts/link-skills.sh 以便 cd products/<slug> && claude 可以看到相同的技能,並進行第一次 git 提交。該腳本會拒絕處理已存在的 slug、包含憑證的 URL,以及明顯非虛構的角色電子郵件或電話。如果執行失敗,請修正它指定的答案並重新執行;不要手動建立資料夾。

如果腳本輸出「still to fill in product.yaml」,表示訪談未涵蓋到範本中的佔位符。詢問這些佔位符的內容,或告知使用者哪些項目尚未填寫。

3. 填寫資料

透過技能工具(Skill tool)按下列順序呼叫這些由模型調用的技能:

  1. source-recon:將每個原始碼擷取到 products/<slug>/sources/ 中,並將其固定記錄在 sources.lock 中。如果因存取問題導致擷取失敗,請報告確切的 git 錯誤並停止:使用者應在他們的機器上修復存取權限,絕不應由你提供憑證。
  2. product-kit:擷取 kit/tokens.css、字型、圖示、標誌,並將角色、名稱和發音寫入 kit 和 kit/RULES.md 中。

這兩項技能都只會在產品資料夾內寫入內容。切勿編輯 sources/ 中的任何內容。

4. 報告

一個簡短表格,接著是下一個指令:

項目值
資料夾products/<slug>/(git:首次提交或原因)
原始碼角色、分支、來自 sources.lock 的提交
套件product-kit 擷取的內容,以及它找不到的內容
角色已確定的角色名稱,供最終否決
待辦事項product.yaml 中仍為佔位符的項目,以及任何未驗證的內容

下一步:cd products/<slug> && claude,然後 /video-new <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

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.

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.

相關技能