extraKnownMarketplacesでチームにマーケットプレイスを自動配布する

extraKnownMarketplacesが配るもの、配らないもの

extraKnownMarketplaces は、settings.json に書いたマーケットプレイスを、そのファイルが効く全員に自動登録する設定です。メンバーが /plugin marketplace add を打つ手間がなくなります。書ける場所は次のとおりです。プロジェクトの .claude/settings.json、個人の ~/.claude/settings.json、組織のmanaged settingsのどれでもかまいません。スコープは「Any file」です。

配るのは「どこにプラグインの棚があるか」という登録情報だけです。登録とプラグインのインストールは別の処理で、棚を登録しても中身は入りません。入れるには enabledPlugins で有効化しますが、これが実際にインストールまで進むかは、どのファイルに書いたかとプラグインの置き場所で変わります。この分かれ目は次の節で扱います。

もう1つ大事な点があります。この設定は他のマーケットプレイスの追加を止めません。止める側の設定は strictKnownMarketplaces と blockedMarketplaces で、managed settingsにしか書けません。「配る」と「絞る」は別のキーが担います。登録の記録ファイルが壊れた場合の直し方はFailed to load marketplace configurationの直し方にあります。

v2.1.287のCLIで確認できる範囲

手元のClaude Code v2.1.287で、モデルを呼ばず設定も変えない範囲(ヘルプの表示だけ)を確認しました。claude --version の出力は次のとおりです。

claude --version

2.1.287 (Claude Code)

claude plugin marketplace には add list remove update の4つのサブコマンドがあります。add のオプションは4つです。--scope <scope>(userが既定、ほかにprojectとlocal)、--sparse <paths...>、--json、--claudeai でした。--sparse はモノレポ向けで、gitのsparse-checkoutで取得範囲を絞ります。ヘルプの例は --sparse .claude-plugin plugins です。

ここから分かるのは、extraKnownMarketplaces がなくても各自のコマンドでマーケットプレイスは足せる、という事実です。手動追加の既定スコープはuserです。チームで揃えたいのは「全員が同じ登録を持つ状態」で、設定ファイルに書く価値はそこにあります。add が受け取るのは、ヘルプの説明にあるとおり、URL・パス・GitHubリポジトリのいずれかです。

リポジトリに置いて全員に配る

典型的なのは、チームのリポジトリに .claude/settings.json を置く方法です。

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

この設定はコミットしてかまいません。リポジトリを開いた人がワークスペースの信頼ダイアログを承諾すると、company-tools が自動登録されます。信頼していないフォルダでは、メッセージも出さずに無視されます。-p を付けた非対話実行でも同じです。信頼していないリポジトリを開いただけでは何も起きません。

特定のプラグインまで既定で有効にしたい場合は、enabledPlugins を並べます。

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

有効化とインストールは別の話

プロジェクトの .claude/settings.json でGitHubリポジトリなど外部ソースのプラグインを有効化しても、他のメンバーの環境には本体が入りません。プラグインを読み込むどの経路でも「未インストール」と報告され、各自が次のコマンドを実行するまで続きます。

claude plugin install <name>@<marketplace> --scope project

/plugin のErrorsタブには、次のメッセージが出ます。

Plugin "<name>" is enabled in project settings but isn't installed here

公式の組織向けページには、末尾の here がない形で載っています。ただし、自動で入る経路もあります。

公式マーケットプレイス claude-plugins-official は扱いが軽く済みます。名前@claude-plugins-official を enabledPlugins で true にするだけで、マーケットプレイス自体が宣言されます。公式の棚から特定のプラグインを配るだけなら、extraKnownMarketplaces のエントリは不要です。

置き場所に合わせてsourceを選ぶ

extraKnownMarketplaces の各エントリは、名前をキーにして source オブジェクトを入れ子にします。source の形式は6つです。

• github: GitHubリポジトリを repo で指す
• git: 任意のgit URLを url で指す
• url: ホストされた marketplace.json を直接指す
• file: ローカルの marketplace.json を path で指す
• directory: ローカルのディレクトリを path で指す
• settings: ホストされたリポジトリを持たず、設定ファイルの中で直接宣言する

npm はこの6つに含まれません。strictKnownMarketplaces の許可リストにも npm はありません。形式は github git url file directory hostPattern pathPattern skills-dir です。extraKnownMarketplaces に npm を書くと、NPM marketplace sources not yet implemented で読み込みに失敗します。npmパッケージ単体でマーケットプレイスを配る道は、どちらの設定にもありません。npmが関わるのは、個々のプラグインのソースとしてnpmパッケージを指す場合です。marketplace.json のエントリでも、settings 形式のインラインでも書けます。

配布先ごとの向き不向き

社内のgitリポジトリに marketplace.json を置けるなら、github か git が素直です。directory は開発用のほか、組織が各端末に配備したローカルのマーケットプレイスを指す用途が公式に挙がっています。/opt/acme/claude-plugins のようなパスへ配備した棚は、managed settingsから directory で指せます。

url は静的ホスティングだけで済むのが利点ですが、取得するのは marketplace.json だけです。相対パスで書いたプラグイン本体は、同じサーバーから取りに行きません。相対パスのプラグインを配りたいなら、Gitベースのマーケットプレイスに切り替えます。url のままにするなら、プラグイン側のソースをアーカイブURLなど、相対パス以外にします。

リポジトリを用意せず設定ファイルだけで済ませたいときは settings です。次の例は、プラグイン1つを設定の中に直接書いています。

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": { "source": "github", "repo": "acme-corp/code-formatter" }
          }
        ]
      }
    }
  }
}

settings には条件が2つあります。name はマーケットプレイスのキーと一致させます。インラインのプラグインは、GitHubやnpmなど外部のソースを指す必要があります。有効化は enabledPlugins で別に行います。

認証が要る置き場所

github と git で非公開リポジトリを使う場合、認証はそのマシンで git clone が使うものに委ねられます。設定済みのcredential helperかSSH鍵です。GITHUB_TOKEN のようなプロバイダートークンは、それを読むcredential helperを通して初めて効きます。

url 形式で認証が要るときは、source に headers を書きます。トークンの寿命が短くて固定値にできない場合は、headersHelper に、新しいヘッダーを出力するコマンドを指定できます(v2.1.238以降)。実行されるのは marketplace.json を取得する前と、同じオリジンからプラグインのアーカイブをダウンロードする前の2か所で、1回の出力を最大60秒使い回します。--add-dir で追加したディレクトリの設定にある headersHelper は無視される点も、覚えておく価値があります。

Git LFSについては、旧い情報が出回っています。Claude Codeは github と git のマーケットプレイスをクローンするとき、LFSの実体を取得せず、ポインタファイルのまま残します。source の skipLfs は受け付けられますが、v2.1.274以降は効果がありません。v2.1.274より前は、"skipLfs": true を書かない限りLFSの実体をダウンロードしていました。

autoUpdateの既定値は出所で変わる

各エントリには、真偽値の autoUpdate を添えられます。省略したときの既定は一律ではありません。公式Anthropicのマーケットプレイスの大半(claude-plugins-official を含む)は true、サードパーティは false です。

true なら、起動後にバックグラウンドでマーケットプレイスを更新し、入っているプラグインも更新します。社内マーケットプレイスで自動更新させたいなら、"autoUpdate": true を明示します。書き忘れると更新は届かず、手動で claude plugin update(または /plugin のInstalledタブのUpdate now)を実行するまで古いままです。逆に自動更新させたくない外部マーケットプレイスには、false を書いて既定をコードに残しておくと、後から読む人が迷いません。

配布と制限は別のキーで組む

名前は似ていますが、3つのキーの役割はまったく違います。

もう1つの blockedMarketplaces も、managed settingsだけに書ける拒否リストです。書式は許可リストと同じで、「このソースだけ禁止」と書きたいときに使います。追加済みのマーケットプレイスからのインストール・更新・自動更新も止まるので、ポリシーを入れる前に誰かが追加していた棚も使えなくなります。

許可リストの github エントリには、"owner/*" という所有者ワイルドカードが書けます。ただしv2.1.223以降の機能で、strictKnownMarketplaces と blockedMarketplaces でしか効きません。extraKnownMarketplaces や /plugin marketplace add では、repo は1つのリポジトリ名でなければなりません。社内のGitHub EnterpriseやGitLabサーバー全体を許可したいなら、ホスト名の正規表現で照合する hostPattern も使えます。

両方を組み合わせる

配布と制限を同時に実現するには、managed-settings.json に両方を書きます。

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

同じリポジトリを両方のキーに書きます。許可リストがそれ以外の追加を拒み、extraKnownMarketplaces が全ユーザーに登録します。strictKnownMarketplaces だけでは、ユーザーが許可済みの棚を自分で追加するまで、何も登録されません。公式マーケットプレイスだけは、許可リストがそれを許していれば、初回の対話起動で自動登録されます。

この自動登録を当てにできない端末があります。初回の対話起動より前に動く非対話環境、VS Code拡張機能でしか動かしていない端末、空配列のロックダウンのようなポリシーで一度ブロックされた端末です。ブロックされた記録は残り、ポリシーを直しても再試行されません。こうした端末には対処が2つあります。1つは、同じ managed-settings.json の extraKnownMarketplaces に公式マーケットプレイスを足す方法です。もう1つは、端末で claude plugin marketplace add anthropics/claude-plugins-official を明示的に実行する方法です。

disableSideloadFlags も組み合わせる価値があります。strictKnownMarketplaces が絞るのはマーケットプレイス経由の追加です。--plugin-dir や --plugin-url のCLIフラグは、その回だけ許可リストを迂回できてしまいます。disableSideloadFlags を true にすると、この2つに加えて --agents と --mcp-config も起動時に拒否します(v2.1.193以降)。拒否したフラグ名を示すエラーで終了します。ZIP配布での --plugin-url の運用はClaude Codeプラグインをzip配布するで扱っています。

同名のエントリが複数あるときの優先順位

複数の設定ファイルが同じ名前でマーケットプレイスを定義した場合、Claude Codeは最も優先度の高いファイルのエントリを丸ごと採用します。低い優先度のファイルの値は、一部も引き継ぎません。この挙動はv2.1.228以降のものです。

v2.1.228より前は、同名のエントリをフィールド単位でマージしていました。優先度の高いファイルが書いていないフィールドを、低いファイルから引き継げたということです。別のファイルが管理する headers の認証情報が、高優先度側のURLに継ぎ足される危険がありました。古いバージョンが混在する環境では、この差を踏まえて設計します。

キー名には別名もあります。v2.1.232以降は、extraKnownMarketplaces を additionalMarketplaces と書けます。strictKnownMarketplaces の別名は allowedMarketplaces です。古いバージョンは別名を無視するので、混在環境のファイルには正規のキー名を残します。同じファイルに両方の綴りがあれば、正規のキー名の値が優先されます。Claude Codeが設定を更新するとき、additionalMarketplaces を extraKnownMarketplaces に書き換えることもあります。

自動登録が効かないときの切り分け

「配ったはずなのに登録されない」という症状は、次の順に確かめると原因を絞れます。

シードに登録された棚は、--scope なしで update や remove を実行すると失敗します。失敗時のメッセージには、シードディレクトリの名前が出ます。コンテナへの事前展開の手順はプラグインをコンテナへ事前展開する手順にあります。

プラグインが入らない場合は、登録とは別の問題です。前の節で触れた「有効化はされたが未インストール」の状態なら、メッセージに従って claude plugin install を実行します。

strict フィールドと strictKnownMarketplaces の混同も、よくある取り違えです。前者はプラグイン1つの中で定義の権威をどちらに置くかを決め、後者は組織としてどのマーケットプレイスを追加してよいかを決めます。違いはマーケットプレイスのstrict modeとvalidateの使い方で扱っています。GitHub Enterprise Server上で運用しているなら、許可リスト設計はGHESプラグインマーケットプレイスを許可リストで運用するが参考になります。

まとめ

リポジトリ単位の配布は信頼ダイアログ後の登録までで、インストールは外部ソースのプラグインなら各自の操作が残ります。全社の強制はmanaged settingsで組みます。extraKnownMarketplaces、enabledPlugins、strictKnownMarketplaces を揃えます。マーケットプレイスの作り方全体はClaude Codeプラグイン完全ガイドにあります。Claude Codeの導入全体から確認したい場合は、そちらも参照してください。