video-description

name	video-description
description	Use when YouTube 概要欄を Complete Collection 形式で自動生成するとき。「概要欄」「説明文」「SEO最適化」「メタデータ生成」で発動

Overview

コレクション用の YouTube 概要欄を自動生成します。ファーストビューに情景フックとタイムスタンプ（チャプター）を配置し、シーン描写・Perfect for セクション・Usage & Attribution・ハッシュタグで構成します。

設定読み込みゲート

前提確認や Step 1 に入る前に、以下を必ず Read（Codex では同等のファイル閲覧）で開く。SKILL.md の説明や記憶から設定値を推測しない。

1. .claude/skills/video-description/config.default.yaml
2. config/skills/video-description.yaml（存在する場合）

読み込み後は youtube_automation.utils.skill_config.load_skill_config("video-description") と同じ deep-merge 前提で、チャンネル上書きを優先して扱う。存在しない override は未設定として扱い、勝手に作成しない。

前提

config/channel/ が存在すること（load_config() でロード可能）。

存在しない場合、ユーザーに確認:

• 新規チャンネル → /channel-new を案内
• 既存チャンネル（YouTube で既に運営中）→ /channel-new（既存チャンネル取り込みモード）を案内

When to Use

• コレクションの動画が完成し、YouTube 概要欄が必要なとき
• Complete Collection の概要欄を作成するとき

Quick Reference

引数	説明	例
$ARGUMENTS	コレクションディレクトリパス（省略可）	/video-description collections/planning/20260303-clm-merlin-study-collection/
未指定	アクティブなコレクションを自動検出	/video-description

Channel Adaptation

Complete Collection 形式（情景フック＋タイムスタンプ＋Perfect for）で生成する。 ハッシュタグ・CTA・チャンネル URL は config/channel/*.json から取得。

Instructions

あなたは YouTube 概要欄最適化スペシャリストです。config/channel/*.json からチャンネル名・ジャンル・ハッシュタグ等を読み取り、チャンネルに最適化された概要欄を生成します。

対象コレクション

$ARGUMENTS

対象コレクションの workflow-state.json と 20-documentation/suno-prompts.md を読み込み、コレクションのテーマ・雰囲気を把握してから概要欄を生成してください。

Benchmark 概要欄 TTP（徹底的にパクる）

ベンチマーク先の概要欄構造を忠実に転写し、自チャンネル用に最小限のカスタマイズだけ加える。 オリジナリティは概要欄ではなくコンテンツで出す。下記の Complete Collection テンプレートはベンチマークデータが一切ない場合のフォールバックに過ぎない。

Step 1: ベンチマーク概要欄を読み込む

1. docs/benchmarks/*.md の 概要欄TTPサンプル セクションを最優先で参照する（再生数 top 3 のサンプルを重点的に）
2. Markdown にサンプルがない場合は、最新の data/benchmark_*.json の channels[].videos[].description を参照する
3. 両方とも存在しない場合のみ、下記 Complete Collection テンプレートへフォールバックする

Step 2: 構造要素を抽出して転写する

ベンチマークの概要欄から以下の要素を そのまま 転写する（文言は自チャンネル向けに書き換えるが、構造・順序・セクション配置は変えない）:

抽出対象	転写方法
冒頭ハッシュタグの有無と位置	ベンチマークがタイトル直後にハッシュタグを置いているなら同じ位置に置く
段落構成と段落数	段落の数・各段落の役割（情景フック / 音楽説明 / リスニングアドバイス / エンゲージメント質問 / ユースケース / チャンネル紹介）を同じ順序で配置する
エンゲージメント質問の挿入位置と数	ベンチマークが 2 回質問を挟むなら同じ位置に同数挿入する
ADHD / 特定ユースケースへの言及パターン	ベンチマークが「Many listeners also use...as ADHD focus music」と書いているなら同じ文脈で同じ構造の文を置く
Keywords セクションの有無と量	ベンチマークにロングテール Keywords セクションがあれば同量のキーワードリストを生成する
CTA の語調とスタイル	ベンチマークの CTA 文を語調ごと転写し、チャンネル名だけ差し替える
著作権表記のフォーマット	Ownership / Copyright 表記のスタイルを揃える

Step 3: テンプレ使い回し禁止

コレクションごとに冒頭フックと音楽説明を固有に書く。 以下は禁止:

• 複数コレクションで同じ冒頭段落を使い回す（例: 「is built for the part of your day where...」を全動画で再利用）
• ベンチマーク先の文章をそのままコピペする（構造を転写し、文言はコレクションの世界観に合わせて書き直す）
• 抽象的な説明だけで具体的情景がない冒頭（Flow365 top 動画は各回で異なる具体的シーンから書き出している）

冒頭フックは workflow-state.json の planning.music.atmosphere と suno-prompts.md のシーン描写を素材にし、コレクション固有の情景を毎回ゼロから書く。

Complete Collection テンプレート

情景フック＋タイムスタンプ＋Perfect for 構成のテンプレート。装飾ヘッダー・Usage & Attribution 本文は config.default.yaml の section_headers / usage_attribution_lines に集約されており、 チャンネル特性に応じて config/skills/video-description.yaml で上書きできる（BGM 系・ゲーム音楽系・ASMR 系などへ展開可能）。

テンプレート本文・ポイント解説は references/description-templates.md の「Complete Collection 概要欄テンプレート」セクションを参照すること（記載値はデフォルトのサンプル）。

タイムスタンプ生成手順

1. 個別トラックがある場合（02-Individual-music/）: metadata_generator.py の analyze_audio_files() で自動計算
   • master をループ生成しているコレクション（yt-generate-master --loop N / --target-duration）で全ループ分のチャプターを展開する場合は generate_timestamps(loops=N) / format_timestamps_text(loops=N) を使う。2 周目以降の開始秒は 1 周目と同じクロスフェード算術で連続計算される。2 周目以降のタイトルは 1 周目と同一になるため、チャプター名をユニークにしたいチャンネルでは各行の loop フィールド（1 始まり）を手掛かりに LLM リネームで装飾する（1 ループ分のみ載せる従来運用は loops=1 のままで変更なし）
2. ファイル名規約 \d+-pattern-[a-d] を持つコレクションでは、format_timestamps_text() がテーマ見出し（── Pattern A: <name> ──）と楽曲行（00:00 Track 1）を組み合わせた 個別楽曲単位 のタイムスタンプを返す。テーマ見出し行は YouTube のチャプター parser に拾われないよう先頭 timestamp を持たない（重複 timestamp は chapter list 全体を無効化する）
   • テーマ表示名は workflow-state.json の planning.music.patterns[<letter>].display_name（無ければ .name を Pattern X: <name> に整形）から解決される。両方無ければ Pattern X にフォールバック
   • pattern 規約に従わない legacy コレクションはテーマ見出し無しのフラット出力（後方互換）
3. チャプター名は原則トラックタイトル（ファイル名から生成）を使用
4. 同名トラックの LLM リネーム:
   • BAHMetadataGenerator.detect_duplicate_track_titles() を呼び、case-insensitive で重複しているタイトル群を取得する
   • 戻り値が空ならこの手順をスキップ
   • 重複があれば、本 skill を実行している LLM 自身が以下の情報を読み、コレクションのテーマ・シーン展開（時系列／空間／情緒のいずれか）を把握してから固有名に書き換える:
     • workflow-state.json の planning.music.patterns[<letter>]（pattern ごとの mood / instruments / tempo 等）
     • 20-documentation/suno-prompts.md（pattern 別の Style / Lyrics 文脈）
     • 当該トラックの pattern_key（テーマ群が同じか別か判定）
   • 命名方針:
     • 元曲名のコア語彙は保つ（同一テーマ群であることを視聴者に示すため）
     • コレクションの物語アークに沿った短い修飾語（英語 2〜3 語）で区別する。例: Quiet Hours × 2 → Quiet Hours — Dusk / Quiet Hours — Dawn、Rain Window × 3 → Rain Window I 型ではなく Rain Window — Distant / Rain Window — Closer / Rain Window — Drift
     • 末尾に v1〜v9 / ロマン数字 I〜VIII を付けない（preflight の variation suffix 検出で reject される）
   • 決めたリネーム結果は BAHMetadataGenerator.apply_track_display_names({index: "新表示名", ...}) に渡す。これで:
     • self.tracks[i]["title"] が上書きされる
     • workflow-state.json の track_display_names に {filename: display_name} 形式で永続化される（次回ロード時 _apply_persisted_display_names() で再適用される）
   • 02-Individual-music/ のファイル名や ID3 タグは変更しない（派生アセットへの波及防止）
5. 00:00 から始まること（YouTube チャプター要件）、最低3チャプター

Perfect for テーマ別カスタマイズ

skill-config (.claude/skills/video-description/config.default.yaml / 上書き config/skills/video-description.yaml) の perfect_for_themes からコレクションのテーマにマッチするキーを選択:

• テーマが辞書にない場合は config/channel/content.json の descriptions.perfect_for（デフォルト）を使用
• 絵文字は skill-config の theme_emoji から引く（例: 📚(study), 🌙(sleep), 🍺(tavern), 🌊(ocean), 🌿(forest), 🔮(druid/magic), 🌧️(rain), 🔥(hearth)）

タイトル形式

config/channel/content.json の title.template に基づいてタイトルを生成する。

• [総時間]: 2+ Hours / 1+ Hour 等（切り捨て表記）
• ユースケースはコレクションテーマに応じて調整

タイトル案を決めたら、まず 100 codepoint 以内であることを確認する（YouTube タイトル上限。超過は upload preflight で必ず fail するため、この段階で RHS の修飾語を削って短縮する。用途語・尺表記・テーマ語は残す）。

続けて、descriptions.md に保存する前に過去 live タイトルとの重複 warning を確認する（yt-title-duplicate-check は 100 codepoint 超過も検出し、超過時は --strict に関係なく exit 1 になる）:

uv run yt-title-duplicate-check "$COLLECTION_DIR" --title "$PROPOSED_TITLE"

• タイトル全体 / タイトル後半 / 長い タイトル末尾 が過去タイトルと一致した warning は、アップロード直前まで持ち越さずこの段階で見直す
• warning が無ければそのまま保存してよい
• 最終 upload preflight は別途維持されるため、このチェックを省略しない

タグ（YouTube タグ欄）

config/channel/content.json の tags.base + tags.themes.<theme> を結合してタグリストを生成する。

テーマに応じてキーワードを調整すること。

必須要素

各要素は YouTube SEO と視聴者信頼の両面で CTR・視聴維持率に寄与する:

1. 誇張表現回避: Epic, Ultimate 等を避け Ancient, Enchanted 等を使用 — 誇張は CTR を下げる傾向があり、チャンネルブランドの信頼性も損なう
2. AI 透明性: Usage & Attribution セクションを含める — AI 生成コンテンツの透明性維持はコミュニティとの信頼関係の基盤
3. SEO 最適化: config/channel/content.json の tags.base に基づく戦略的キーワード — YouTube 検索とおすすめアルゴリズムの両方で発見性を高める
4. ハッシュタグ: 13個（base + theme固有）— YouTube は概要欄の最初の3ハッシュタグをタイトル下に表示するため、数と順序が重要
5. タイムスタンプ必須: 00:00 始まり、3チャプター以上 — YouTube がチャプターを自動認識し、検索結果にプレビュー表示される

Cards（YouTube Studio で手動設定）

概要欄生成時に、カードセクションも descriptions.md に含める。設定は skill-config の cards セクション参照。

• カード種類: 動画カード（Video card）のみ
• 枚数: 1動画1枚（最小限運用）
• タイミング: skill-config cards.timing（デフォルト 12:00）
• リンク先: 最新のコレクション（新コレクション公開時に全動画を更新）
• テキスト: skill-config cards.text_template（デフォルト Up next from {channel_name}）

品質チェック

• タイトルが 100 codepoint 以内（YouTube 上限。yt-title-duplicate-check が超過検出）
• 誇張表現なし（Epic/Ultimate等 不使用）
• AI 透明性あり（Usage & Attribution セクション）
• チャンネル CTA 含む
• ハッシュタグ 13個（base + theme）
• モバイル読みやすさ（セクション区切り）
• タイムスタンプあり（00:00 始まり、3チャプター以上）
• カードセクション含む（タイミング・テキスト・リンク先）

概要欄保存

概要欄は必ずコレクションの 20-documentation/descriptions.md に保存する。 保存フォーマット（ヘッダー、概要欄本文、タイトル案、タグ、Cards、品質チェック）は references/description-templates.md の「descriptions.md 保存フォーマット」セクションを参照すること。

保存後、workflow-state.json の description.generated = true に更新する。

障害時ガイダンス

概要欄はエージェント生成（テキスト）で、外部サービスを呼ばない。

状況	兆候	対処
入力データ/設定の不在	参照先のローカルファイルが見つからない	該当ファイルを用意するか前段スキルを先に実行（外部サービスに依存しないため API 障害・quota の影響は受けない）

Next Step

概要欄生成後: → /video-upload <collection-path> で YouTube へアップロード