media-use: オーディオ/画像を調達する前に、
/media-useを呼び出して HeyGen カタログから BGM/SFX/画像を解決してください。既存のアセットを登録するには、まず--adoptを実行します。詳細は/media-useスキルを参照してください。
PR から HyperFrames へ
このスキルを使用して、GitHub プルリクエストを取り込み、変更を理解し、コード変更の解説動画を計画し、HyperFrames でフレームごとに構築します。入力は gh 経由で読み取られるコード変更であり、ウェブサイトではありません — 寄稿者のアバター以外にキャプチャステップや実際のアセットはありません。
Step 0 の前にルートを確認してください。 あなたはオーケストレーターです。各ステップを実行し、そのゲートを確認してから次のステップに進みます。このスキルは GitHub プルリクエスト(コード変更)用です。他の意図は別の場所にルーティングしてください: 製品ローンチ/プロモーション →
/product-launch-video; 一般的なウェブサイトツアー →/general-video; PR のないトピック解説 →/faceless-explainer; 既存映像へのキャプション →/embedded-captions; 短いナレーションなしモーショングラフィック →/motion-graphics; リポジトリ全体または複数 PR のリリースウォークスルー →/general-video。対象外: ライブ/レンダリング時のデータ — PR の事実はオーサリング時に一度読み取られ、組み込まれます。ユーザーが「動画を作って」とだけ言った場合やルートが不明な場合は、最初に/hyperframesを読んでください。
あなたはオーケストレーターです。videos/<project>/ ディレクトリで作業します。ステップを順に実行し、各ゲートを通過してから続行します。ユーザーゲートがあるステップは Step 0、Step 3、Step 6 です。Step 5 を除き、すべてのステップを自分で実行します。Step 5 ではフレームごとに 1 つのサブエージェントを派遣します。デザインやモーションのルールはここに記述せず、フレームワーカーのサブエージェント hyperframes-creative と hyperframes-animation に任せます。
ワークフロー: Step 0 セットアップ → hyperframes.json; Step 1 取り込み → capture/extracted/ + assets/<login>.png; Step 2 デザインシステム → frame.md; Step 3 ストーリーボード/スクリプト → STORYBOARD.md と SCRIPT.md; Step 3.1 オーディオ → audio_meta.json; Step 4 ビジュアルデザイン → 拡張された STORYBOARD.md; Step 5 フレーム → compositions/frames/NN-*.html と index.html; Step 6 最終レンダリング → renders/video.mp4。
Step 0: セットアップとブリーフ
目標: PR 参照とコア動画ブリーフを確定し、必要に応じて HyperFrames プロジェクトを作成します。
PR 参照(完全な URL、<owner>/<repo>#<N> 参照、またはチェックアウト済みリポジトリ内の「this PR」)を取得し、1 メッセージでブリーフを確認します — 各項目に推奨デフォルト値を示し、/hyperframes ですでに設定されている値を事前入力します: アングル(変更ログ / 機能紹介 / 修正解説 / リファクタリングウォークスルー — デフォルト: PR から推測)、オーディエンス(デフォルト: 開発者)、長さ(デフォルト: PR の変更サイズに合わせてスケーリング — 以下参照)、アスペクト(デフォルト 16:9)、言語。スタイルは常に claude です。ユーザーが返信するまで続行しません。「go」はデフォルトを受け入れます。
PR の変更サイズから長さを推奨し、固定の推測は行いません。ブリーフを確認する前に、PR を一度覗き見します — これは読み取り専用呼び出しで、アングルも特定します(Step 1 では完全な決定論的フェッチを実行します):
gh pr view <PR_REF> --json title,additions,deletions,changedFiles
additions + deletions(changedFiles で調整)から階層を選び、それをデフォルトとして提示します(ユーザーは上書き可能。ハード上限は約 3 分):
| PR の変更サイズ | 推奨長さ |
|---|---|
| 些細(約 50 行未満変更) | 約 20~40 秒 |
| 集中的(約 50~200 行) | 約 40~70 秒 |
| 大規模(約 200~600 行) | 約 70~110 秒 |
| 巨大(約 600 行超、または 25+ ファイル) | 約 110~180 秒 |
提案時にその根拠を 1 フレーズで述べます(例:「約 40 秒 — 小さな変更、+44/−13 を 12 ファイルにわたって」)。巨大な PR が必ずしも長い動画を意味するわけではありません — ストーリーが 1 つの重要な変更である場合は、簡潔にまとめてその旨を伝えます。
hyperframes.json が欠落している場合のみ初期化します。<project> は PR からケバブケースで命名します(例: acme-sdk-pr-1842)。ワークスペース名やタイムスタンプは使用しません。
npx hyperframes init "videos/<project>" --non-interactive --example=blank — init はインストール済みスキルを GitHub 上の最新バージョンと照合し、古いものがあればグローバルセットを更新します。
ブリーフの前にサインインステータスを表示 — npx hyperframes auth status を実行し、その出力をそのまま中継します(言い換えたり書き換えたりしないでください)。 これにより、音声/BGM が HeyGen を使用するかローカルエンジンを使用するかが報告され、サインインしていない場合はサインイン方法が示されます。サインインしていない場合は、そこで STOP してユーザーの選択を待ちます — サインインするか、ローカルエンジンで続行するために「go」/「offline」と言うまで — ブリーフやその他のことを尋ねる前に。 これを一時的なメモではなく、実際の決定ポイントとして扱います。選択肢をブリーフの質問に組み込まないでください。また、リポジトリごとの .env にキーを書き込まないでください。(自律モードでは、ステータスを記録し、オフラインで続行します。)正規のガイダンスについては、../hyperframes-media → Preflight を参照してください。
ゲート: hyperframes.json が存在する。PR 参照が取得された。アングル、長さ、アスペクト比、言語が確定した。サインインステータスが表示された(サインイン済み、またはオフラインで続行)。
Step 1: PR の取り込み(キャプチャなし)
目標: PR の事実を取得し、情報源としてプロジェクトに組み込みます。ウェブサイトのキャプチャはありません。 fetch-pr.mjs は gh を決定論的に実行します — ページネーションされた gh api でファイルリストを完了させるため、大きな PR でも約 100 ファイルで切り捨てられず、capture/pr.json + capture/diff.patch のみを書き込みます(スクラッチディレクトリなし)。次に ingest.mjs がそれをオフラインで合成キャプチャパッケージに変換します。
PR="<url | owner/repo#N | N>"
# PR を決定論的にフェッチ: gh を実行、ページネーションされた
# gh api でファイルリストを完了(大きな PR でも約 100 ファイルで
# 切り捨てられない)、capture/pr.json + capture/diff.patch のみ書き込み —
# スクラッチディレクトリなし。gh auth / not-found / private エラーはここで exit 1。
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# オフライン変換 → capture/extracted/{tokens.json(colors:[] → claude パレット)、
# visible-text.txt(ブリーフ)、people.json(寄稿者、ボットフィルター済み、
# avatarFile=assets/<login>.png)}。
(cd "videos/<project>" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# people フロントの唯一のネットワークステップ — 各寄稿者の GitHub アバターを
# assets/<login>.png にダウンロード(オプションのクレジットクローズ用)。
# ベストエフォート。常に exit 0。
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
fetch-pr.mjs が exit 1 の場合(gh auth / not found / private)、その stderr を報告して停止します — PR の内容を作り出さないでください。 ingest.mjs が exit 1 の場合、stderr を読み(通常は不正な pr.json)、修正して再実行します(決定論的)。fetch-people-avatars.mjs は常に exit 0 です。アバターがない場合は、単に著者へのクレジットクローズがないことを意味します。
ゲート: capture/pr.json、capture/diff.patch、capture/extracted/tokens.json、capture/extracted/visible-text.txt、capture/extracted/people.json が存在する。PR の変更を 1 つの明確な文で説明できる。assets/<login>.png はベストエフォート — 存在しなくても失敗ではありません。
Step 2: デザインシステム
目標: claude フレームプリセットを採用。スクリプトがこれをこの動画の frame.md + キャプションスキンに変換します。
スタイルは固定 — claude(ウォームなエディトリアル。diffs に最適化されたネイビーのコード面)。実行:
node <SKILL_DIR>/scripts/build-frame.mjs --preset claude --hyperframes .
スクリプトは claude プリセットの FRAME.md を frame.md にコピーし、capture/extracted/tokens.json 内のブランドトークンとリミックスします(PR にはトークンなし → colors:[]/fonts:[] は claude 独自のパレット、完全なデザインを維持)、プリセットのキャプションスキンを .hyperframes/caption-skin.html にコピーし、自己検証します(マッピングが壊れていると exit 1)。exit 0 したらすぐに続行 — 手動編集は不要。
ゲート: build-frame.mjs が exit 0 — frame.md が claude プリセットから存在し、.hyperframes/caption-skin.html がキャプションスキンソースとして存在する。
Step 3: ストーリーボードとスクリプト
目標: PR を承認されたフレーム単位の説明計画に変換します。
references/story-design.md、../hyperframes-core/references/storyboard-format.md、../hyperframes-core/references/script-format.md を読みます。これらを使用して STORYBOARD.md を書き、ナレーションが必要な場合は SCRIPT.md も書きます。
story-design.md を PR のアーキタイプ(変更ログ / 機能紹介 / 修正解説 / リファクタリングウォークスルー)、PR ネイティブのフレームタイプ、フック、説得、ビート、フレームごとの単語予算、オプションのクレジットクローズに使用します。順序はナラティブデザイン、diff のファイル順序ではありません — 変更を説明し、diff を読み上げないでください。capture/diff.patch から実際の diff ハンクを 2~4 件(それぞれ小さな読みやすいスニペット)取り上げます。各フレームの scene に必要な code-* ブロックに名前を付けます。フレームはオプションの credits クローズ(2~6 個の assets/<login>.png アバター)以外に asset_candidates を持ちません。ストーリーボードとスクリプトのリファレンスから正確な必須フィールドを使用します。
ドラフト後、フレーム単位のサマリーを表示します。同じメッセージで、ユーザーに (a) 承認または変更リクエストを求め、(b) ストーリーボードスキャフォールドのライブプレビュー(npx hyperframes preview)が必要かどうかを尋ねます — はいの場合のみ開きます。承認されるまで繰り返します。プレビューの選択は Step 6 に持ち越します。
ゲート: STORYBOARD.md が存在し、すべてのフレームに必要なナラティブフィールドがある。ナレーションが必要な場合 SCRIPT.md が存在する。ユーザーが計画を承認した。
Step 3.1: オーディオ
目標: 承認されたスクリプトからナレーション、単語タイミング、音楽、オーディオメタデータを生成します。
Step 3 承認後にオーディオを開始します。バックグラウンドで実行し、その後 Step 4 に進みます。
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
オーディオスクリプトは、ナレーション、単語タイミング、HeyGen の音楽ライブラリからの BGM 検索、タイミングメタデータを処理します。BGM の雰囲気はストーリーボードの music: フィールドから取得されます。これは HeyGen Audio API を取得に使用し、生成には使用しません。また、TTS と同じ ~/.heygen 認証情報を使用します。プロバイダーの詳細については、../hyperframes-media/references/tts.md を読んでください。
ナレーションがなく SCRIPT.md もない場合は、音声生成をスキップします。ストーリーボードに音楽の雰囲気がある場合、BGM は引き続き実行される可能性があります。
ゲート: オーディオジョブが開始されたか、プロジェクトが無音とマークされている。
Step 4: フレームビジュアルデザイン
目標: 各ストーリーボードフレームにビジュアルディレクション、レイアウト意図、モーションの選択肢を追加します。
STORYBOARD.md をその場で編集します。別のストーリーボードを作成しないでください。色、タイポグラフィ、レイアウトの雰囲気、スタイルの信頼できる情報源として frame.md を使用します。
references/visual-design.md、references/composition.md、references/motion-language.md、references/code-vocabulary.md、../hyperframes-animation/ を読みます。visual-design.md を必須のフレームフィールドと必須の ## Video direction ブロック、およびコードビートが focal として code-* ブロックに名前を付ける方法に使用します。code-vocabulary.md を使用して、ビートごとに適切なブロックを選択します(diff = code-diff、リファクタリング = code-morph、新規コード = code-typing、…)。composition.md をレイアウト/階層/焦点に使用し、motion-language.md + ../hyperframes-animation/ を有効なエフェクト ID とブループリント ID に使用します。エフェクト名やブロック/ブループリント ID をでっち上げないでください。
すべてのフレームに対して、effects と focal および/または roles を含む、必要なビジュアルおよびモーションフィールドを追加します。コードビートの場合は、focal として code-* ブロックに名前を付け、effects が周囲の claude Code Surface(ブロックが所有するコードアニメーションではない)を振り付けできるようにします。動画全体に 1 つの ## Video direction ブロックを追加します。
ストーリー、スクリプト、transition_in、asset_candidates、PR ソースは変更しないでください。このステップでは HTML を記述しません。アセットステージングステップはありません — 唯一の実際のアセットはクレジットアバターで、すでに assets/ にあります。
ゲート: すべてのフレームに effects と focal および/または roles がある。コードフレームは code-* ブロックに名前を付けている。## Video direction が存在する。
Step 5: フレームの構築
目標: すべてのストーリーボードフレームを HTML コンポジションとして構築し、再生可能な動画を組み立てます。
オーディオが開始された場合、Step 3.1 のオーディオが終了するのを待ちます。その後、持続時間を同期し、SFX を取得します。無音の場合は両方をスキップします。
node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
持続時間の同期は機械的です。実際の音声の持続時間が優先されます。無音のフレームは推定値を保持します。同期された持続時間を手動で編集しないでください。
ディスパッチ前に、STORYBOARD.md 全体で名前が付けられたレジストリブロックを一度プレインストールして、並列ワーカーがレジストリで競合しないようにします:
for b in <ストーリーボード内の各レジストリブロック>; do npx hyperframes add "$b"; done
ディスパッチ前に、sub-agents/frame-worker.md と ../hyperframes-core/references/subagent-dispatch.md を読みます。フレームごとに 1 つのサブエージェントを、可能であれば並列でディスパッチします。そうでない場合は、ワーカーを波状に実行します。各ワーカーは正確に 1 つのフレームを処理します。各ワーカーのコンテキストには、PROJECT_DIR、frame_id、キャンバスサイズ、キャプションステータスと(キャプションが有効な場合の)キープアウトバンド、ANIM_DIR(../hyperframes-animation/ への絶対パス)、references/code-vocabulary.md への絶対パスを含める必要があります。各ワーカーは frame.md、自身の ## Frame N ブロック、引用された各エフェクト/ブループリント ID のレシピ本文、および(コードビートの場合)名前付きブロックの入力の code-vocabulary.md を読みます。各ワーカーは compositions/frames/NN-*.html のみを書き込みます。ワーカーは決して STORYBOARD.md を編集しません。
各ワーカーが戻ってきたら、STORYBOARD.md でそのフレームを animated とマークします。
オーディオタイミングが存在するようになったら、バックグラウンドでキャプションを構築し、インデックスを組み立てます:
node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
captions.mjs はプロジェクトの .hyperframes/caption-skin.html(Step 2 でコピーされた claude のもの)を使用し、frame.md からブランドトークンを注入します。captions: skipped (<reason>) は検証済みです...