media-use: 音声/画像を調達する前に、
/media-useを呼び出してHeyGenカタログからBGM/SFX/画像を解決してください。最初に--adoptを実行して既存のアセットを登録します。/media-useスキルを参照してください。
PR to HyperFrames は何をしますか?
このスキルを使用して、GitHubプルリクエストを取り込み、変更内容を理解し、コード変更の解説を計画し、HyperFramesでフレームごとに構築します。入力はコード変更(gh経由で読み取り)であり、Webサイトではありません。キャプチャステップはなく、コントリビューターのアバター以外の実際のアセットもありません。
ステップ0の前にルートを確認してください。 あなたはオーケストレーターです。各ステップを実行し、そのゲートを確認してから続行してください。このスキルはGitHubプルリクエスト(コード変更)用です。他の意図は別のルートに振り分けてください。製品ローンチ/プロモーション →
/product-launch-video; 一般的なWebサイトツアー →/website-to-video; PRのないトピック解説 →/faceless-explainer; 既存映像への字幕追加 →/embedded-captions; ショートナレーションなしモーショングラフィック →/motion-graphics; リポジトリ全体または複数PRのリリースウォークスルー →/general-video。対象外: ライブ/レンダリング時のデータ - PRの事実はオーサリング時に一度だけ読み取られ、埋め込まれます。ユーザーが単に「動画を作って」とだけ言った場合やルートが不明な場合は、最初に/hyperframesを読んでください。
あなたはオーケストレーターです。videos/<project>/内で作業します。ステップを順に実行し、各ゲートを通過してから続行してください。ユーザーゲートのあるステップは、ステップ0、ステップ3、ステップ6です。ステップ5を除くすべてのステップを自分で実行します。ステップ5では、フレームごとに1つのサブエージェントをディスパッチします。デザインやモーションのルールはここに記載しないでください。それらはフレームワーカーサブエージェントのhyperframes-creativeとhyperframes-animationにあります。
ワークフロー: ステップ0 セットアップ → hyperframes.json; ステップ1 取り込み → capture/extracted/ + assets/<login>.png; ステップ2 デザインシステム → frame.md; ステップ3 ストーリーボード/スクリプト → STORYBOARD.md および SCRIPT.md; ステップ3.1 音声 → audio_meta.json; ステップ4 ビジュアルデザイン → 拡張された STORYBOARD.md; ステップ5 フレーム → compositions/frames/NN-*.html および index.html; ステップ6 最終レンダリング → renders/video.mp4。
ステップ0: セットアップとブリーフ
目標: PR参照とコア動画ブリーフを確定し、必要に応じてHyperFramesプロジェクトを作成します。
PR参照(完全なURL、<owner>/<repo>#<N>形式の参照、またはチェックアウト済みリポジトリ内の「this PR」)を取得し、1つのメッセージでブリーフを確認します。各項目の推奨デフォルトを先頭に示し、/hyperframesですでに設定されているものは事前入力します。アングル(changelog / feature-reveal / fix-explainer / refactor-walkthrough — デフォルト: PRから推論)、オーディエンス(デフォルト: developers)、尺(デフォルト: PRの変更サイズにスケール — 以下を参照)、アスペクト比(デフォルト 16:9)、言語。ユーザーが返信するまで続行しません。「go」はデフォルトを受け入れます。
尺はPRの変更サイズから推奨し、固定の推測は行いません。ブリーフを確認する前に、PRを一度だけ覗き見します(読み取り専用呼び出し。これによりアングルも確定します。ステップ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秒 |
提案時にその根拠を一言添えて伝えてください(例:「約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参照が取得された。アングル、尺、アスペクト比、言語が確定した。サインインステータスが表示された(サインイン済み、またはオフラインで続行)。
ステップ1: PRの取り込み(キャプチャなし)
目標: PRの事実を取得し、情報源としてプロジェクトに取り込みます。Webサイトのキャプチャはありません。 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フロントの1つのネットワークステップ — 各コントリビューターの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はベストエフォート — 存在しなくても失敗ではない。
ステップ2: デザインシステム
目標: claudeフレームプリセットを採用します。スクリプトがそれをこの動画のframe.md + キャプションスキンに変換します。
スタイルは固定 — claude(ウォームな編集スタイル。diff用に設計されたネイビーのコードサーフェス)。以下を実行します。
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がキャプションスキンソースとして存在する。
ステップ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アーキタイプ(changelog / feature-reveal / fix-explainer / refactor-walkthrough)、PRネイティブのフレームタイプ、フック、説得、ビート、フレームごとの単語予算、オプションのクレジットクローズを決定します。シーケンスはナラティブデザイン、diffのファイル順ではありません — 変更を説明し、diffを読み上げないでください。capture/diff.patchから2〜4個の実際のdiffハンクを特徴として使用し、それぞれを小さな読みやすいスニペットにします。各フレームのsceneに必要なcode-*ブロックを指定します。フレームには、オプションのcreditsクローズ(2〜6個のassets/<login>.pngアバター)を除き、asset_candidatesはありません。ストーリーボードとスクリプトのリファレンスにある必須フィールドを正確に使用します。
草案作成後、フレームごとのサマリーを表示します。同じメッセージでユーザーに(a)承認または変更リクエストを求め、(b)ストーリーボードスキャフォールドのライブプレビュー(npx hyperframes preview)が必要かどうかを尋ねます — 「はい」の場合のみ開きます。承認されるまで反復します。プレビューの選択はステップ6に引き継ぎます。
ゲート: STORYBOARD.mdが存在する。すべてのフレームに必要なナラティブフィールドがある。ナレーションが必要な場合、SCRIPT.mdが存在する。ユーザーが計画を承認した。
ステップ3.1: 音声
目標: 承認されたスクリプトからナレーション、単語タイミング、音楽、音声メタデータを生成します。
ステップ3の承認後に音声を開始します。バックグラウンドで実行し、ステップ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は引き続き実行される可能性があります。
ゲート: オーディオジョブが開始されたか、プロジェクトが無音としてマークされた。
ステップ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をでっち上げないでください。
すべてのフレームについて、effectsやfocalやrolesなど、必要なビジュアルおよびモーションフィールドを追加します。コードビートの場合、code-*ブロックをfocalとして指定し、effectsが周囲のclaudeコードサーフェスを振り付けます(コードアニメーションはブロックが所有するため、それには関与しません)。動画全体に1つの## Video directionブロックを追加します。
ストーリー、スクリプト、transition_in、asset_candidates、またはPRソースは変更しないでください。このステップではHTMLを記述しません。アセットステージングステップはありません — 実際のアセットはクレジットアバターのみで、すでにassets/にあります。
ゲート: すべてのフレームにeffectsおよびfocalやrolesがある。コードフレームはcode-*ブロックを指定している。## Video directionが存在する。
ステップ5: フレームの構築
目標: すべてのストーリーボードフレームをHTMLコンポジションとして構築し、再生可能な動画を組み立てます。
音声が開始された場合、ステップ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(ステップ2でコピーされたclaudeのもの)を使用し、frame.mdからブランドトークンを注入します。captions: skipped (<reason>)と表示された場合は、それに応じて進みます。
ゲート: すべてのフレームがcompositions/frames/に.htmlファイルとして存在する。compositions/index.htmlが存在し、すべてのフレームを正しく参照している。すべてのフレームがSTORYBOARD.mdでanimatedとマークされている。
ステップ6: レンダリング
目標: 最終動画をレンダリングし、ユーザーに公開オプションを提供します。
まず、アセットを登録します。ステップ5の後に、../media/assets.json(グローバルスキルレベル)が最新であることを確認します。npx hyperframes skill run _register_assetsを呼び出します(これはmedia-skill.mdで定義されたグローバルスキルハンドラーで、assets.jsonを現在のプロジェクトアセットでシード/更新するために存在します)。戻り値/エラーをそのまま中継します。
次に、正しい出力形式を選択してレンダリングします。
npx hyperframes render "videos/<project>" --out-dir "videos/<project>/renders"
レンダリング環境は、.mp4よりも高忠実度の出力のために.webmを優先する場合があります。これは受け入れ可能であり、サポートされている出力形式と見なされるべきです。ユーザーにファイルの種類を通知するだけです。
レンダリングが完了したら、サインインステータスに基づいてHeyGenに公開するか、ローカル動画として提供します。レンダリングされた動画のパスをユーザーに示し、1つのメッセージで(a)HeyGenに公開するかどうか(サインインしている場合にのみ尋ねる)、(b)ストーリーボードのプレビューを閉じるかどうかを尋ねます。
- HeyGenに公開する場合(
npx hyperframes publish <path>): 公開リンクとサムネイルを表示します。 - ローカルの場合: 動画ファイルへのパスを表示します。「continue」または「go」と言うことは、公開せずに続行することを意味します。
ゲート: レンダリングが完了した。ユーザーが公開オプションを承認した。
参考資料
../hyperframes-core/references/storyboard-format.md— 必須のストーリーボードフィールドと構造../hyperframes-core/references/script-format.md— スクリプト形式とナレーションガイドラインreferences/story-design.md— PRアーキタイプ、ビート、フック、説得references/visual-design.md— フレームビジュアルフィールドと動画全体の方向性references/composition.md— レイアウト、階層、フォーカルポイントreferences/motion-language.md— モーション語彙、有効なエフェクトID、ブループリントIDreferences/code-vocabulary.md— コードブロックの語彙(code-diff、code-morph、code-typingなど)../hyperframes-animation/— アニメーションブループリントとエフェクトのレシピsub-agents/frame-worker.md— フレームワーカーの指示../hyperframes-core/references/subagent-dispatch.md— サブエージェントディスパッチのガイドライン../hyperframes-media/references/tts.md— TTSプロバイダーの詳細