/thumbnail

Use when コレクションの YouTube サムネイル（thumbnail.jpg）を CTR 最適化し、実効 text_render.mode に従い、既定 ai_burn_in で文字入り候補を生成・承認してから textless 背景を作るとき、または deterministic で textless main.png/jpg を先行生成して実フォント合成するとき、--compare で生成済み候補を競合と 320px 比較するとき、--test で Studio の A/B テストを設計・記録するとき、--iterate で伸びた動画の勝因を次のサムネへ還元するとき、または --loop で textless main.png/jpg から Veo / fal.ai / Gemini Omni Flash のループ動画背景を生成するとき。「サムネイル生成」「画像生成」「アイキャッチ」「サムネ比較」「モバイル表示テスト」「サムネ A/B テスト」「Test & Compare」「伸びた動画のサムネ改善」「ループ動画」「Hailuo」「背景動画」「loop.mp4」で発動。競合の勝ちパターン分析は channel-research の thumbnail mode、人間の眼を鍛える訓練は /truth-eye を使う。SVG・汎用画像生成には使わない

何ができるか

collection の YouTube サムネイルを、競合の勝ちパターンとチャンネル固有の制作制約に合わせて作るスキルです。通常入口ではテキスト付きの thumbnail.jpg と動画背景用の textless main.png / main.jpg を別々に確定し、候補の承認、320px での視認性確認、制作状態の更新まで進めます。生成後の比較、A/B テスト、勝因の還元、ループ背景作成も同じ入口から一段ずつ実行できます。

mode	すること	主な成果物
フラグなし	サムネ候補と textless 背景を生成・確定	`thumbnail.jpg` / `main.png` または `main.jpg`
`--compare`	候補を競合サムネと 320px で比較	`docs/plans/thumbnail-comparison.md`
`--test`	YouTube Studio の A/B テストを設計・記録	`thumbnail-test-active.json` / `thumbnail-test-history.json`
`--iterate`	公開済み動画の勝因を分析し、次回の生成へ引き継ぐ	`data/thumbnail-iterate/champion.json` ほか
`--loop`	textless 背景から短いループ動画を生成	`10-assets/loop.mp4`

新しいサムネイルを作りたいとき

/thumbnail
/thumbnail fiddle playing

フラグなしで対象 collection を選び、設定済みの provider と参照画像から候補を作ります。テーマを引数で渡すこともできます。通常は候補ごとに確認を挟み、確定した画像だけを正式名へコピーします。チャンネルが全自動生成を明示設定している場合だけ、確認を省略して自動確定します。

小さい表示で競合に負けないか確認したいとき

/thumbnail --compare

--compare は生成済み候補を 320px に縮小し、競合の上位サムネと並べて可読性、コントラスト、被写体の認識しやすさを確認します。通常生成では承認前にこの検証を通してください。音楽・タイトルとの意味的な一致を見る /audit --alignment とは役割が異なります。

Studio の A/B テストを回したいとき

/thumbnail --test

--test は最大 3 案の Test & Compare を設計し、開始時の仮説と終了後の結果を collection に記録します。いま実施中のテストを上書きせず、履歴を残しながら次のテストへ進めるための mode です。

伸びたサムネの勝因を次へ使いたいとき

/thumbnail --iterate

--iterate は公開済み動画の CTR や比較対象を読み、再利用できる勝ち筋を champion として保存します。通常生成はこの記録を参照してプロンプトへ反映します。分析対象の動画 ID は引数では渡さず、対象 collection の workflow-state.json に記録された公開済み動画から自動で特定されるため、対象 collection を 1 件に確定でき、比較期間の Analytics が揃った状態で実行してください。

静止画からループ背景を作りたいとき

/thumbnail --loop

--loop は確定済みの textless main.png / main.jpg を Veo、fal.ai、または Gemini Omni Flash へ渡し、動画本編で繰り返せる loop.mp4 を作ります。Shorts の 9:16 ループは yt-generate-shorts-loop --engine fal でも生成できます。静止画の確定前には実行せず、生成後は継ぎ目と意図しない文字・動きをプレビューしてください。

つまずいたら

候補生成前に止まる — config/channel/、対象 collection、参照画像を確認してください。チャンネル制作制約が未作成でも生成は続けられますが、先に /channel-strategy --constraints を実行すると判定基準を揃えられます
provider の認証や quota で失敗する — 自動では別 provider に切り替わりません。ADC、API key、利用上限を直すか、設定で provider を明示変更してから再実行してください
--compare で不合格になる — 正式画像へ確定せず、文字量、コントラスト、顔や主役の大きさを直した候補を生成して比較し直してください
--loop が始まらない — main.png または main.jpg が確定済みか、チャンネルで loop-video が有効かを確認してください

リファレンス

発動フレーズ

サムネイル生成
画像生成
アイキャッチ
サムネ比較
モバイル表示テスト
サムネ A/B テスト
Test & Compare
伸びた動画のサムネ改善
ループ動画
Hailuo
背景動画
loop.mp4

前後工程

前工程: /channel-strategy --constraints, /wf-new, /thumbnail --iterate
後工程: /thumbnail --loop, /thumbnail --compare, /thumbnail --test, /thumbnail --iterate, /audit --alignment
委譲先: なし

成果物

書き込む: collections/<id>/10-assets/thumbnail.jpg, collections/<id>/10-assets/main.png, collections/<id>/10-assets/main.jpg, collections/<id>/10-assets/loop.mp4, collections/<id>/20-documentation/thumbnail-prompts.md, collections/<id>/20-documentation/thumbnail-test-active.json, collections/<id>/20-documentation/thumbnail-test-history.json, collections/<id>/workflow-state.json, assets/thumbnail-gallery/<id>.<ext>, docs/plans/thumbnail-comparison.md, data/thumbnail_compare/*, data/thumbnail-iterate/runs/<video-id>.json, data/thumbnail-iterate/champion.json, data/thumbnail-iterate/synthesis-required.json
読み込む: 検証済み docs/channel/creative-constraints.json, docs/benchmarks/thumbnail-analysis.json, data/thumbnail-iterate/champion.json, collections/<id>/20-documentation/thumbnail-test-history.json, collections/<id>/workflow-state.json, config/skills/thumbnail.yaml, data/benchmark_*.json, docs/benchmarks/thumbnails/*.jpg

想定 API call 数

API	call 数 / 実行	変動要因
画像生成（Gemini / OpenAI、`image_generation.provider` で切替）	候補 1 枚あたり max_attempts × 1 call（既定 1、失敗時の内部リトライで最大 ×3）	max_attempts / 候補枚数 / 再生成回数。provider が codex は API 経路外で課金なし
画像生成（textless 背景 main.png/jpg）	承認後の再生成で +1 call	再生成回数
Vertex AI Gemini Vision（yt-thumbnail-check）	画像 1 枚 = 1 call	`self_check.enabled: false` なら 0

上限 / 承認: 生成前に confirm_cost() が cost_per_image_usd × attempts を提示して y/N 確認する。auto_selection.mode: full では全自動 opt-in を事前同意として -y でこの質問を省略する。それ以外は従来どおり確認する。self_check.enabled: false で check をスキップできる。

前提

config/channel/ が存在すること（load_config() でロード可能）。 config/skills/thumbnail.yaml はオプション。yt-skills sync で配布される config.default.yaml がそのまま使われるため、default 動作で問題なければ作成不要。カスタマイズしたい場合のみ config.default.yaml をコピーして config/skills/thumbnail.yaml に置き、必要な値だけ上書きする（deep-merge される）。 config/channel/ が存在しない場合、ユーザーに確認:

新規チャンネル → /setup --channel を案内
既存チャンネル（YouTube で既に運営中）→ /setup --import を案内