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という仕組みの一部です。次のどちらかなら、この2つは無効になります。1つは、設定全体でspinnerTipsEnabledがfalseに解決される場合です。もう1つは、spinnerTipsOverrideでexcludeDefaultがtrueになり、読み込める自前のtipがある場合です。参照されるのは、user設定・--settings・managed settingsのうち優先順位が最も高いものです。Discoverタブへの固定表示はtip設定から独立しており、この条件では止まりません。

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

社内マーケットプレイスを整備しても、社員が「そのプラグインの存在自体を知らない」ままでは使われません。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なら、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回のみです。シグナルが一致した状態で初めてタブを開いたときに固定され、その記録は~/.claude.jsonに残ります。注記には一致したシグナルが入ります(suggested for this directoryやsuggested for terraform commandsなど)。それ以降の訪問では通常の並び順に戻ります。

plugin hintsとの違い

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

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

公開する前に、マーケットプレイスディレクトリに対してclaude plugin validateを実行し、relevanceブロックを確認します。--strictを付けると警告もエラー扱いになり、CIで未知のフィールドを落とせます。--jsonなら検査結果をJSONオブジェクト1つで受け取れます。--strictはv2.1.145以降、--jsonはv2.1.259以降で使えます。終了コードは、通過が0、検査の失敗が1、検証器自体の失敗が2です。セッション内からは/plugin validate <path>で同じ報告を出せます。

claude plugin validate ./my-marketplace

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

v2.1.287で、わざと壊したマーケットプレイスを検査した結果を示します。hostsにURLをそのまま書き、relevanceにextra、signalsにunknownSigという未知のキーを足しています。

✘ Found 1 error:
 
  ❯ plugins.0.relevance.signals.hosts.0: must be a lowercase bare hostname (no scheme, port, or path)
 
⚠ Found 3 warnings:
 
  ❯ plugins[0].relevance.extra: Unknown field 'extra'. Claude Code ignores it at load time.
  ❯ plugins[0].relevance.signals.unknownSig: Unknown field 'unknownSig'. Claude Code ignores it at load time.
  ❯ plugins[0] plugin.json → author: No author information provided. Consider adding author details for plugin attribution
 
✘ Validation failed

未知のキーは警告、ホスト名の書式違反はエラーで、終了コードは1でした。topicを65文字にした別の検査は、次のエラーになりました。

plugins.0.relevance.topic: Too big: expected string to have <=64 characters

上限超えは軽く見られません。認識されるフィールドの値が上限を超えると、そのプラグインのエントリ全体が無効になり、直すまで利用者はそのプラグインをこのマーケットプレイスからインストールできません。

relevanceに文字列を書いた場合はエラーでなく警告で、「It will be ignored at load time」と出て検査は通ります。提案が出ない原因がrelevanceのタイプミスなら、validateが成功しても気づけない点に注意が必要です。

提案が出ないときの切り分け

管理者の許可と運営者の宣言の2段構えなので、出ない原因は症状から絞れます。

どこにも出ない場合は、まず許可リストを疑います。名前がpluginSuggestionMarketplacesに無いか、取得元の宣言が無いか、マシンに登録済みの同名マーケットプレイスが別の取得元由来だと、提案は一切出ません。公式マーケットプレイスだけは名前の許可で足ります。

Discoverタブには出るのにスピナーと開始時に出ない場合は、spinnerTipsEnabledがfalseか、excludeDefaultが効いています。Discoverタブの固定表示はこの設定から独立しています。

セッション開始時に出ない場合は、シグナルの種類が原因かもしれません。開始時の通知が欲しいなら、cwdを書いているか確かめます。

cliが期待どおり一致しない場合は、記録されるのが複合コマンドの先頭だけだからです。cd infra && terraform planではterraformが記録されません。terraformを単独で実行する場面が想定できないなら、filesReadやhostsを併用します。

一度出たきり出ない場合は、頻度の制限に当たっています。動作確認を繰り返すときは、Discoverタブの固定表示が同じマシンでは最初の1回しか出ない前提で試します。

インストール済みのプラグインに出ないのは仕様です。

まとめ

提案が出ないとき、まず確かめるのはrelevanceの中身でなく、managed settingsの許可と取得元の宣言です。宣言側の事故は、--strict付きのclaude plugin validateをCIに置けば公開前に止められます。プラグインの基本的な作り方と配布手順はClaude Codeプラグイン完全ガイドにあります。