Claude Code plugin relevanceで組織にプラグインを推薦する

社内向けにプラグインマーケットプレイスを運用しているなら、marketplace.jsonのプラグインエントリにrelevanceブロックを1つ足すだけで、Claude Codeが利用者の作業内容に合わせてインストールを提案してくれます。仕組みはplugin relevanceと呼ばれ、対象はマーケットプレイス運営者と組織の管理者です。マーケットプレイスが宣言しても、管理者がmanaged settingsで許可するまで提案は一切表示されません。

plugin relevanceとは何か

plugin relevanceとは、マーケットプレイスのプラグインエントリに「このプラグインが関係しそうな条件」を宣言しておき、条件が現在のセッションに一致したときだけClaude Codeがインストールを提案する仕組みです。条件はセッションの作業ディレクトリや、Claudeが読んだファイルのようなシグナルに対するパターンマッチで判定します。

シグナルの照合は利用者のマシン上でローカルに行われます。ネットワーク通信は発生せず、どのシグナルが一致したか、その値が何だったかがAnthropicにもマーケットプレイス運営者にも報告されることはありません。

シグナルが一致し、かつそのプラグインが未インストールの場合、Claude Codeは3箇所にプラグインを表示します。

スピナーのヒントとセッション開始時の通知は、スピナーtipsという仕組みの一部です。設定全体でspinnerTipsEnabledがfalseに解決される場合、あるいはuser設定・--settings・managed settingsのspinnerTipsOverrideキー全体でexcludeDefaultがtrueに解決され、かつそれらのキーが少なくとも1つのtipかtipsFileを設定している場合、この2つは無効になります。Discoverタブへの固定表示はtip設定から独立しており、この条件では止まりません。

Claude Codeがプラグインを自動でインストールすることはなく、提案を受け入れるかどうかは常にユーザーが選びます。

社内マーケットプレイスを整備しても、社員が「そのプラグインの存在自体を知らない」ままでは使われません。管理者がSlackやWikiで告知しても、実際にTerraformやStripeのコードを触っている瞬間には届きにくいものです。plugin relevanceは、その気づきをセッションの作業内容そのものから逆算して届ける仕組みです。

marketplace.jsonにrelevanceを追加する

マーケットプレイスのmarketplace.jsonで、対象プラグインのエントリにrelevanceオブジェクトを追加します。次の例は、Claudeが.tfファイルを読んだとき、またはterraformコマンドを実行したときにterraform-helpersプラグインを関連ありと宣言します。

{
  "name": "acme-corp-plugins",
  "owner": { "name": "Acme Platform Team" },
  "plugins": [
    {
      "name": "terraform-helpers",
      "source": "./plugins/terraform-helpers",
      "description": "Acme conventions and helpers for Terraform",
      "relevance": {
        "topic": "Terraform",
        "signals": {
          "cli": ["terraform"],
          "filesRead": ["**/*.tf"]
        }
      }
    }
  ]
}

relevanceブロックはあってもシグナルが一度も一致しなければ、そのプラグインは通常のマーケットプレイスエントリと同じ扱いになります。Discoverリストには通常の並び順で表示され、スピナーのヒントとして浮上することもありません。

relevanceフィールド

topicを省略した場合の既定値は、プラグイン名のハイフン区切りをそれぞれ大文字化した形になります。たとえばdb-migrate-helperというプラグイン名なら、既定のtopicはDb Migrate Helperになります。スピナーのヒント文をそのまま自然に読ませたいなら、topicを明示的に指定したほうが安全です。

signalsで使えるシグナル

cli / hosts / filesRead / manifestDepsはセッションの履歴を必要とするシグナルなので、スピナーのヒントとDiscoverタブでのみ一致しえます。filesReadとmanifestDepsは、Claudeが書き込み・編集したファイルや自動読み込みされたCLAUDE.mdメモリーファイルも含む、セッションが記録したファイル状態を対象にします。

次の例はmanifestDepsを使い、Claudeがstripeに依存するpackage.jsonを読んだ時点でStripe向けプラグインを提案します。fileパターンは[/\\\\]でフォワードスラッシュとバックスラッシュの両方のパス区切りに一致させ、\\.でドットをリテラル扱いにしています。JSON内では正規表現の各バックスラッシュを2重に書きます。

{
  "name": "stripe-helpers",
  "source": "./plugins/stripe-helpers",
  "relevance": {
    "topic": "Stripe",
    "signals": {
      "manifestDeps": [
        {
          "file": "[/\\\\]package\\.json$",
          "pattern": "\"stripe\"\\s*:"
        }
      ]
    }
  }
}

managed settingsで提案を有効化する

marketplace.jsonにrelevanceを書くだけでは提案は表示されません。管理者がmanaged settingsでそのマーケットプレイスを許可リストに追加する必要があります。

pluginSuggestionMarketplacesにマーケットプレイス名を追加します。公式Anthropicマーケットプレイス以外を対象にする場合は、同じmanaged settings内でextraKnownMarketplacesのエントリかstrictKnownMarketplacesのエントリとしてマーケットプレイスの取得元も宣言する必要があります。マシン上に登録済みのマーケットプレイスが別の取得元由来なら、許可リストの名前は無視されます。無関係な取得元が許可済みの名前を横取りして、組織全体にプラグインを提案させる事態を防ぐための仕組みです。

次のmanaged-settings.jsonは、GitHubリポジトリから組織のマーケットプレイスを登録し、その提案を有効化します。

{
  "extraKnownMarketplaces": {
    "acme-corp-plugins": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  },
  "pluginSuggestionMarketplaces": ["acme-corp-plugins"]
}

公式マーケットプレイスは取得元宣言の要件が免除されます。その名前は公式Anthropicの取得元からしか登録されえないため、名前を許可リストに載せるだけで十分です。

{
  "pluginSuggestionMarketplaces": ["claude-plugins-official"]
}

ユーザーに表示される内容

セッション中にシグナルが一致すると、スピナーのヒントは次のように表示されます。

Working with Terraform? Install the terraform-helpers plugin:
/plugin install terraform-helpers@acme-corp-plugins

セッション開始時、cwdシグナルが一致すると次の1行通知が出ます。

plugin suggestion: terraform-helpers@acme-corp-plugins · /plugin

同じプラグインの提案は、スピナーのヒントとセッション開始時の通知を合わせて3セッションに1回までしか表示されず、いずれもそのプラグインをインストールした時点で止まります。セッション開始時の通知はさらに、2回表示された後は出なくなります。/pluginのDiscoverタブでは同じプラグインの固定表示は1回のみで、それ以降の訪問では通常の並び順に戻ります。

plugin hintsとの違い

似た名前の仕組みにplugin hintsがあり、どちらもClaude Codeが最終的にプラグインのインストールを提案する点は共通しています。判定の起点と対象範囲は別物です。

組織内の自作ツールに気づいてほしいならplugin relevance、外部のCLI・SDKから自分の公式プラグインへ誘導したいならplugin hintsという住み分けになります。どちらも最終的な確認と実行はユーザーの手に委ねられ、Claude Codeが自動でインストールすることはありません。

マーケットプレイスを検証する

公開する前に、マーケットプレイスディレクトリに対してclaude plugin validateを実行し、relevanceブロックを確認します。

claude plugin validate ./my-marketplace

このバリデータはrelevanceおよびrelevance.signals配下の未知のキーを警告として報告し、relevanceの値がオブジェクトでない場合はフラグを立て、signals.hostsのエントリにスキーム・ポート・パスが含まれる場合は拒否します。

よくある質問

relevanceを設定すればすぐに提案が表示されますか

されません。マーケットプレイス側のrelevance宣言と、管理者によるmanaged settingsでの許可リスト登録の両方がそろって初めて提案が表示されます。管理者の許可なしでは公式マーケットプレイスのrelevance宣言も効果を持ちません。

cliやfilesReadのようなシグナルはセッション開始時にも一致しますか

一致しません。セッション開始時点で一致しうるのはcwdシグナルだけです。cli / hosts / filesRead / manifestDepsはセッションの実行履歴を必要とするため、スピナーのヒントとDiscoverタブでのみ一致します。

すでにインストール済みのプラグインにも提案は出ますか

出ません。シグナルが一致しても、そのプラグインが未インストールの場合だけスピナーのヒントとセッション開始時の通知が表示されます。

spinnerTipsEnabledをfalseにすると何が止まりますか

スピナーのヒントとセッション開始時の通知の両方が無効になります。ただし/pluginのDiscoverタブへの固定表示はtip設定から独立しているため、この設定では止まりません。

signals.hostsにパスを含むURLを書くとどうなりますか

claude plugin validateがそのエントリを拒否します。hostsはスキーム・ポート・パスを含まない裸の小文字ホスト名だけを受け付けるシグナルです。

1つのrelevanceブロックに複数の種類のシグナルを組み合わせられますか

組み合わせられます。先述のterraform-helpersの例はcliとfilesReadの両方を1つのsignalsオブジェクトに書いています。プラグインの実態に合わせて、複数の種類のシグナルを1つのエントリにまとめて宣言できます。

まとめ

plugin relevanceは、marketplace.json側のrelevance宣言とmanaged settingsのpluginSuggestionMarketplaces許可リストがそろって初めて動く2段構成の提案機能です。シグナルの照合はローカルで完結し、外部への通信は発生しません。cwdはセッション開始時から効く唯一のシグナルで、それ以外のcli / hosts / filesRead / manifestDepsはセッションの実行履歴が積み上がってから効き始めます。マーケットプレイス運営者はプラグインごとに的確なシグナルを選び、組織の管理者はmanaged settingsの許可リストを整えることで、必要な人に必要なタイミングでプラグインを届けられます。プラグインの基本的な作り方と配布手順はClaude Codeプラグイン完全ガイドを参照してください。