메뉴
Use when Suno UI に投入する音楽プロンプト (Style + Lyrics) を生成したいとき。SunoAI V5 向けの YAML 定義（インストは `tracks_per_collection` で曲数指定の独立 entry 並列、ボーカルは pattern × tracks_per_pattern 設計）から suno-prompts.md / suno-prompts.json を作成する（次工程 `/suno-helper` でブラウザ自動生成 + playlist 一括追加、その後 `/masterup` で DL + マスター化）。プロンプト作成・Style 文・Lyrics テンプレートなど Suno 連続生成の前段で使用すること。Lyria チャンネルでは /lyria を使う
Use when Suno UI に投入する曲をブラウザで連続生成 + playlist 追加したいとき。yt-collection-serve で suno-prompts.json を配信し、suno-helper Chrome 拡張で 1 タブ完結の自動実行（pattern 注入 → Generate → 完了待機 → 次へ → 全件完了で playlist 一括追加）を回す operator 手順。`/suno` でプロンプトが揃った後、または既存 collection の途中再開で使用する
Use when まだコレクションディレクトリが存在せず、新規コレクション制作を立ち上げたいとき。「新しいコレクション始めたい」「制作開始」「新規ワークフロー」など、企画選択からディレクトリ作成・素材準備までを行う初期化フェーズで使用する。既存コレクションの進行は /wf-next
Use when 各コレクションの音楽ムード × サムネイル雰囲気 × タイトル訴求の整合性を監査したいとき。「整合性チェック」「一致してるか確認」「タイトル見直し」「サムネと音楽の一致」「タイトル改善」「CTR改善」など。CTR に最も影響するチェックポイント。方向性見直し時に必ず使用すること
Use when 収集済みのAnalyticsデータを詳細分析し、戦略的改善提案が必要なとき。/analytics-collect でデータ収集後に実行。CTR改善、パフォーマンス分析、戦略検討、データ分析、コレクション比較、投稿の振り返りなど、データに基づく判断が求められる場面で必ず使用すること
Use when YouTube Analyticsデータの収集・最新化が必要なとき。/analytics-analyze 実行前のデータ準備ステップとして使用。ユーザーが「データ更新」「最新の数字」「統計を取得」「分析の準備」と言及したとき、または analytics_system.py の実行が必要な場面で必ず使用すること
Use when Analytics分析レポートの表示・閲覧が必要なとき。過去レポートの比較やパフォーマンスレビュー時に使用。「レポート見せて」「過去データ確認」「パフォーマンスレビュー」「前回の分析結果」など、既存レポートの参照・比較が必要な場面で必ず使用すること
| name | suno |
| description | Use when Suno UI に投入する音楽プロンプト (Style + Lyrics) を生成したいとき。SunoAI V5 向けの YAML 定義（インストは `tracks_per_collection` で曲数指定の独立 entry 並列、ボーカルは pattern × tracks_per_pattern 設計）から suno-prompts.md / suno-prompts.json を作成する（次工程 `/suno-helper` でブラウザ自動生成 + playlist 一括追加、その後 `/masterup` で DL + マスター化）。プロンプト作成・Style 文・Lyrics テンプレートなど Suno 連続生成の前段で使用すること。Lyria チャンネルでは /lyria を使う |
コレクション用の SunoAI v5 音楽プロンプトを YAML で定義し、スクリプトで最終プロンプトを生成する。インストゥルメンタル / ボーカル（歌詞あり）両モード対応。
tracks_per_collection) を指定し、ceil(N/2) 個の独立 entry をフラットに並べる（pattern 概念は廃止）。/suno-helper が各 entry を Suno に順次投入し、Suno 仕様で 1 Generate = 2 clip 生成されるため両 clip 採用で N clip となるpattern_strategy: mixed/single) × 再生成 (tracks_per_pattern) で構成し、ベスト曲を選曲する運用（歌唱の発音・ピッチ精度のため）音楽エンジンの選択は以下の階層で決まる:
/channel-direction で suno/lyria を検討 → /channel-setup が config/channel/youtube.json の music_engine に書き込む/wf-new の yt-init-collection --music-engine suno でコレクション毎に上書き可能（省略時はチャンネル設定を継承）/wf-new が workflow-state.json の music_engine = "suno" を判定して /suno を自動実行する。手動で /suno <theme> を叩いた場合もこのスキルに入るAI の役割は 情景フレーズ（scenes）+ テンポ（tempo）+ 歌詞（lyrics、ボーカルモード時）の設計 に集中すること。genre_line や共通設定はスクリプトが config/skills/suno.yaml から自動付加する。
config/skills/suno.yaml の genre_line を読み取り、ボーカル要素（vocals, vocal, singing, rap, male/female vocals 等）が含まれていればボーカルモード、なければインストゥルメンタルモードとして処理する。
| モード | YAML 構造 | 歌詞 | Suno 設定 |
|---|---|---|---|
| インストゥルメンタル | tracks_per_collection 由来の ceil(N/2) 個の独立 entry（各 entry = 1 scene = 1 Generate = 2 clip 両採用） | 不要 | Custom Mode + Instrumental ON |
| ボーカル（歌詞あり） | pattern_strategy × tracks_per_pattern の旧パターン設計（情景フレーズ + 歌詞をパターン単位） | 必須（パターンごと） | Custom Mode + Instrumental OFF + Lyrics 欄に投入 |
config/skills/suno.yaml に style_variants が定義されている場合、各 entry（インスト）またはパターン（ボーカル）に style キーで variant を指定できる。variant が指定されているときはデフォルトの genre_line の代わりに variant 固有の genre_line が使われる。
戦略選択（style_strategy を参照）:
| 戦略 | 説明 | YAML での指定方法 |
|---|---|---|
mixed | 1 コレクション内で複数の variant を混合 | 各 entry / パターンに異なる style: A〜E を割り当て |
single | 1 コレクション = 1 variant で統一 | 全 entry / パターンに同じ style: X を割り当て |
AI は genre_line を手書きしてはならない。 方向性は必ずスクリプト（yt-video-analyze の suno_preset 出力）由来とする。/suno 実行に入る最初のステップとして以下を機械的に判定し、要件を満たさない場合はパターン設計に進まず中断する:
config/skills/suno.yaml の genre_line を読むconfig/channel/analytics.json の benchmark.channels[].slug を列挙data/video_analysis/<slug>/*.json の存在を確認| 状態 | 判定 | アクション |
|---|---|---|
genre_line 非空 | OK | パターン設計に進む（既存 suno_preset fallback は引き続き有効） |
genre_line 空 + 少なくとも 1 slug で data/video_analysis/<slug>/*.json 存在 | OK | suno_preset.genre_line を fallback として採用しパターン設計に進む |
genre_line 空 + 全 slug で data/video_analysis/<slug>/*.json 不在 | NG（中断） | パターン設計に進まず、ユーザーに以下を案内して停止する |
NG 時の案内テンプレ:
`/suno` を進められません: `genre_line` が空で、benchmark の video-analyze 結果も未取得です。
AI が方向性を手書きすると意図しないジャンルに流れるため、以下のいずれかを先に実行してください。
1. `data/benchmark_*.json` が無ければ: `/benchmark` を先行実行
2. `data/benchmark_*.json` 取得済みなら: `uv run yt-video-analyze --source benchmark --channel <slug> --top 5`
を全 benchmark slug で実行
3. 終わったら `/suno <theme>` を再実行
どうしても手書きで続行する場合のみ、明示的に `config/skills/suno.yaml::genre_line` を埋めてから再実行してください。
AskUserQuestion で「上記の手順を自動実行するか」を提示することは可能だが、ユーザーが明示同意するまでパターン設計の本文（情景フレーズ・歌詞含む）の作成に着手しない。genre_line 候補を本文中で口頭提案するのも禁止（手書き相当のため）。
設計に入る前に、config/channel/analytics.json の benchmark.channels[].slug を列挙し、
各 slug について data/video_analysis/<slug>/*.json（/video-analyze の出力）が存在するか確認する。
bgm_arc.intro / bgm_arc.peak / bgm_arc.outro / bgm_arc.energy_curve を
読み込み、slug ごとに intro 秒・peak 秒・outro 開始秒の平均と代表的な energy_curve パターンを
抽出する。
ceil(tracks_per_collection / 2) 個の entry をテーマ世界の中で散らす際の
バリエーション設計（朝寄り / 夕方寄り / 雨上がり / 室内など）の素材として使う。entry 間で似た
情景に寄りすぎないよう、benchmark の scene_timeline[].summary から多様な視覚モチーフを引く。patterns_per_collection 個の起伏配置（例: 4 パターン運用なら
パターン 1 を intro 寄り、パターン 3 を peak 寄り。1 パターン運用なら intro→peak→outro を 1 つの
情景フレーズに内包させる）の参考にする。scene_timeline[].summary は情景フレーズ設計（後述）の
素材として使う。data/video_analysis/<slug>/*.json 不在 + data/benchmark_*.json も不在: ユーザーに
「/benchmark を先行実行してください」と案内し、本サブセクションはスキップして警告のみで続行。data/benchmark_*.json は存在するが分析未実行: AskUserQuestion で
uv run yt-video-analyze --source benchmark --channel <slug> --top 5 の自動実行を提案。承認時のみ実行。
genre_line が空のときは拒否すると「前提条件チェック（hard gate）」を満たせないため中断する
（AI が手書き fallback で続行することは禁止）。genre_line が埋まっているときに限り、拒否時は
起伏配置の参考情報が無い旨を警告して続行できる。.json の analyzed_at が最新 data/benchmark_*.json のファイル名日付より古い場合は
警告のみ（中断しない）。サマリー出力フォーマット:
**ベンチマーク BGM 構造（video-analyze 平均）**
| slug | intro (avg) | peak (avg) | outro 開始 (avg) | energy 代表 |
|---|---|---|---|---|
| <slug> | 12s | 1:45 | 8:20 | 「徐々に上昇 → 中盤ピーク → ゆるやかなフェード」 |
ベンチマーク構造を参考にするが完全模倣しない。差別化方針（/channel-direction の決定事項）と
矛盾する場合は意図的に外す。
data/video_analysis/<slug>/*.json の suno_preset.genre_line / suno_preset.exclude_styles を
yt-generate-suno が fallback として参照する。config/skills/suno.yaml の対応キーが空のとき、
全 slug 横断で集約した推奨値を採用する:
genre_line: 各 JSON のスタイル句を多数決し上位 8 句を , 結合exclude_styles: 全 JSON の和集合（重複排除、出現順保持）ユーザーが config/skills/suno.yaml に override を書いた瞬間にそちらが優先される（後方互換）。
新規チャンネルでも /video-analyze --source benchmark を先に回しておけば 1 回目の /suno から
近い雰囲気で開始でき、genre_line / exclude_styles の手調整回数が減らせる。
方向性は必ずスクリプト由来とする（AI 手書き禁止）:
genre_line空 +suno_presetfallback も 取れない状態（=data/video_analysis/<slug>/*.jsonが全 slug で不在）で本 skill が AI 推定のgenre_lineを本文中・YAML・suno-prompts.md のいずれにも書き起こすことは禁止する。前提条件 チェック（hard gate）で中断し、yt-video-analyzeを回してもらってから再実行する。
$ARGUMENTS
インストモードは pattern 概念を廃止し、tracks_per_collection で指定した曲数から
ceil(N/2) 個の独立 entry をフラットに並べる。Suno は 1 Generate = 2 clip 生成するため、
両 clip を採用すれば最終 clip 数が tracks_per_collection になる（選曲しない）。各 entry は
他 entry と独立した情景・スタイルで設計し、A〜D の感情起伏や同一プロンプトの再生成は使わない。
参照すべきキー:
| キー | 役割 | 既定 |
|---|---|---|
tracks_per_collection (config) | 1 コレクションあたりの最終 clip 数 | 20 |
tracks (yaml top-level) | コレクション単位の上書き（省略時は config の値） | （省略） |
style_strategy | mixed (entry ごとに variant 混合) / single (全 entry 共通) | single |
style_variants | variant 名と genre_line の対応辞書 | {} |
bgm_arc 平均と scene_timeline[].summary から多様な情景の素材を集める（同じテーマ
世界の中で entry 間に色味の差を付ける材料）config/skills/suno.yaml::tracks_per_collection を読み、コレクション単位で
変えたい場合のみ suno-patterns.yaml の top-level tracks: キーで上書きするceil(tracks / 2) 個の entry を設計する: 各 entry は固有の name_jp / name_en / scenes (1 行)
/ tempo を持つ。name_jp / name_en の組（= Suno UI Song Title 欄に注入される entry.name）は
全 entry でユニーク必須 (重複すると Library / playlist / /masterup のリネーム時に衝突する)。
entry 間で情景が被らないよう、視点・時刻・場所・季節などを散らすstyle_strategy: single なら全 entry 同じ variant、mixed なら
entry ごとに variant を切り替える（例: A:lo-fi / B:ambient / C:piano / D:nature）yt-generate-suno 実行で検証: 以下のいずれかに違反すると fail-loud で停止する。
ceil(tracks / 2) と一致しないentry.name（= {name_jp} — {name_en}）が他 entry と重複しているtracks_per_collection | 必要 entry 数 (= ceil(N/2)) | 最終 clip 数 | プロンプト切替回数 |
|---|---|---|---|
| 20（既定） | 10 | 20 | 10 |
| 16 | 8 | 16 | 8 |
| 24 | 12 | 24 | 12 |
/suno-helper が各 entry を順次注入し、各 entry の (Generate) → 2 clip 生成完了 → 次 entry を
自動的に回す。完了後は 2 clip を選曲せず両方 playlist へ加わる。
ボーカルモードのみ、従来どおりパターン × 再生成回数で設計する（歌唱の発音・ピッチが不安定な ため、1 prompt から 2 clip 生成してベスト曲を選曲する運用を維持）。
参照すべきキー:
| キー | 役割 | 既定 |
|---|---|---|
pattern_strategy | パターン運用の戦略名 (mixed / single) | mixed |
tracks_per_pattern | 1 パターンあたりの Suno 再生成回数 (1 回 = 2 曲) | 3 |
pattern_strategy_note | AI への運用補足 (任意の自由記述) | "" |
bgm_arc 平均から起伏配置の参考にする（Instructions 冒頭のサマリーを利用）pattern_strategy: single の場合複数シーンに分けず 1 つの統合された情景フレーズ にまとめ、同一プロンプトを
tracks_per_pattern 回（既定 3 回、1 回 2 曲）生成する運用に切り替える。
suno-patterns.yaml には パターン 1 件だけ を書き出し、style variant も全曲共通にするpattern_strategy_note に補足が書かれていればそれを情景フレーズ設計に反映するtracks_per_pattern 回 × 2 曲 = tracks_per_pattern * 2 トラックpattern_strategy: mixed の場合従来の起伏設計（感情・エネルギーの推移）を N 個のパターンに分割する運用。デフォルトの
N=4（静寂 → 開放 → 親密 → 動き）が典型例。tracks_per_pattern 回ずつ生成しベスト曲を選定する。
総トラック数 = パターン数 × tracks_per_pattern × 2（Suno は 1 リクエスト = 2 曲）。
プロンプト変更は パターン数回のみ（パターン切替時のみ）。
| パターン数 | tracks_per_pattern | 総トラック | プロンプト切替回数 |
|---|---|---|---|
| 1 (single) | 3 | 6 | 1 |
| 4 (mixed, 典型) | 3 | 24 | 4 |
Suno V5 では Styles 経由で実楽曲長を制御できない（2026-05 時点）。Styles 末尾に長さ指定文字列を入れてもトークンを浪費するだけで効かないため、リポジトリ側ではこの指定を持たない。望む長さに満たない場合は Suno UI の Extend で延長する。
style_influence で指定（デフォルト 85 推奨）注意: 構造タグ（
[Intro],[Verse],[Chorus],[Bridge],[Outro]）はインストゥルメンタルでは効果なしだが、 ボーカルモードでは Lyrics 欄に必須（楽曲構成を Suno に伝える）。
music_engine: suno かつ genre_line にボーカル要素が含まれる場合に適用。
[Intro] / [Verse] / [Chorus] / [Bridge] / [Outro] のいずれかを置く（Suno が認識）config/skills/suno.yaml の lyrics_guidelines.language に従うlyrics_guidelines.tone（例: conversational, narrative, poetic）に従うlyrics_guidelines.rhyme_style（loose / strict / natural）に従うlyrics_guidelines.forbidden_topics に指定された語・テーマは避ける。固有人名もジェネリックな "you / I / we" に置換10-assets/main.png / thumbnail.jpg）のキャラクター性別と、歌詞の語り手 gender、genre_line のボーカル性別（male vocals / female vocals）の 3 点を一致させる。サムネで先に決まったキャラ性別に歌詞を従わせる。
genre_line は male vocalsgenre_line は female vocalslyrics_guidelines.vocal_gender が male / female なら従う。"" / auto の場合はサムネ（main.png）のキャラ性別を確認して決定するlyrics_guidelines.language: en の場合は、文法の正しさよりも「自然な話し言葉の積み上げ」を優先する。
downfall は「美しい終わり」ではなく失墜・転落を連想させるため避けるconfig/skills/suno.yaml の lyrics_guidelines.style_reference に参考歌詞を登録できる。これは文体参照専用で、歌詞本文・固有表現・印象的なフレーズを copy / verbatim / そのままコピペしてはいけない。
lyrics_guidelines:
style_reference:
- |
[Verse]
<参考にしたい英語歌詞>
使うときは、参照歌詞から以下だけを抽出して新規歌詞へ反映する:
config/skills/suno.yaml の lyrics_generation.provider で歌詞初稿の生成経路を切り替えられる。
| provider | 生成経路 |
|---|---|
claude | 通常の /suno skill 実行内で歌詞を作る |
codex | .claude/skills/suno/references/codex-lyrics.sh で Codex CLI に歌詞下書きを委譲する |
codex を使う場合は ChatGPT API を直叩きしない。追加 API key を持たず、ChatGPT ログイン済みの Codex CLI を使う。事前に以下でログイン状態を確認する:
codex login status
プロンプトファイルを用意し、出力先を wrapper の第 2 引数として明示して直接実行する:
bash .claude/skills/suno/references/codex-lyrics.sh \
20-documentation/codex-lyrics-prompt.md \
20-documentation/codex-lyrics.md
プロンプトにはテーマ、各 pattern の scenes、lyrics_guidelines、lyrics_guidelines.style_reference を含める。Codex から返った codex-lyrics.md を確認し、意味反転語（例: downfall）が混入していないこと、観察日記風・loose rhyme・mantra 的 Chorus が成立していることを確認してから suno-patterns.yaml の lyrics に貼り込む。
[Intro]
(short instrumental cue, optional 1-2 line spoken intro)
[Verse 1]
4-8 行。情景描写から始める。一人称 or 二人称の語り。
[Chorus]
2-4 行を繰り返す。コアフレーズ（タイトルや keyword に直結）。
[Verse 2]
4-8 行。Verse 1 の続き or 視点シフト。
[Chorus]
（繰り返し）
[Bridge]
2-4 行。視点を変える、または感情のピーク。
[Chorus]
（最後にもう一度）
[Outro]
1-2 行 or instrumental fade。
ジャンル別の具体的な歌詞例は references/lyrics-examples.md を参照。lyrics_guidelines.template_reference で指定した識別子に対応する例を起点にし、チャンネルの catchphrase を織り込む。
Create a... で始めない。情景を描写するSolo Cello や Ethereal Choir でフィーチャー楽器を強調可能（任意）scene_timeline の活用: Instructions の「ベンチマーク BGM 構造の参照」で抽出した
scene_timeline[].summary（視覚的に強い瞬間の傾向）を素材として活用する。そのままコピペしない —
自チャンネルの世界観に翻訳してから使う（語彙・トーン・固有名詞は本 skill の禁止形容詞ルールと整合させる）SunoAI をモダン / オーケストラ方向に誘導するため禁止:
thundering, blazing, crushing, soaring, screaming, devastating, explosive, ferocious, towering, surging, crystalline, shimmering, lush, sweeping, majestic, glorious, echoing
代替: low, sparse, bright, soft, deep, gentle, quiet, warm, airy, rising, driving 等
雨音や環境音は楽曲に含めない。 マスタリング時に別レイヤーで追加する。
SunoAI は情景フレーズ中の水・雨関連ワードを SE（効果音）として生成してしまう。以下のルールを守る:
NG ワード（SE を誘発）:
rain, dripping, drops, puddles, splashing, pouring, streaming water, trickling, wet（音を連想する文脈で）
OK ワード（ムード・視覚のみ）:
misty, melancholic, nocturnal, bittersweet, wistful, lonesome, lingering, overcast, hazy, foggy, damp（視覚描写として）, glistening, misted, fogged
全プロンプトに必ず追加:
no rain sound effects, no white noise, no ambient noise
Exclude Styles にも必ず追加:
rain sounds, vinyl crackle, white noise, ambient noise
（config/skills/suno.yaml の exclude_styles にあらかじめ含めておくと自動付加される）
しっとり感は misty, melancholic, nocturnal, bittersweet 等のムード語で表現する。
exclude_styles で除外したワードを genre_line 側に残すと相殺される。たとえば exclude_styles に vinyl crackle を含めつつ genre_line に vinyl crackle warmth のような表現を入れると、Suno には除外したい SE が結局供給されてしまう。exclude_styles を更新するときは genre_line 側にも同じワードや派生表現が混ざっていないかをセットで確認する。
ジャンル別の具体例は references/suno-examples.md を参照。新規プロンプト作成時は、該当ジャンルの例を基準として確認する。
自然言語テンポ: very slow / slow / gentle / moderate / lively
| テーマ | テンポ | 情景フレーズ例 |
|---|---|---|
| Study / Reading | slow | fingers turning pages slowly |
| Mystical / Magic | slow / gentle | a glass orb glowing soft blue |
| Sleep / Dream | very slow | embers fading in a stone hearth |
| Village / Town | moderate | bread cooling on a windowsill |
| Forest / Nature | gentle / moderate | morning mist between ancient oaks |
| Tavern / Inn | moderate | ale mugs and low firelight |
| Journey / Travel | moderate | boots on a winding road at dusk |
| Festival / Dance | lively | fiddles rising in a torchlit hall |
20-documentation/suno-patterns.yaml に保存。scenes + tempo（インスト時） または scenes + lyrics（ボーカル時） を記述する。style_variants がある場合は style キーで variant を指定可能。
tracks (省略時は config の tracks_per_collection) から導出した ceil(N/2) 個の独立 entry を
patterns: 配列に並べる。各 entry は 1 scene = 1 Generate = 2 clip 採用。
title: Collection Title Here
mode: instrumental # 省略時は genre_line から自動判定
tracks: 20 # 省略時は config/skills/suno.yaml::tracks_per_collection (既定 20) が効く
patterns: # ceil(tracks/2) = 10 entry を並べる。entry 間で情景は被らせない
- name_jp: 屋上の静寂
name_en: Rooftop Silence
style: C
tempo: slow
scenes:
- a heavy door propped open with a brick, cool night air rising through a dim stairwell, the last stars fading above an antenna array
- name_jp: 朝のキッチン
name_en: Morning Kitchen
style: A
tempo: gentle
scenes:
- steam rising from a kettle by a cracked window, soft sunlight on a wooden cutting board, a single cup waiting on the counter
# ... 残り 8 entry を同様に並べる
title: Collection Title Here
mode: vocal # 省略時は genre_line から自動判定
patterns:
- name_jp: <日本語パターン名>
name_en: <English Pattern Name>
scenes:
- <情景フレーズ (英語、1 行)>
lyrics: |
[Verse 1]
<4-8 行の情景描写>
[Chorus]
<2-4 行のコアフレーズ>
[Verse 2]
<4-8 行、視点シフト or 続き>
[Chorus]
（繰り返し）
[Bridge]
<2-4 行、感情のピーク>
[Chorus]
（最後にもう一度）
[Outro]
<1-2 行 or instrumental fade>
注意:
style 指定時は variant の genre_line にテンポが含まれるため、tempo は省略可能len(patterns) が ceil(tracks / 2) と一致しないと yt-generate-suno が fail-loud で停止するname_jp / name_en の組はユニーク必須。重複していると yt-generate-suno が fail-loud で停止する
（Suno Library / playlist 識別 / /masterup リネーム衝突を防ぐため、両モード共通の制約）tracks_per_pattern 回生成で
tracks_per_pattern * 2 トラック/パターン（既定 3 回 = 6 トラック）。pattern_strategy: single の
場合、patterns: 配列は 1 要素だけ にする（A 〜 D を並べない）uv run yt-generate-suno <collection-path>
config/skills/suno.yaml の genre_line + exclude_styles + style_influence をパターンに自動付加して suno-prompts.md を生成する。設定変更時はスクリプト再実行のみで全プロンプトに反映される。
suno-prompts.md と同じ 20-documentation/ ディレクトリに、各パターンの { name, style, lyrics } を配列化した suno-prompts.json も併出される。これは Step 3 の Chrome 拡張（yt-collection-serve 経由）が fetch する配信元で、suno-prompts.md の Style 行と同一内容から生成されるため両者はドリフトしない。
ボーカルモードの出力: 各パターンに Style 欄（情景フレーズ + genre_line）+ Lyrics 欄（歌詞そのまま）の 2 ブロックが書き出される。Suno 側で Custom Mode に入って Instrumental トグル OFF にした状態で両方を投入する（Step 3 の自動投入、または fallback の手コピペ）。
保存後、workflow-state.json の music.generated = true に更新する。
/suno-helper で自動投入（推奨）suno-prompts.json を Chrome 拡張（extensions/suno-helper/）が読み取り、Suno Custom Mode の Style/Lyrics 両フィールドへ順次注入 → Generate 押下 → 生成完了検知 → 次パターン、を連続実行する。手コピペ（4 パターン × 3 回 ≒ 12 サイクル）を自動化する経路。
ヘッドレス／DevTools 経由ではなく 既ログイン状態の本物の Chrome セッション 上で動かすため、reCAPTCHA を踏みにくく、DOM 操作は固定実装でトークン消費ゼロ、ネイティブイベント発火で React に即時反映される。
手順:
extensions/suno-helper/ で pnpm install && pnpm build を実行 → Chrome で chrome://extensions → デベロッパーモード ON → 「パッケージ化されていない拡張機能を読み込む」で extensions/suno-helper/.output/chrome-mv3/ を選択。詳細は extensions/README.md。suno-prompts.json を localhost に配信する。Ctrl-C で停止できるフォアグラウンドプロセス。
uv run yt-collection-serve collections/planning/<theme>
# → http://localhost:7873/suno/prompts.json で配信（CORS はデフォルトで chrome-extension:// と suno.com 系 web origin を許可。#896）
suno-prompts.json のパスを直接渡してもよい。ポートを変える場合は --port <PORT>。http://localhost:7873）を入れて データ取得 → パターン一覧を確認 → 全パターンを連続実行。拡張をロードできない、Suno の UI 変更で注入先セレクタが外れた（extensions/shared/dom.ts の SELECTORS 保守が必要）、その他自動投入が機能しない場合は、従来どおり suno-prompts.md を見ながら手コピペ に切り替える:
suno-prompts.md を開く。自動・手動どちらの経路でも投入内容は同一（suno-prompts.md と suno-prompts.json は同一の中間表現から生成）。
/alignment-check がコレクション横断で音楽 mood × サムネ × タイトルの整合を機械的に判定できるよう、workflow-state.json の planning.music セクションを populate する。新規制作分は必須。
{
"planning": {
"music": {
"engine": "suno",
"mood": ["mellow", "introspective"],
"atmosphere": "rainy harbor at night, mellow jazz by the docks",
"tempo": "slow",
"instruments": ["soft piano", "saxophone", "upright bass"],
"exclude": ["electric guitar", "heavy drums"]
}
}
}
書き方ガイド:
| フィールド | ソース | 補足 |
|---|---|---|
engine | 固定値 "suno" | — |
mood | コレクション全体を貫く感情語 1-3 個 | インストは全 entry の scenes を、ボーカルは全パターンの感情の流れを蒸留（例: ["mellow", "warm"]） |
atmosphere | 全 entry / パターンの scenes を集約した世界観 1 文（英語） | 個別シーンを羅列せず、コレクション全体の情景を 1 文で言い切る |
tempo | 代表テンポ | enum: very slow / slow / gentle / moderate / lively（情景フレーズ設計の「テンポ設計」表と同じ語彙） |
instruments | config/skills/suno.yaml の genre_line + mood_descriptors の楽器 + scenes の楽器ロール指定（Solo Cello 等） | 重複排除し、主役 3-5 個に絞る |
exclude (optional) | config/skills/suno.yaml の exclude_styles から楽器系のみ | rain sounds / vinyl crackle / white noise 等の環境音系は対象外（楽曲楽器ではないため） |
冪等性: 既存値があっても planning.music 全体を上書きする（merge しない）。スキル再実行 = 設計やり直しと見なす。
/suno はSuno UI に投入するプロンプト（Style + Lyrics）を生成する工程で、映像オーバーレイ（ビジュアライザー・波形・購読ボタンポップアップ等）は扱わない。
ユーザーから「ビジュアライザー付きで」「波形を出して」等の指示があっても、/suno 段階・/masterup 段階のいずれでも何も合成できない。
ビジュアライザー周りの現状と制約は videoup SKILL.md の「オーディオビジュアライザー / オーバーレイについて」節を参照（#511 で feature 化中・現状未実装）。
誤指示の事故防止のため、suno 着手前に動画にオーバーレイが必要かをユーザーへ確認すること（#646 feedback）。
本スキル自体は外部 API を呼ばない（生成プロンプトを作るだけ）。実際の楽曲生成は /suno-helper で自動投入、またはその fallback として手コピペで行う。
| 状況 | 兆候 | 対処 |
|---|---|---|
| Suno UI / CDN 障害 | Suno 側でエラー・生成が進まない | 本スキルの責務外（楽曲生成は /suno-helper）。Suno 公式サイト・公式 SNS で障害情報を確認し、時間を置いて UI で再試行。DL/マスター化は /masterup 側の障害ガイダンスに従う |
→ /suno-helper で SunoAI Custom Mode（Instrumental ON）に自動投入して連続生成 + playlist 一括追加
→ /masterup <playlist-url> でダウンロード + マスター音源生成
→ /suno-helper で SunoAI Custom Mode（Instrumental OFF）に Style + Lyrics を自動投入して連続生成 + playlist 一括追加
→ 歌唱の発音・ピッチが破綻していないか必ず試聴チェック
→ /masterup <playlist-url> でダウンロード + マスター音源生成
/wf-new/suno-helper/masterupextensions/suno-helper/ / extensions/shared/src/youtube_automation/scripts/collection_serve.py