By name: video-analyze description: "Use when 動画コンテンツ分析・映像解析が必要なとき。Gemini に YouTube URL を直接渡してフック構造・BGM 展開・シーンタイムライン・サムネ整合性・編集指標を抽出する。「signature 要素抽出」「retention drop の構造的原因」「競合動画の冒頭 30 秒解析」「BGM のピーク位置」など、メタデータ・コメント・静止画では届かない動画本体の中身に切り込みたい場面で使用すること"
Overview
yt-video-analyze で YouTube 動画を Gemini に直接渡し、以下の構造化データを抽出する:
hook_structure— 0-30 秒のカット割り・テキスト出現タイミング・signature 要素bgm_arc— イントロ尺・ピーク位置・アウトロのタイムスタンプscene_timeline— シーン境界 + 一言要約thumbnail_alignment— サムネで提示した要素が本編に映っているかの整合性editing_metrics— 平均カット長・テキスト出現頻度
既存スキルが扱えていなかった「動画の中身」というドメインを埋め、/benchmark・/analytics-analyze・/alignment-check・/thumbnail-compare・/viewer-voice の精度を底上げする。
前提
config/channel/がロード可能であること (load_config())- Vertex AI ADC 初期化済み (
gcloud auth application-default login+set-quota-project)。project_id は ADC quota project から自動解決（GOOGLE_CLOUD_PROJECTは任意で上書き可） - 解析対象動画が Public または Unlisted であること (Gemini API は Private 動画を取得できない)
実行フロー
Step 1: スクリプト実行
# ベンチマーク競合の上位動画を解析
uv run yt-video-analyze --source benchmark --channel <slug> --top 5
# 自チャンネル live コレクションを解析
uv run yt-video-analyze --source own --collection <name>
# 単発動画 (任意 URL)
uv run yt-video-analyze --url <youtube_url>
| オプション | 説明 |
|---|---|
--source benchmark |
data/benchmark_*.json から --channel slug でフィルタし --top 件 (default 5) を解析 |
--source own |
collections/live/<name>/20-documentation/upload_tracking.json の complete_collection.video_id (および videos[]) を解析 |
--url |
任意 YouTube URL を直接解析 (slug は固定 url) |
Step 2: 出力確認
| 出力先 | 用途 |
|---|---|
data/video_analysis/<slug>/<video_id>.json |
構造化データ (1 動画 1 ファイル) |
reports/video_analysis/<slug>.md |
人間向けサマリー (slug 単位で集約) |
設定
skill-config (.claude/skills/video-analyze/config.default.yaml):
| 項目 | 既定 | 説明 |
|---|---|---|
model |
gemini-2.5-pro |
動画入力対応 Gemini モデル |
delay_sec |
10 | 動画間の API レート対策ウェイト (秒) |
prompt |
汎用プロンプト | ジャンル/世界観に合わせて config/skills/video-analyze.yaml で上書き推奨 |
注意事項
- Gemini API には YouTube URL を直接渡す (動画ダウンロードしない)
- Public/Unlisted のみ対応 (Private 動画は API 側で拒否される)
- Shorts は Gemini の 1fps サンプリング制約により短尺フック構造の解析精度が落ちる。
/shortで生成・投稿した自チャンネル Shorts は本 skill の対象外として扱い、リテンション / CTR 分析は/analytics-analyzeに任せる - API レート制限対策で動画間に
delay_sec秒スリープ
呼び出し側スキル
以下の skill は data/video_analysis/<slug>/*.json の bgm_arc / scene_timeline を入力として
参照する。/video-analyze が未実行のときは警告で続行するが、ベンチマークデータがあれば自動実行を提案する。
/channel-direction— Step 1 の分析サマリーでbgm_arc平均（intro / peak / outro 秒）を提示し、 Step 2 の議論ポイント「6. 競合の BGM 構造」と Step 3 決定事項「BGM 構造方針」の根拠データとして使う/suno— Instructions 冒頭でbgm_arc平均を読み込み、4 パターンの起伏配置の初期値とする。scene_timeline[].summaryは情景フレーズ設計ルール 5 の素材として利用（コピペ禁止、世界観翻訳）/lyria— Step 2「ベンチマーク BGM 構造の参照」でbgm_arc平均を読み込み、composition.jsonのフェーズ境界・各phase.at_minの初期値として活用
関連ファイル
yt-video-analyze(youtube_automation.scripts.video_analyze) — CLI 本体data/video_analysis/<slug>/<video_id>.json— 動画別構造化データreports/video_analysis/<slug>.md— slug 別 Markdown レポートdata/benchmark_YYYYMMDD.json—--source benchmarkの入力collections/live/<name>/20-documentation/upload_tracking.json—--source ownの入力