Communitygithub.com

josueh04/product-video-skills

プロダクトの実際のフロントエンドコードを、1:1再現のビデオ仕様に変換します。画面ごとに読み取り専用のサブエージェントが、すべての変数をリテラル値に解決し、出典を明記した静的HTML/CSSを返します。resolve_tokens.pyでデザイントークンを抽出し、正確なサイズ、色、フォント、パディング、アニメーション、アイコンを提供します。Angular with PrimeNG(実績あり)、React、Vue、Tailwind、プレーンHTMLに対応。

product-video-skills とは?

このスキルは、プロダクトの実際のフロントエンドコードから、ビデオ制作に必要なUI仕様を1:1で再現するための強力なツールです。各画面に対して読み取り専用のサブエージェントを並列起動し、フレームワーク固有のアダプタ(Angular/PrimeNG実績あり、React、Vue、Tailwind、プレーンHTMLは未検証)に従って、すべてのCSS変数、SCSS変数、Tailwindテーマをリテラル値に解決します。すべての値は出典(ロール/パス:行@sha)付きで提供され、未定義の変数はフラグが立てられるため、推測による不正確さが排除されます。さらに、`kit/tokens.css`に解決済みのトークンを書き出す`resolve_tokens.py`スクリプト、製品独自のアイコンセットからSVGを抽出するアイコン抽出機能、i18n文字列の保持、本番環境のグリッチ(未定義変数やフォールバック、パディング不足など)の修正リスト作成など、ビデオ制作の全工程をカバーします。Claude Code、Cursor、Codexなど、サブエージェント機能とファイル書き込み機能を持つAIエージェントプラットフォームで使用することを想定しており、`CLAUDE_SKILL_DIR`環境変数とPythonランタイムに依存します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/ui-spec-from-code

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

コードからのUI仕様

ビデオは製品のインターフェースを録画ではなくHTMLとCSSで再構築するため、インターフェースの品質は仕様の正確さに依存します。近似は見過ごされません。このスキルが生まれた制作現場では、レビュアーが手描きのアイコンとロゴを初回レビューで却下し、サイズと名前が間違った手作りバッジに激怒しました。修正はコードを読むことで行われましたが、コードには目視では見えない落とし穴が潜んでいました。ルートフォントサイズはアプリケーションシェルによって実行時に設定され(スタイルシートで宣言された10pxではなく14px)、いくつかのCSS変数は本番環境に存在せずフォールバック値が適用され、あるコンポーネントは2ヶ月前のコミットでアクセントバーを失い、2つの「ダイアログ」はライブラリのダイアログではなくカスタムポップアップでした。

そのため、仕様のすべての値はリテラルかつ出典付きであり、出典を明記できない値はフラグが立てられ、決して推測されません。

入力

  • videos/<video>/SOURCES.md (source-reconから):各画面、そのルート、コンポーネント、状態。存在しない場合は、最初にsource-reconを実行してください。
  • sources/<role>/ と sources.lock。すべての引用はロックされたshaを使用します。
  • product.yaml:app_canvas.logical(UIが再構築されるビューポート)、app_canvas.theme、app_canvas.rem_px、sources[].framework。
  • フレームワーク用アダプタ:references/adapters/<framework>.md。サブエージェントプロンプトを作成する前に読んでください。そのスタックで値がどこに隠れているかが示されています。
product.yamlのフレームワークアダプタステータス
angular-primengreferences/adapters/angular-primeng.md本番実績あり
reactreferences/adapters/react.md未検証
vuereferences/adapters/vue.md未検証
Tailwindを使用するスタックreferences/adapters/tailwind.md (フレームワーク固有のものと併用)未検証
html、other、サーバーテンプレートreferences/adapters/html.md未検証

未検証のアダプタの場合は、ユーザーにその旨を伝え、それに従い、最後に学んだことを追加してください(「<製品>で学んだこと」セクションを短く追加)。そうすることで、次の製品がより先に進めるようになります。

1. グローバルレンダリング情報(製品ごとに1回)

画面の前に、すべての画面が依存する情報を確立し、出典付きで kit/render-facts.md に書き込みます。

  • 実行時のルートフォントサイズ(CSSだけでなく、それを設定するアプリケーションシェルのコードを検索)。これにより、rem の変換が正しくなります。異なる場合は、product.yaml の app_canvas.rem_px を更新します。
  • テーマ:どのセレクタがビデオのテーマを有効にするか、そしてそれがデフォルトでオンかどうか。
  • トークンファイル、CSSレイヤーまたはインポート順序(どのルールが優先されるか)、ロックファイルからの正確なバージョンとそのテーマプリセットを持つコンポーネントライブラリ。
  • 実際に読み込まれるフォント(linkタグ、@font-face、フォントパッケージ)。CSSで名前が指定されているだけではありません。宣言されているが読み込まれていないフォントは、本番環境ではフォールバックとしてレンダリングされます。
  • デスクトップブレークポイント。app_canvas.logical がデスクトップレイアウトを表示していることを確認します。

次に、ビデオのテーマ用にリテラルに解決されたトークンを書き込みます。

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/ui-spec-from-code/scripts/resolve_tokens.py" <product_dir> \
  [--role frontend] [--theme-selector "html.dark"] [--files src/styles/tokens.css ...]

これは、sources/<role>/ からCSSカスタムプロパティ、トップレベルのSCSS変数、Tailwind v3テーマ(静的に)を読み取り、すべての var() と $variable を解決し、各行に /* role/path:line@sha */ の出典を付けて kit/tokens.css に書き込みます。UNDEFINED とフラグが立てられた行は、本番環境で定義されていない変数です(潜在的なグリッチ)。needs a Sass compile は、Sass関数で構築された値にマークを付けます。これはサブエージェントが関数とその入力から手動で解決する必要があります。エクスポートに関連のないスタイルシート(ドキュメントサイト、メールテンプレート、ベンダーCSS)が含まれている場合は、--files を使用してください。

2. 画面ごとに1つのサブエージェント

画面ごとに(または大きな画面のパネルごとに)1つの読み取り専用サブエージェントを、すべて並列で起動します。references/ui-spec-prompt.md にアダプタの「値が隠れている場所」リストを追加して埋めます。各サブエージェントを sources/<role>/ (ユーザーのチェックアウトではない)に向け、レンダリングコンテキスト(論理キャンバスサイズ、テーマ、rem、レンダリング情報、トークン、および既に再構築された部分のCSS)を提供します。これにより、新しい部分が一致します。

各サブエージェントは以下を返します:キャンバス内のジオメトリ、状態ごとの静的HTML(フレームワーク構文なし)、リテラル値と値ごとの出典を持つ1つのCSSブロック、追加クラスとしてのホバー/フォーカス/アクティブ/無効/ローディング状態、正確な継続時間とイージングを持つトランジションとキーフレーム、ライブラリと名前によるアイコン(またはそのままのインラインSVG)、すべての表示文字列、および明示的な「未検証」リスト。

コーディネーター(あなた)は自分で仕様を抽出しません。実際のアプリケーションの1つの画面は、数十キロバイトの調査結果になる可能性があり、ビデオの途中でコンテキストがいっぱいになったコーディネーターは、ビルド全体を見失います。

3. アイコンと画像

アイコンは製品独自のアイコンセットとアセットから取得し、描画したり、ブラウザプロファイルや拡張機能フォルダから取得したりすることは決してありません。製品ごとに(そして新しい画面ごとに)references/icon-extraction-prompt.md を実行して、ビデオが必要とするすべてのアイコンをそのライブラリと名前にマッピングし、その名前をproduct-kitの collect_icons.py に渡します。このスクリプトはSVGを出典付きで kit/icons/ にコピーします。SVGファイルがないアイコンフォントの場合、ビルドはライブラリ独自のCSSからコードポイントを書き込み、空のボックスをレンダリングするのではなく、不明な名前では失敗する必要があります。

4. 仕様を書く

画面ごとに、videos/<video>/specs/<screen>.md と specs/<screen>.html を作成します。

# 仕様: <画面>
ソース: frontend@1a2b3c4 (SOURCES.mdを参照)。キャンバス 1440x810、テーマ light、rem 16。

## ジオメトリ
| 要素 | x | y | w | h | 出典 |

## 状態
S1 <名前>: <表示内容、架空のデータ>。<screen>.html 内のHTML、セクション S1。

## CSS
<1つのブロック、リテラル値、各行に /* role/path:line@sha */>

## モーション
| 対象 | プロパティ | 開始値 | 終了値 | 継続時間 | イージング | 遅延 | 出典 |

## アイコン
| キー | ライブラリ | 名前 | kit/icons 内のファイル | 出典 |

## 文字列
| キー | テキスト | 出典 |

## 修正(ビデオで修正された本番環境のグリッチ)
| 対象 | 本番環境の挙動 | ビデオの挙動 | 理由 |

## 未検証
- <値または挙動、理由、および利用可能な最良の参照>

見た目を維持し、グリッチを修正する

レイアウト、トークン、動作を1:1で再構築します。アニメーション、ホバー、タイピング、ローディング状態など、実際の製品のように感じさせるものも含みます。しかし、目に見える本番環境の欠陥は修正します。ビデオは製品を最高の状態で表示し、レビュアーはなぜバグが画面に表示されているのか尋ねるからです。パディング不足、オーバーフロー、テキストの切り捨て、ネイティブブラウザコントロール(製品がデザインしたオーディオプレーヤーの代わりに表示されるグレーのデフォルトオーディオプレーヤー)、フォールバック値を表示する未定義変数、クリック後に残るフォーカスリングなどです。すべての修正を仕様の修正テーブルとBRIEFノートにリストします。設計上の決定である奇妙な点(フィールドを覆うスティッキーフッター、コンテンツと共にスクロールするサイドバー)はそのまま維持します。それらを変更することは修正ではなく、再設計です。

仕様が適用して記録する2つの追加の変換:

  • 正規名。product.yaml names のレガシー文字列を、ライブUIがまだ古いものを表示している場合でも正規名に置き換えます。その要素の他のすべての点は維持します。
  • 禁止用語。実際の画面にベンダーまたは banned_terms の用語(モデルピッカー、統合カード)が表示されている場合は、その部分をフレームから除外します。空っぽまたは壊れて見えてはいけません。それが自然に存在しないフレーミングまたは状態を選択します。

データ

仕様には、product.yaml cast からの架空のデータのみが含まれます。リポジトリ内のフィクスチャ、シード、スクリーンショットには実際の名前が含まれる場合があります。それらの形状を使用し、値は決して使用しません。

仕様をビルドに渡す前のチェックリスト

  • ロックされたコミットが出典として使用されている。レンダリング情報が書き込まれている。ビデオのテーマ用にトークンが解決されている。
  • キャンバスサイズがデスクトップブレークポイントより大きい。remが実行時と一致している。
  • すべての var() が解決されている。未定義のものはフォールバックと共にリストされている(またはグリッチとして修正されている)。
  • すべての文字列がi18nファイルまたはテンプレートから取得されている。正規名が適用されている。
  • すべてのアイコンがアプリのライブラリから取得されている。ビルドはグリフが見つからない場合に失敗する。
  • ロゴと画像がリポジトリのアセットから取得されている。
  • デフォルト状態(タブ、アコーディオン、トグル)がコードと一致している。
  • オーバーレイ、ポップアップ、トランジションのタイミングが正確なイージングと共に取得されている。
  • スクロール範囲が実際のコンテンツ内に収まっている。テキストが端で切れていない。
  • フレーム内にベンダー、禁止用語、内部ID、実際の顧客データが含まれていない。
  • 修正と維持された奇妙な点がリストされている。未検証の値がレビュアー用にリストされている。

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

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.

関連スキル