keyword-cluster

/digital-marketing-pro:keyword-cluster

スクリプトの場所。 ホストで ${CLAUDE_PLUGIN_ROOT} が設定されていない場合、スクリプトはこのプラグインの scripts/ フォルダー（skills/ と同じ階層）にあります。Python 3.10 以降で実行してください。python が見つからない場合（macOS、多くの Linux システム）は python3 を使用してください。

目的

シードキーワードのセットから、公開準備が整ったクラスター計画を作成します。検索意図ごとにグループ化され、独自のスコアリング式で優先順位を付けたピラーページとそのスポーク、内部リンクマップ、4つのゲートで構成される品質スコアカードを作成します。出力は /digital-marketing-pro:content-brief または /digital-marketing-pro:content-engine にそのまま引き継げる形式です。

コンテキストの効率化

負荷の高いスキルです。参照ファイルは Read する前に Grep し、一致した範囲のみ offset と limit を指定して Read してください。ファイルを開く前に ${CLAUDE_PLUGIN_DATA}/<brand>/ を一覧表示してください。セッション途中で再実行する場合、すでにコンテキストにあるファイルは読み飛ばしてください。

使用する場面

• 新しいコンテンツプログラムの開始時 — 20個のキーワードを含むブリーフを、構造化されたトピックハブに変換する
• 既存のコンテンツライブラリを監査し、カニバリゼーション（同じ検索意図をめぐって2つのページが競合する状態）を確認する
• 執筆を始める前に、ピラーとスポークのアーキテクチャを設計する
• 数百のバリエーションにわたるプログラマティック SEO を段階的に進める（トピックファミリーごとに1回使用）
• 既存サイトの内部リンクグラフを再編成する

キーワードの 拡張 だけが必要な場合（/digital-marketing-pro:keyword-research を使用）、または ランキング／SERP 機能の分析が必要な場合（SERP 機能には --features を指定して /digital-marketing-pro:rank-monitor を使用）は、使用しないでください。

ブランドコンテキスト（自動適用）

1. ~/.claude-marketing/brands/_active-brand.json からアクティブなスラッグを読み取り、~/.claude-marketing/brands/{slug}/profile.json を読み込みます
2. ブランドが存在しない場合は、「まずブランドを設定しますか（/digital-marketing-pro:brand-setup）？」と尋ねます。または、デフォルト設定で続行します
3. skills/context-engine/industry-profiles.md にある業界固有のガイダンスを適用します
4. クラスタリングの前に、skills/context-engine/compliance-rules.md を適用して禁止用語を除外します

入力

入力	ソース	必須？
シードキーワード（3～500個）	keyword 列を含む CSV（任意：volume、kd、intent）	はい
キーワードごとの SERP 結果	任意の順位トラッカー／Ahrefs／Semrush のエクスポートから取得した JSON：{keyword: [top result URLs]}	強く推奨 — これがない場合、スクリプトは精度が低い語彙ベースのクラスタリングに切り替わります
対象国／言語	ブランドプロフィールから取得	任意の上書き
最小検索ボリューム／最大 KD フィルター	CLI フラグ	任意
重複のしきい値	CLI フラグ --overlap（デフォルトは SERP モードで 0.4、語彙モードで 0.3）	任意

SERP の JSON がない場合は、ブランドに接続された順位トラッカーの MCP（Ahrefs／SE Ranking／Semrush）を使用して各シードを検索し、上位10件の URL を保存すれば、すぐに作成できます。API の利用コストに見合わないほどシードが多い場合に限り、この手順を省略してください。ただし、最終成果物では信頼度の低いモードであることを明記してください。

プロセス（番号付きファイルを10個出力）

すべての出力は ${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{YYYY-MM-DD}/ に保存します。

1. 00-input.md — シード、ソース、フィルター、ブランドのコンテキスト、実行タイムスタンプを記録します
2. 01-seed-expansion.md — シードが20個未満の場合は、ブランドのキーワード調査用 MCP（Ahrefs の getRelatedKeywords など）を使って約50～200個まで拡張します。それ以外の場合はスキップします。拡張元を記録します。
3. 02-filtered.csv — 最小ボリューム／最大KD／禁止ワードのフィルターを適用します。フィルター後のセットを CSV として保存します（スクリプトが使用するファイルです）。
4. 03-serps.json — 接続済みのランクトラッカーを使って、キーワードごとに上位10件の SERP URL を取得します（SERP がすでに提供されている場合はスキップします）。予算ガード：推定コストが500クレジットを超える場合は、取得前にコストを提示し、「続行しますか？（y/N — デフォルトは N）」と確認します。
5. 04-cluster-run.json — スクリプトを実行します：

   python "${CLAUDE_PLUGIN_ROOT}/scripts/keyword_cluster.py" \
       --keywords "${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{date}/02-filtered.csv" \
       --serps "${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{date}/03-serps.json" \
       --overlap 0.4 \
       --min-volume {profile.min_volume or 0} \
       --max-kd {profile.max_kd or 100} \
       --out "${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{date}/04-cluster-run.json"
   

6. 05-quality-scorecard.md — 04-cluster-run.json の quality_scorecard ブロックを読み込みます。status: needs_review の場合は、以下のように診断します：
   • cannibalisation: fail → 2つのクラスターが pillar と intent を共有しています。統合するか、優先度の低いクラスターの pillar を再割り当てします。
   • orphan: fail → 複数のキーワードを含むクラスターに spoke がありません。メンバーを再トークン化するか、--overlap を下げます。
   • coverage: fail → クラスターに割り当てられたシードが80%未満です。--overlap を0.3に下げるか、シードを拡張します。
   • anchor_diversity: fail → pillar 名が似すぎています。同義語のバリエーションを使ってクラスター名を書き換えます。
   • fragmentation_warning: true（pillar のみが50%超）→ overlap のしきい値が厳しすぎます。まず --overlap 0.3 を試します。
7. 06-pillar-pages.md — priority_score >= 0.5 の各クラスターについて、pillar ページの概要を1段落で作成します（検索意図、対象読者、目標文字数、答えるべき主要な質問）。これらは /digital-marketing-pro:content-brief に渡します。
8. 07-internal-link-map.md — スクリプト出力の internal_link_targets を表形式で表示します。クラスターごとに、リンク先となる他のクラスターと推奨アンカーテキストを記載します。開発チームまたは CMS テンプレートが使用するファイルです。
9. 08-build-order.md — priority_score の降順で並べます。推奨する構築スケジュールは、上位10%を第1四半期、次の30%を第2四半期、残りをバックログとします。
10. PLAN.md — 1ページの概要です。統計、スコアカード、優先度上位5つのクラスター、次のスキルへの引き継ぎを記載します。

出力形式

${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/2026-06-04/
├── 00-input.md
├── 01-seed-expansion.md      (only if seeds expanded)
├── 02-filtered.csv
├── 03-serps.json             (if SERP mode)
├── 04-cluster-run.json       (raw script output)
├── 05-quality-scorecard.md
├── 06-pillar-pages.md
├── 07-internal-link-map.md
├── 08-build-order.md
└── PLAN.md                   (the deliverable)

PLAN.md はブランド／クライアント／次のスキルに渡すファイルです。それ以外はすべて、監査可能な中間状態です。

品質スコアカード（4つのゲート）

実行するたびに、scripts/keyword_cluster.py によってスコアカードが生成されます。status: ready になるには、4つすべてに合格する必要があります：

ゲート	チェック内容	重要な理由
cannibalisation	同じ (pillar, primary_intent) の組み合わせを共有するクラスターがないこと	同じ SERP で競合する2つのページを作成するのを防ぎます
orphan	複数のキーワードを含むすべてのクラスターに、1つ以上の spoke があること（pillar のみのクラスターは対象外としてタグ付け）	クラスターの中心にあるトピックを支えるトピックがないという、クラスタリングのバグを検出します
coverage	入力シードの80%以上が、少なくとも1つのクラスターに割り当てられていること	「低品質な」シードや、しきい値が厳しすぎる状態を検出します
anchor_diversity	複数のキーワードを含む各クラスターに、2種類以上のアンカーテキストが提案されていること	内部リンクグラフ全体でアンカーテキストが過剰に最適化されるのを防ぎます

fragmentation_warning: true（pillar のみが50%超）はソフトなシグナルです。実行結果は有効ですが、--overlap を下げて再実行することを検討してください。

クラスタリング後

次のように尋ねます：「以下を行いますか？

• 上位の pillar ページの概要を作成しますか？（/digital-marketing-pro:content-brief）
• 優先度が最も高い pillar の執筆を始めますか？（/digital-marketing-pro:content-engine）
• 内部リンクマップを CMS に適用しますか？（/digital-marketing-pro:seo-implement）
• /digital-marketing-pro:seo-drift を使って四半期ごとの再実行をスケジュールしますか？」

チェーンの引き継ぎ

このスキルは、次のチェーンで成果物を提供します。

1. /digital-marketing-pro:keyword-research — シードを生成します
2. /digital-marketing-pro:keyword-cluster — このスキル
3. /digital-marketing-pro:content-brief — PLAN.md と 06-pillar-pages.md を使用して、各ピラーのブリーフを作成します
4. /digital-marketing-pro:content-engine — コンテンツを作成します
5. /digital-marketing-pro:seo-implement — 内部リンクマップを CMS に適用します

ヒントと注意事項

• SERP モードは、レキシカルモードより明らかに優れています。 レキシカルクラスタリングでは、「shopify seo」と「ecommerce platform seo」が重複する SERP をターゲットにし、「shopify themes」はそうではないことを把握できません。
• 重複しきい値のデフォルト値は保守的です。 fragmentation_warning: true が表示されたら、まず 0.3 に下げてください。クラスターが少なすぎて cannibalisation: fail が表示されたら、0.5 に上げてください。
• 優先度スコアは順位付けではありません。構築順序の出発点です。priority_score: 0.3 のクラスターでも、利益率の高い製品ラインに対応していれば、コンバージョンの最も高い機会となる場合があります。機械的な判断より、ブランドプロフィールの business_goals を優先してください。
• 生の GSC クエリのエクスポートデータは、事前にフィルタリングせずに実行しないでください。 GSC のダンプには、同じクエリのロングテールのバリエーションが何千件も含まれています。これらはすべて同じクラスターにまとまり、巨大なクラスターが 1 つ生成されます。
• ピラーのみのクラスターも有効です。これはシードセットにスポーク候補がないだけで、個別のインテントを表しています。スポークを追加したい場合は、ステップ 2 の拡張でシードを追加してください。
• 内部リンクマップは提案であり、指示ではありません。 最終的なアンカーテキストは、ブランドのトーンに合っているか確認してください（ブランドプロフィールのトーン項目と skills/context-engine/guidelines-framework.md を適用します）。

使用するエージェント

• seo-specialist（主要）— 解釈と、ピラーページに関する最終提案
• competitive-intel — 結果が予想外に見える場合の SERP 重複に関する推論
• brand-guardian — 禁止語リストに照らしたアンカーテキストのレビュー

関連項目

• /digital-marketing-pro:keyword-research — シードを生成します（最初に使用）
• /digital-marketing-pro:content-brief — クラスタープランを使用します（次に使用）
• /digital-marketing-pro:seo-implement — 内部リンクマップを CMS に適用します
• /digital-marketing-pro:seo-drift — クラスターの変化を検出するため、四半期ごとに再実行します
• scripts/keyword_cluster.py — 基盤となるクラスタリングエンジン