Communitygithub.com

josueh04/product-video-skills

コードだけでは得られないUIのピクセル単位のリファレンスを収集します。画面録画からのフレームとタイムドOCRテキスト、過去のClaude Codeセッションのトランスクリプトから復元したキャプチャ、本番環境と同様にビルドしたローカルアプリインスタンス、サードパーティアプリ向けのWeb調査、さらにサイドバイサイドのパリティ画像とコンタクトシートを使用します。

product-video-skills とは?

このスキルは、ソースコードだけでは捉えきれないランタイムのUI動作を、実際の画面録画や過去のセッションから復元したキャプチャなどを用いて正確にリファレンスとして取得するためのツールセットです。特に、バックエンドの応答による表示順序やアニメーションの実時間、他社製品のUIなど、コードからは得られない情報を補完します。主なワークフローは、画面録画(.mov/.mp4)からのフレーム抽出とOCRによるテキストタイムライン作成、Claude CodeのセッションJSONLからの画像復元、本番コミットからのローカルインスタンスビルドとヘッドレスブラウザキャプチャ、そしてサードパーティUIの公開情報のみを用いたWeb調査です。また、ビルドしたUIと実物の比較を容易にするためのパリティ画像生成機能も備えています。このスキルの最大の特徴は、レビューアの個人ブラウザやアカウントに絶対にアクセスしないという厳格なルールです。過去にエージェントがレビューアのブラウザで操作中に問題を起こした事例を踏まえ、オフラインのリファレンスを最優先し、セッションのトランスクリプトからキャプチャを復元する手段を提供します。対応プラットフォームは主にmacOS(OCRはApple Vision使用)とLinux(OCR非対応、コンタクトシートで代替)であり、スクリプト群はシェルスクリプトとPythonで実装されています。

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

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

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

ドキュメント

UIリファレンスキャプチャ

コードは構造、スタイル、文字列、アイコンを提供します。しかし、ランタイムで何が起こるか(バックエンドが何を返すか、どの順序で表示されるか、実際のアプリがどのくらい待つか)は提供せず、他社のUIについても何も語りません。このスキルは、固定された優先順位に従ってリファレンスでこれらのギャップを埋めます。決して誰かの個人ブラウザで即興で操作することはありません。

この最後のルールには経緯があります。このスキルの元となったプロダクションでは、エージェントがレビューアのログイン済みブラウザにアクセスしてライブアプリをキャプチャすることが許可されていました。ライブフローはハングし、エージェントはレビューアが停止を指示した後も「クリーンアップ」ステップを続け、テストワークスペースに不要なアイテムを残し、セッションは約68分後に何も使えるものが構築されずに悪い形で終了しました。同じキャプチャは後でセッションのトランスクリプトから数分で復元されました。まずオフラインリファレンス、ブラウザはユーザーが明示的に要求し、孤立した環境でのみ使用し、停止が指示されたらすぐに停止します。

格納場所

  • 入力(レコーディング、エクスポート、ユーザーが提供したスクリーンショット):到着次第、products/<slug>/references/<name>/ にコピーします。ダウンロードフォルダとOSの一時キャプチャフォルダはクリーンアップされます。元のプロダクションでは、あるレコーディングはシステムが削除するはずだったフォルダにありました。macOSのレコーディング名には、AM/PMの前に狭い改行なしスペース(U+202F)が含まれています:名前を入力するのではなく、globで検索してください。
  • 作業材料(数千のフレーム、復元されたキャプチャ、生のOCR):すべてのリポジトリの外にあるスクラッチフォルダ(例:$TMPDIR/pvs-<slug>-<name>/)。
  • 保存する価値のある結果(OCRタイムライン、実際のデータを切り取ったキーフレーム、分析):references/<name>/ に保存し、SOURCES.mdから引用します。

実際のワークスペースのレコーディングとキャプチャには、実際の顧客名、メールアドレス、電話番号、内部ID、他のユーザーの会話が含まれます。これらはworkbenchリポジトリに決して入れず、ビデオにも表示しません:セクション1のステップ6に変更が必要なものをリストしています。

テクニックの選択

持っているものテクニック読むもの
プロダクトの画面録画1. 録画を分析するreferences/recording-analysis.md
アプリを見た過去のセッション2. トランスクリプトからキャプチャを復元するこのファイル、セクション2
ローカルで実行できるアプリ3. 本番環境と同様にビルドしたローカルインスタンスreferences/local-instance.md
他社のプロダクト4. Web調査、公開ソースのみreferences/third-party-ui-prompt.md
何もない(電話、エンドカード、生成テキスト)キットからデザインし、マークするproduct-truth (mock)

この順序で試してください。誰かに録画を依頼する前に、セクション2を確認してください:キャプチャがすでに存在する可能性があります。4つのうちどれも機能しない場合は、その旨を伝えてください。レビューアのブラウザにフォールバックしないでください。

1. 画面録画を分析する

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/ui-reference-capture/scripts"
W="$TMPDIR/pvs-acme-board"                                    # スクラッチ、リポジトリ外
bash "$S/frames.sh" references/board/rec.mov "$W" --fps 10 --logical-width 1440
bash "$S/ocr.sh" "$W/logical" "$W/ocr.jsonl"                  # macOSのみ
"$PVS_HOME/bin/pvs-py" "$S/ocr_events.py" "$W/ocr.jsonl" references/board/ocr-timeline.txt --fps 10 \
  --region "panel=0.6,0,1,[email protected]"
"$PVS_HOME/bin/pvs-py" "$S/grid.py" sheet "$W/overview.png" "$W/logical" --every 20 --cols 4
  1. frames.sh は小さなサムネイル(変更検出用)と、アプリの論理幅(Retina録画は2x:論理幅はピクセル幅の半分)のフレームを書き出します。これにより、1フレームピクセルは再構築されたアプリの1CSSピクセルになります。
  2. ocr.sh は ocr.swift(Apple Vision)をキャッシュフォルダに一度コンパイルし、フレームごとに1行のJSONを書き出します。Linuxでは「unsupported」で終了します:代わりにコンタクトシートを読んでください。
  3. ocr_events.py はフレームごとのOCRを安定したスパン start-end [region] text に変換します。このタイムラインは、実際のアプリが表示する正確な文字列とそのタイミングを提供し、ビデオを目で推測するよりも優れています。
  4. grid.py sheet はコンタクトシートを作成します:2秒ごとの概要、次にフェーズごとに10fpsの高密度シート。grid.py overlay は測定のためにフレームに論理ピクセルグリッドを描画します。
  5. キーフレームを references/<name>/frames/<t>-<state>.jpg として保存します(実際のデータは切り取ります)。
  6. references/<name>/analysis.md を references/recording-analysis.md の構造で書き込みます:正確な文字列を含む実際のタイムライン、測定されたモーション(パネルが開くまでの時間、カーソルが止まる時間)、「ビデオのため変更必須」テーブル(実際の名前、メール、電話、ワークスペース、内部ID、長い待機時間、DockなどのOSクローム)、および誰かがそれらの上に構築する前に提起すべきプロダクトギャップ(ストーリーに必要なステップが録画で失敗していることを示す)。

録画は待機時間を圧縮することでギャップを隠します。短縮したすべての待機時間を記録してください。

2. 過去のセッションからキャプチャを復元する

Claude Codeセッションでツールが返したすべての画像(ブラウザスクリーンショット、ウィンドウキャプチャ、読み込んだ画像)およびチャットに貼り付けられたすべての画像は、そのセッションのJSONLに保存されています。

"$PVS_HOME/bin/pvs-py" "$S/recover_transcript_images.py" ~/.claude/projects/<project>/<session>.jsonl \
  [--from-line N] [--tool screenshot]

出力フォルダを指定しない場合、新しい一時フォルダに書き出し、gitワークツリー内のフォルダは拒否します。これらのキャプチャは実際のアカウントを示しているためです。index.tsv(ファイル、時刻、ツール、入力)を書き出すので、必要な画面を見つけることができます。コンタクトシート(grid.py sheet <out> <dir> --labels name)でレビューし、実際のデータを切り取ったクリアされたものだけを references/<name>/ にコピーします。元のプロダクションでは、1本のビデオ全体が117枚の復元画像とコードから構築されました。

3. 本番環境と同様にビルドしたローカルインスタンス

アプリがユーザーのマシンで実行できる場合の最も信頼性の高いリファレンス:本番コミットから本番ビルド引数でビルドし、架空のデータでシードし、すべての共有システムから隔離し、ヘッドレスブラウザでキャプチャします。開始する前に references/local-instance.md を読んでください。ユーザーは自分のアプリを実行することに同意する必要があり、ユーザーのアカウントや共有データベースは決して使用しません。

4. サードパーティUI

他社の画面については、references/third-party-ui-prompt.md を使用して調査サブエージェントを起動します:公開ソースのみ(公式ドキュメント、ヘルプセンター、プレスキット、マーケティングスクリーンショット、ベンダー所有の公開埋め込みデモ)、ログインは不可、送信や予約も不可、約30分。すべての値は、検証済み、測定済み、または推測済みとしてマークされて戻ってきます。プロダクトに独自のコンポーネントがある場合(チャットアプリのプレビューをレンダリングするプロダクトにはプレビューコンポーネントがあります。チャットアプリを再構築する代わりにそれを使用します)、それを優先します。サードパーティの画面全体は、実際の統合を証明する場合にのみ表示します。それ以外の場合は、プロダクト内でロゴとバッジを使用します。

パリティ:再構築が一致することを証明する

"$PVS_HOME/bin/pvs-py" "$S/pair.py" snapshots/nocam-12.4s.png references/board/frames/12.4-board.png \
  640 40 1100 300 "$W/pair-board-header.png" --ref-scale 2 --logical-width 1440 --render-width 1920

カメラをスケール1でスナップショット(#camera{transform:none!important} を使用したコンポジションのコピー)を撮り、両方から同じ論理ボックスをクロップして、それらを重ねます。スクリプトはチャネルごとの平均絶対差を出力します。値が下がり止み、重ねた画像にオフセットがなくなるまで反復します。アプリのピクセルで測定し、明示的に変換します:スケールの混乱は誤った座標の繰り返し原因でした。

ルールとその理由

  • 決してレビューアの個人ブラウザやプロファイルを使用しない、およびそこから取得したもの(フォント、アイコン、ストレージ)も使用しない。誰かが停止と言ったら、クリーンアップも含めてすべてのブラウザアクションを即座に停止する。
  • 決してログインしない、トークンやブラウザストレージを読み取らない。 キャプチャにログインが必要な場合、その人は自分のセッションで自分のパスワードを入力するか、キャプチャは行われない。
  • 復元および録画された素材はプライベートに保つ。 まず一時フォルダ、トリミングされたコピーのみ。
  • すべての推測値をマークする。 半分が推測されたリファレンスは、どの半分かを明示しなければならない。

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

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.

関連スキル