社内やチームにプラグインを配り始めると、最初のインストールよりも「2回目以降」で事故が起きます。エントリ名を整理したら既存ユーザーがインストールできなくなった、ローカルで直したのに反映されない、不要になったマーケットプレイスを消したらユーザーのプラグインごと消えた——どれも、更新と互換性の扱いを決めないまま運用に入ると踏む落とし穴です。
この記事は、Claude Code のプラグインマーケットプレイスを本番で回すために、「何を凍結された契約として扱い、何をどう更新し、何を壊さないか」を、公式ドキュメントで逐語確認できた仕様（2026-10-07 検証）だけを土台に設計します。
マーケットプレイスの最小構成と、検証で守れる範囲
マーケットプレイスの定義はシンプルです。
A plugin marketplace is a directory or repository with a .claude-plugin/marketplace.json file that lists your plugins and where to fetch each one.
マーケットプレイスとは .claude-plugin/marketplace.json を持つディレクトリまたはリポジトリで、このファイルがプラグイン一覧と各プラグインの取得元を記述します。つまりマーケットプレイスの実体は 1 枚の JSON であり、更新運用とはこの JSON とその参照先をどう管理するかに尽きます。
marketplace.json には name・owner・plugins 配列が必須で、plugins 配列の各エントリには name と source が必要です。最小形は次の通りです。
{
"name": "acme-tools",
"owner": { "name": "ACME Platform Team" },
"plugins": [
{ "name": "hello-logger", "source": "./plugins/hello-logger" }
]
}
この静的な正しさは claude plugin validate で守れます。validate はマーケットプレイスディレクトリ内のファイルだけを読み、JSON 構文エラー・必須フィールド欠落（owner 欠落なら Invalid input）・命名規則違反・.. を含む相対パス・未知フィールドを報告します。逆に言えば、validate が緑でも「取得元が正しくフェッチできるか」は保証されません——後述する remote source の罠がここに関わります。
インストールIDという、壊してはいけない公開契約
プラグインのインストールIDは「エントリ名 + @ + マーケットプレイス名」です。公式の例では my-first-plugin@my-marketplace となり、上の例なら hello-logger@acme-tools です。
ここで本番運用の最大の互換性リスクが出ます。マーケットプレイスのエントリ名（marketplace.json 内）と、プラグイン自身の plugin.json のマニフェスト名がずれていると、マニフェスト名でインストールしようとした人は失敗します。
Plugin "" not found in marketplace ""
マニフェスト名で見つからない旨のこのエラーは、「リネームしたが片方だけ直した」という典型的な更新ミスで発生します。エントリ名・マーケットプレイス名はインストールIDを構成する以上、一度公開したら利用者側のコマンドに焼き付く「公開API」です。整理したくなっても改名ではなく別名の追加で対応するのが安全です。
更新の反映と、バージョンの扱い
ローカルの相対パス source で入れたプラグインの更新挙動には、運用上重要なクセがあります。
Your edits take effect at the next session start or when you run /reload-plugins in a session, with no change to the plugin's version .
編集は次回セッション開始時または /reload-plugins 実行時に反映され、プラグインのバージョン番号は変わりません。つまりローカル開発ではファイルを直すだけで素早く反映できますが、plugin.json の version は自動では上がりません。バージョンはリリース手順の中で人が明示的に上げるものだ、と割り切る必要があります。
一方 remote source は性質が違います。github・git-subdir などの remote source は、インストール時に初めてフェッチされます。したがってリポジトリやパスの誤りは validate では出ず、インストール段階で初めて表面化します。source タイプには少なくとも url（任意ホストの git リポジトリURL）・archive（HTTPS 経由の zip）・npm・command（マシン上でコマンドを実行して生成されるディレクトリ）があり、全タイプの一覧は「Plugin sources」ページ側に委ねられています。
本番運用で避けたい落とし穴
まず、マーケットプレイスの削除は破壊的です。
The command removes the marketplace and uninstalls its plugins.
削除コマンドはマーケットプレイスの登録を解除し、そのマーケットプレイスからインストールされた全プラグインをアンインストールします。したがって「このプラグインはもう薦めない」を remove で表現すると、利用者の環境から実際に消えてしまいます。廃止はエントリを残したまま非推奨扱いにする運用で行うべきです（なお削除コマンドの正確な構文は本稿の検証範囲外のため、該当ページで確認してください）。
次に、名前の予約です。予約済みの名前でマーケットプレイスを追加しようとすると、The name '<name>' is reserved for official Anthropic marketplaces で始まるメッセージで拒否されます。社内マーケットプレイスには固有プレフィックスを付け、予約名との衝突を避けます。
最後に配布形態です。管理者はマーケットプレイスを組織の全マシンに必須として設定できます（設定方法は本稿の検証範囲外）。全社必須にする前に、CI で validate を通し、remote source については実際のインストールまで試すことを強く勧めます。