promo-video (プロモーションビデオ生成スキル)

promo-video

生のクリップから短いプロモーションビデオをアセンブルします。ポートレート、スクエア、ランドスケープ対応。 オプションでBlenderレンダリングのイントロ/アウトロ、AI生成音楽も利用可能。

このスキルはホストエージェントに依存しません。Agent Skills標準（https://agentskills.io）を実装するすべてのランタイム（Claude、Claude Code、OpenAI Codex、Gemini CLI、Cursor、GitHub Copilot、Cline、OpenCode、OpenHands、Goose、Kiro、Junieなど）で同一に動作する必要があります。ホスト固有のツール（AskUserQuestion、スラッシュコマンド、明示的に利用可能でない限りMCP）に依存してはなりません。すべてのユーザーとのやり取りは通常のチャットメッセージとして行います。

いつ使うか

• 「これらのクリップを繋ぎ合わせて30秒のリールにして」
• 「ハッカソンのプロモーンビデオをポートレートで作って」
• 「スマホ動画が入ったフォルダがあるんだけど、1080x1920のソーシャルクリップに音楽付きで作って」
• 「ロゴのイントロ＋ハートのアウトロ＋背景音楽付きのプロモを作って」
• ユーザーが .mov/.mp4 ファイルのディレクトリを参照し、1つの成果物を求めている。

前提条件

• ffmpeg がPATHにあり、libx264、aac、prores_ks（アルファチャンネル付きイントロ/アウトロMOVにのみ必要）でビルドされていること。
• Python 3.9+。
• Python依存関係を一度インストール: スキルディレクトリ内で pip install -r requirements.txt を実行。
• オプション: プロジェクトルートに SUNO_API_KEY を含む .env ファイルを置くと、音楽生成が有効になります。スキルはキーが設定されているか自動検出し、設定されている場合のみ音楽生成を提案します。
• オプション: ホストエージェントでBlender MCPが利用可能で、イントロ/アウトロのレンダリングを生成できます。references/blender_mcp.md を参照。

デフォルトフロー（対話ベース）

ステップ0 — 前回の実行からクリップが変更されたか検出

質問を始める前に、ユーザーが前回のセッションから再開しようとしているか確認します。gallery/.clips_snapshot.json が存在する場合（またはユーザーが以前使用したクリップフォルダを指定した場合）、以下を実行します:

python scripts/clip_diff.py <clips_dir>

• 終了コード 0 — クリップフォルダは最後のスナップショットと一致。続行。
• 終了コード 1 — 差異あり。レポートには新規/削除/変更されたクリップがリストされます。ユーザーに表示し、scripts/gallery.py を再実行してギャラリーを更新するよう提案します。既存の選択でまだ存在するクリップはそのまま残ります。
• 終了コード 2 — スナップショットなし。初回実行として通常通り続行。

既存のプロジェクトを再開する場合は、このステップをスキップしないでください — 古いギャラリーや selection.json をそのまま使って「新しいクリップがどこにもない？」というバグの原因になります。

質問

最初に、以下の質問を順番にユーザーにします。自然な回答を受け付けます。ホストがサポートしない限り、複数選択UIを表示しないでください。すべての質問に対して「あなたに任せる」という回答も受け付け、適切なデフォルトを適用します。

1. ターゲットフォーマット。 1080x1920 ポートレート（デフォルト）、1920x1080 ランドスケープ、または 1080x1080 スクエア。カスタムサイズも許可。
2. クリップソース。 生クリップを含むディレクトリへの絶対パスまたは相対パス。.mov、.mp4、.m4v をサポート。
3. 目標時間（秒）。 （通常20～45秒）
4. 音楽。 次のいずれか: (a) 既存の音声ファイル、(b) Sunoで生成（SUNO_API_KEY が設定されている場合のみ提案）、(c) 音楽なし。
5. イントロ。 次のいずれか: なし、静止画像（パス）、Blender MCP生成。
6. アウトロ。 イントロと同じ選択肢。
7. ディレクターモード。 はい、またはいいえ。「はい」の場合、このまま直線的に進めずに references/director_mode.md の手順に従います。

次に、クリップ選択を処理します。2つの方法を提供します:

A) ビジュアルギャラリー（クリップが10個以上の場合、またはユーザーがフレームを見てからキューを設定したい場合に推奨）。 scripts/gallery.py <clips_dir> --resolution WxH --fps 30 --target-length N を実行すると、gallery/gallery.html が生成され、サムネイル、IN/OUTスライダー、速度スライダー、範囲プレビューが含まれます。ユーザーにブラウザで開いてもらい、クリップを選択してキューを設定し、「Export selection.json」をクリックするよう伝えます。ダウンロードされたファイルは build.py で使用可能です。

B) インライン対話（小規模なバッチやブラウザがない場合に適しています）。 各クリップについて自分で確認します:

• cue_in と cue_out（秒単位、トリム範囲）
• speed 乗数（1.0 = オリジナル）
• fixed: true（タイミング/速度が手動調整済みの場合）、false（自由なフィラー用、デフォルト: 中央から0.6秒、速度1.0）

「デフォルトでいいよ」という提案も提供 — すべてのクリップをアルファベット順に、自由なデフォルトで、目標時間まで選択します。

どちらの方法でも、結果は templates/selection.schema.json に適合する selection.json です。進める前に検証します。

ビルド

selection.json が有効になったら、以下を実行します:

python <skill>/scripts/build.py <selection.json> --out output/<name>.mp4

build.py は中間アーティファクトを build/（カレントワーキングディレクトリからの相対パス）に書き込みます: build/normalized/、build/trimmed/、build/montage.mp4、build/composed.mp4。build/ を削除すると、完全な再レンダリングが強制されます。

scripts/ 以下の各サブモジュールはスタンドアロンでも実行可能です — パイプライン全体を再構築せずに1つのステップを繰り返すのに便利です。それぞれに --help 引数があります。

ディレクターモード（オプション）

オプトイン。ロールプロンプトについては references/director_mode.md を参照。スキルは4つの順次ロール — ナレーター → カッター → コンポーザー → スーパーバイザー — を生成し、selection.json を状態として共有します。各ロールは現在のJSONを読み取り、更新を書き戻します。ユーザーが「もっとガイドしてほしい」や「プロデューサーのように進めて」と言った場合に使用します。

音楽生成（オプション）

ユーザーが「Sunoで生成」を選択した場合、音楽生成ステップを references/song_builder_agent.md で定義されたSong-Builderサブエージェントに委任します。そのサブエージェントは:

1. ユーザーにジャンル、ムード、BPM範囲、セクション構成、インストゥルメンタルのオン/オフを尋ね、ビデオの長さを期間として受け取ります。
2. Sunoプロンプト＋スタイルタグを策定します。
3. scripts/music.generate_song(spec) を呼び出します — ユーザーが比較用のオプションを希望する場合は takes > 1 を指定します。
4. 選択されたテイクをビデオの長さにトリミングし、フェードを適用します。
5. 最終的なmp3パスを selection.json の audio として書き込みます。

ホストがサブエージェントメカニズム（Claude CodeのAgentツールなど）を提供している場合はそれを使用します。それ以外の場合は、同じスレッド内でインラインでロールを実行します。

Blender MCP統合（オプション）

支援のみ — このスキルはBlenderシーンをバンドルしません。

ユーザーがBlenderレンダリングのイントロまたはアウトロを希望する場合、references/blender_builder_agent.md で定義されたBlender-Builderサブエージェントに委任します。これがフルフローを担当します: 事前チェック（このホストでBlender + MCPが実際に到達可能か確認）、デザインインタビュー（ビジュアルの方向性、色、長さ）、シーンビルド、反復プレビュー、ProRes 4444アルファMOVへのレンダリング、MOVパスの selection.json への引き渡し。

ホストがサブエージェントメカニズム（Claude CodeのAgentツールなど）を提供している場合はそれを生成します。それ以外の場合はインラインでロールを実行します。メインの対話フローは、質問票のステップ5でユーザーが「Blender MCP生成」を選択した場合に、Blender-Builderを呼び出す必要があります。

セットアップドキュメント（Blenderのインストール、MCPサーバーのインストール、ホストへの登録）は references/blender_mcp.md にあります。Blender-Builderサブエージェントは、ユーザーが初めてスタックを設定する必要がある場合に、そのドキュメントから情報を取得します。

エラーリカバリ

• クリップの正規化（コーデック/解像度のエッジケース）に失敗した場合、build.py は非ゼロの終了コードと、問題のあるファイルを指す明確なstderrメッセージを出力します。ユーザーにそのクリップをスキップするか調査するか尋ねます。
• Sunoが4xxエラーを返したりタイムアウトした場合、ユーザーに再試行、「既存のファイル」に切り替える、または音楽なしで進めるかを提案します。
• 静かにクリップをドロップしてはいけません。--force が指定されていない限り、既存の出力ファイルを確認なしで上書きしてはいけません。

このスキルのスタイルノート

• ホスト固有のツールを決して前提にしない。 すべての対話はプレーンチャットです。
• 作業内容を示す。 トリミングするときは、ビルド前にどのキーポイントに決定したかをユーザーに伝えます。
• 大きな失敗を報告する。 ffmpeg がない場合は、その旨を伝え、ユーザーのプラットフォーム向けのインストールコマンドを表示します。