製品紹介動画生成スキル は何をしますか?
ユーザーが作ったものを指さすと、あなたはナレーション付きの洗練されたアニメーション説明動画を返します。それを初めて見る人でも1分以内に内容を理解できます。動画はそのプロジェクト専用にデザインされます。独自の視覚的メタファー、独自のカスタムアニメーション。名前だけを差し替えた汎用テンプレート動画は決して作らないでください。
分析(事実) → デザインブリーフ → ストーリーボード.json(組み込み+カスタムシーン) → 検証 → コンタクトシートQA → 修正 → レンダリング(+音声、+音楽) → 納品
スクリプトはこのファイルと同じディレクトリの scripts/ にあります。$SK はこのスキルのフォルダ(この SKILL.md がある場所)を指します。
0. セットアップ確認(10秒)
python3 -c "import playwright, PIL, numpy" && which ffmpeg && python3 $SK/scripts/voiceover.py --list
不足している場合: pip install playwright pillow numpy edge-tts --break-system-packages && playwright install chromium。ffmpegがない場合はユーザーに伝えてください(MP4出力に必要;--html-only でもHTMLプレイヤーは出力されます)。voiceover --list で現在使用可能な音声エンジンが表示されます。
1. 説明する対象を理解する
まず推測し、質問は最小限に: 対象(単一の製品、またはポートフォリオ)、視聴者・目的(GitHub上の開発者、顧客、ソーシャルメディア)、ソース(ローカルパス、アップロードされたzip、GitHub URL、ライブサイト、または単なる説明)。デフォルト: 16:9、45~75秒、開発者+技術に詳しくない一般視聴者、ナレーションあり。本当に曖昧な場合のみ、1つだけ短い質問をしてください(例: 15個のリポジトリがあり、どれかヒントがない)。それ以外の場合は仮定を一文で述べて進めてください。ユーザーにインタビューしないでください。
2. 事実を収集する(絶対にスキップしない: これが動画の信頼性を保つ)
python3 $SK/scripts/analyze_project.py /path/or/git-url [more...] -o facts.json
python3 $SK/scripts/capture_site.py https://their-site.com -o site-capture # ライブサイト: スクリーンショット + ページ情報
アナライザーは、説明、言語、機能、実際のREADMEのコマンド、CLIフラグ、ルート、接続先ドメイン、出力、環境変数、CI/ cron、および表示しても安全な REAL STATS を出力します。それを読んだ後、事実が少ない場合は自分でREADMEと1~3個の主要なソースファイルも読んでください(コアループは何か?ユーザーが実際に実行するものは何か?出力はどのようなものか?)。クローンが失敗した、またはネットワークがオフの場合は、zip または README を要求してください。サイトキャプチャがブロックされた場合は、スクリーンショットを要求するか、カスタムシーンでUIを描画してください。
3. デザインブリーフ、次にストーリーボード
references/narrative-playbook.md(アーク、真実性ルール)、references/storyboard-schema.md(全シーンタイプ/フィールド)、references/custom-scenes.md(カスタムシーンの書き方)を読んでください。assets/examples/ にある参考ストーリーボードは良い例を示していますが、それらはインスピレーションであり、テンプレートではありません: その内容、構造、文言を再利用しないでください。
まず、以下の項目を簡単に決定してください(書き留めてください):
- 一言で表す約束。
- 製品が物理的に行うこと(場所間で移動するもの)と、それを示す単一の視覚的メタファー。
- 「aha」モーメントのシーン。
- テーマ、アクセントカラー(ユーザーのブランドカラーがわかればそれ)、
bgスタイル、ペース: 製品の個性に合わせます。 - どの2~4シーンをカスタム(この製品のために描画)にするか、どの汎用ビートに組み込みコンポーネント(タイトル、問題、手順、CTA...)を使うか。
次に storyboard.json を書きます:
- アーク: フック → 問題 → 仕組み → 簡単である証明 → 具体的な結果 → 優れている理由 → CTA;7~10シーン、45~75秒。
- 品質基準: 製品が本当にプレーンなCLIでない限り、少なくとも1シーンはカスタムにします。ahaシーンは常にカスタム、または慎重に選んだ組み込みシーンにします。ボットは会話を示し、スクレイパーはページが行になる様子を示し、APIはリクエストとレスポンスを示し、ダッシュボードはライブの数字を示します。
- すべてのシーンに
narration: 話し言葉スタイル、15~35語。これがナレーション、キャプション、SRTになります。 - 真実のみ: コマンド、フラグ、機能、ルート、数値は事実またはユーザーから得たものにします。ターミナル出力やテーブルの行は説明のために例示することはできますが、一般的なもので構いません。ベンチマーク、顧客数、能力を決して捏造しないでください。統計シーンでは
REAL STATS/ README / ユーザーの数値のみを使用します。 meta.urlをリポジトリ/サイトに設定し、最後に明確なCTAを1つ入れます。
4. 検証、そしてレンダリング前に確認
python3 $SK/scripts/storyboard.py explainer/storyboard.json
python3 $SK/scripts/render_video.py explainer/storyboard.json --contact-sheet
コンタクトシート(約20秒)はレイアウト監査(オフステージ、クリッピング、テキストの切り捨て、キャプションと衝突、カスタムシーンのJSエラー)を実行し、explainer-output/contact-sheet.png に書き込みます。それを表示して確認: 窮屈な部分や切れている部分がないか、テキストが読めるか、シーン同士が視覚的に異なっているか、カスタムシーンが意図的に見えるか。コンタクトシートはシーンごとに1フレーム(後半)だけ表示するので、すべてのカスタムシーンについては初期と中間のフレームも確認してください: --still 3.2,6.5。修正して、きれいになるまで繰り返します。
5. ナレーション付きでレンダリング
cd explainer
setsid nohup python3 $SK/scripts/render_video.py storyboard.json --quality final --gif \
> render.log 2>&1 < /dev/null &
sleep 100; tail -c 300 render.log
DONE と表示されるまでポーリングを続けてください(sleep 100; tail -c 300 render.log)。サンドボックス環境(claude.ai)では、バックグラウンド処理はツール呼び出しが実行されている間だけ進行するため、スリープ状態のポーリングがレンダリングを進めます。実行中はターンを終了しないでください。プリセット: draft(960×540、15 fps)、standard(1280×720、30 fps、デフォルト)、final(1920×1080、30 fps)。CPUコアが多いほど高速です(--workers N)。縦向き: meta.aspect: "9:16" または --vertical。マシンが遅い場合: --fps 24。
ナレーションは自動です(--voice auto、デフォルト)。レンダラーはシーンごとに1つの音声ファイルを生成し、ナレーションが途切れないようにシーンを引き伸ばし、音声の下で音楽を自動的に下げ、音声をキャッシュして再レンダリングを高速化します。エンジン優先順位: ElevenLabs(ELEVENLABS_API_KEY)→ OpenAI TTS(OPENAI_API_KEY)→ Edgeニューラル音声(pip install edge-tts、無料、キー不要、インターネット必要)→ Piper(オフラインニューラル)→ macOS say → espeak-ng。オプション: --voice-name en-US-AndrewNeural(任意のエンジンの音声名)、--voice-rate +8%(Edge)、--voice none(音楽のみ)、--voice-dir folder/(ユーザー自身の scene-01.mp3… ファイルを使用)、meta.voice(選択をストーリーボードに保存)。
レンダリングで WARNING voiceover: no speech engine available と表示された場合、動画は(音楽のみで)レンダリングされ、voiceover.txt にスクリプトが保存されます。その場合はユーザーに明確に伝え、ワンライナーで修正方法を示してください: インターネットを有効にして pip install edge-tts(無料)を実行するか、APIキーを設定するか、espeak-ng をインストールします。その後、同じコマンドを再実行してください(音声とエンコードのみがやり直されます。プレイヤーとストーリーボードは変わりません)。claude.ai のサンドボックスは通常インターネットにアクセスできないため、この状況を想定してください。その場合は、そのことを伝え、音声なしの動画とスクリプトを納品し、ユーザーがローカルで Claude Code を実行するかAPIキーを使えば音声を追加できることを説明してください。ログに voiceover: using '<engine>' と表示されない限り、動画にナレーションがあると主張しないでください。
音楽: ロイヤリティフリーのBGMを生成します(--mood calm|upbeat|tech または meta.music_mood)。--music none または --music file.mp3 も可能です。
6. 納品
出力は explainer-output/ ディレクトリにあります: <name>.mp4、<name>-poster.png、player.html(自己完結型インタラクティブプレイヤー。 <iframe src="player.html?embed"> で埋め込み可能。動きとキャプションがありますが音声はありません)、captions.srt、voiceover.txt、storyboard.resolved.json、voice/、オプションで .gif。
確認: ffprobe -v error -show_entries stream=codec_type -of csv=p=0 <name>.mp4 で音声ストリームが表示されること、再生時間が一致すること、ポスターを確認すること。納品物を /mnt/user-data/outputs/ にコピーし、present_files でMP4を最初に、続いてポスター、キャプション、player.html、storyboard.json を提示してください(ユーザーが編集して再レンダリングできるように)。メッセージは短く: シーンごとに1行、仮定したこと、使用した音声エンジン、調整方法を記載してください。バリエーション(9:16 ソーシャルカット約30秒、別の音声やブランドカラー、別のリポジトリ用の動画など)は便利な場合のみ提案してください。
編集と再レンダリング
storyboard.json(テキスト、順序、色、カスタムシーンのコード)を編集し、コンタクトシートを再実行してからレンダリングします。ナレーションを変更すると、変更されたシーンだけが再合成されます。シーンの duration を設定して長くすることができます。アニメーションとナレーションに必要な時間より短くすることはできません。
ポートフォリオ / 「すべてのツール」
すべてのリポジトリを1回の呼び出しで分析し、範囲を示す3~4個の主要プロジェクトを選び、それぞれに独自の視覚的メタファーを持つカスタムまたは最適なシーンを割り当て、残りを features グリッドでまとめ、プロフィールへのCTAで締めくくります。その後、製品ごとに詳細動画を提案してください。
トラブルシューティング
Playwright is not installed→ ステップ0のコマンドを実行。- フレームが真っ黒/真っ白、または
scene error行 → カスタムシーンのJSでエラーが発生しています。監査で例外が出力されます。コードを修正してください。 - テキストが切り取られている/省略されている → テキストを短くする、項目を削除する、またはカスタムレイアウトを作成します。
- 音声がロボットのように聞こえる → espeak を使用しています。代わりに Edge/OpenAI/ElevenLabs/Piper を使用してください。
- 音声がシーンのタイミングと合わない → タイミングは自動です(シーンは音声に合わせて引き伸ばされます)。キャプションが早すぎる場合は、ナレーションを短くしてください。
- ログが動かない/レンダリングが強制終了された → フォアグラウンドで実行されたか、ポーリングが行われていません。デタッチして再起動し、ポーリングしてください。
- 出力が長すぎる → 最も弱いシーンを削除してください。バリデーターは約90秒を超えると警告を出します。
正直な限界
モーショングラフィックス(ダイアグラム、ターミナル、コード、UIモックアップ、カスタムアニメーション)が対象であり、スクリーンレコーディングやフォトリアルな映像ではありません。実際のUIを表示するには、スクリーンショットを渡すか、インターフェースを描画してください。音声品質は利用可能なエンジンに依存します。