【Claude Code 連載第56回】プラグインマーケットプレイス — カタログを作って配る

よっしー

こんにちは。よっしーです(^^)

背景
1. 一言でいうと何か
2. どういう場面で役立つか
3. 実例と解説
4. まとめ＋次回予告

背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

1. 一言でいうと何か

プラグインマーケットプレイスは、プラグインを他人に配布するためのカタログです。実体は .claude-plugin/marketplace.json という1つの JSON ファイルで、それを Git リポジトリに置いて共有します。

第55回でプラグインの中身の仕様を扱いました。今回はその外側——配布経路です。マーケットプレイスが提供するのは4つ：一元化された検出、バージョン追跡、自動更新、複数ソースタイプのサポート（Git リポジトリ、ローカルパス、npm など）。

作業の流れは4ステップです。

プラグインを作る（第55回の範囲）
marketplace.json を書く——プラグインとその取得場所を列挙する
ホストする——GitHub、GitLab、その他の Git ホストにプッシュ
共有する——ユーザーが /plugin marketplace add で追加し、個別にインストール

ライブになった後の更新は、リポジトリに変更をプッシュするだけ。ユーザー側は /plugin marketplace update でローカルコピーを更新します。

ここで最初に区別しておくべき2つの概念があります。マーケットプレイスソースとプラグインソースは別物です。

マーケットプレイスソース：marketplace.json カタログ自体をどこから取るか。/plugin marketplace add か extraKnownMarketplaces 設定で決まる。ref（ブランチ／タグ）は使えるが sha は使えない。
プラグインソース：カタログに載っている個々のプラグインをどこから取るか。各エントリの source フィールド。ref と sha の両方が使える。

つまり acme-corp/plugin-catalog にあるマーケットプレイスが、acme-corp/code-formatter から取るプラグインを載せられる。両者は別リポジトリを指し、独立にピン留めされます。

2. どういう場面で役立つか

シーン1：チームに社内プラグインを配る

GitHub にリポジトリを1つ作り、marketplace.json を置くだけ。ユーザーは /plugin marketplace add owner/repo で追加します。組み込みのバージョン管理、issue 追跡、コラボレーション機能がそのまま使えるのが GitHub 推奨の理由です。

シーン2：安定版と最新版のチャネルを分ける

同じリポジトリの異なる ref を指すマーケットプレイスを2つ用意し、管理設定でユーザーグループごとに割り当てます。安定グループには stable-tools、早期アクセスには latest-tools、という形です。

シーン3：組織のプラグインソースを厳密に制御する

管理者は strictKnownMarketplaces でユーザーが追加できるマーケットプレイスを制限できます。完全ロックダウン（空配列）から、社内 Git サーバーのホスト名パターン許可まで。

シーン4：コンテナや CI に事前組み込みする

CLAUDE_CODE_PLUGIN_SEED_DIR を使うと、**ビルド時にプラグインを焼き込んで、実行時のクローンをゼロにできます。**エアギャップ環境や、起動時間を削りたい CI で効きます。

不要・向かないケース

marketplace.json への直接 URL で配りたいが、相対パスのプラグインがある。機能しません。URL 追加はそのファイルだけをダウンロードするので、./plugins/my-plugin は解決できません（後述）。
Anthropic 公式に見える名前を使いたい。予約されています（後述）。
プラグインの name を気軽に変えたい。**既存インストールが全部壊れます。**UI 上のラベルだけ変えたいなら displayName を使ってください。
plugin.json とマーケットプレイスエントリの両方に version を書きたい。避けるべきです——plugin.json の値が常に無言で優先するので、古いマニフェストのバージョンがカタログ側の指定をマスクします。
オフライン環境で自動更新に任せたい。再クローンが繰り返し失敗します。CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 かシードディレクトリを使います。

3. 実例と解説

チュートリアル：ローカルマーケットプレイスを作る

1プラグイン（コードレビュー用の quality-review skill）を含む最小構成を作ります。ディレクトリはこう作ります。

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

.claude-plugin/ が2箇所に出てくるのがポイントです。マーケットプレイスルート側には marketplace.json、プラグイン側には plugin.json が入ります。

skill を書きます。

---
description: Review code for bugs, security, and performance
---
Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements
Be concise and actionable.

プラグインマニフェスト。

{
  "name": "quality-review-plugin",
  "description": "Adds a quality-review skill for quick code reviews",
  "version": "1.0.0"
}

そしてカタログ。

{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quality-review skill for quick code reviews"
    }
  ]
}

追加してインストールします。

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

呼び出しはプラグイン名でネームスペース化されます。

/quality-review-plugin:quality-review

マーケットプレイススキーマ

必須は3つだけ——name（ケバブケース）、owner（name 必須・email 任意）、plugins（配列）。

name について重要な制約が2つあります。これは公開向けの識別子で、ユーザーが /plugin install my-tool@your-marketplace と打つときに現れます。そして各ユーザーは1つのマーケットプレイス名につき1つしか登録できません——同じ名前で2つ目を追加すると最初が置き換わります。1つの名前で複数プラグインを配るなら、すべてを単一の marketplace.json に列挙します。

予約名の話は無視できません。以下は Anthropic 公式用に予約されており、サードパーティは使えません：claude-code-marketplace、claude-code-plugins、claude-plugins-official、claude-plugins-community、claude-community、anthropic-marketplace、anthropic-plugins、agent-skills、anthropic-agent-skills、knowledge-work-plugins、life-sciences、claude-for-legal、claude-for-financial-services、financial-services-plugins、first-party-plugins、healthcare。加えて公式になりすます名前（official-claude-plugins、anthropic-plugins-v2 など）もブロックされます。

チェックのタイミングが厳しい点に注意してください。追加時だけでなく、読み込むたびに再チェックされます。既に登録済みのマーケットプレイスの名前が後から予約対象になると、読み込みが停止して「信頼できないソースから登録されている」と報告されます。その場合は削除して公式ソースから追加し直すか、サードパーティなら別名で追加し直せばすぐ読み込まれます。（v2.1.205 より前は first-party-plugins と healthcare が未予約で、既登録のものは読み込まれ続けていました。）

オプションフィールドで実用的なのは3つ。

metadata.pluginRoot：相対ソースパスの前に付く基本ディレクトリ。"./plugins" にすれば、各エントリは "source": "formatter" と短く書けます。
allowCrossMarketplaceDependenciesOn：このマーケットプレイスのプラグインが依存してよい他のマーケットプレイス。ここに無いものからの依存はインストール時にブロックされます。
renames：名前変更・削除の移行マップ（後述）。v2.1.193 以降。

プラグインエントリ

必須は name と source の2つ。加えて**plugin.json のフィールド（description / version / author / commands / hooks など）を書ける**うえ、マーケットプレイス固有の source / category / tags / strict / relevance が使えます。

第55回と対応する重要フィールドを挙げると——displayName（v2.1.143 以降、UI 表示専用で名前空間には使わない）、defaultEnabled（v2.1.154 以降。plugin.json の同名フィールドより優先）、relevance（v2.1.152 以降。Claude Code がこのプラグインを提案するタイミングのシグナル。管理者が管理設定でホワイトリスト登録したマーケットプレイスでのみ有効）。

プラグインソースの5種類

ソース	型	フィールド	注記
相対パス	string（`"./my-plugin"`）	—	マーケットプレイスリポジトリ内。`./` で始まり、マーケットプレイスルート（`.claude-plugin/` ではない）に相対解決
`github`	object	`repo`、`ref?`、`sha?`
`url`	object	`url`、`ref?`、`sha?`	Git URL ソース
`git-subdir`	object	`url`、`path`、`ref?`、`sha?`	スパースクローンで帯域を最小化
`npm`	object	`package`、`version?`、`registry?`	`npm install` でインストール

ref と sha の両方が指定されている場合、有効なピンは sha です。Claude Code はピンされたコミットを直接取得します。

そして実運用で効く挙動：GitHub / GitLab / Bitbucket など多くのホストでは、ref のブランチやタグが上流で削除されていても、コミットがリポジトリから到達可能ならインストールは成功します。ただしAWS CodeCommit のように SHA でのコミット取得に非対応なサーバーでは、ref が存在し、そこからピンされたコミットに到達できる必要があります。

相対パスは1行です。

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

../ でマーケットプレイスルートの外を参照してはいけません。そして前述のとおり、marketplace.json への直接 URL でマーケットプレイスを追加した場合、相対パスは解決されません（そのファイルしかダウンロードされないため）。URL ベースで配るなら GitHub / npm / Git URL ソースを使います。

GitHub は owner/repo 形式で、ブランチ・タグ・コミットにピンできます。

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

url ソースも形は同じです（repo が url になるだけ）。.git サフィックスは任意なので、Azure DevOps と AWS CodeCommit のサフィックスなし URL も動きます。

モノレポには git-subdir が効きます。

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

url は GitHub ショートハンド（owner/repo）や SSH URL も受け付けます。

npm はプライベートレジストリにも対応します。

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

strict — 誰がコンポーネントの権威か

strict は、plugin.json がコンポーネント定義（skills、agents、hooks、MCP サーバー、出力スタイル）の権威かどうかを決めます。

true（デフォルト）：plugin.json が権威。マーケットプレイスエントリは追加のコンポーネントで補足でき、両方がマージされる。
false：マーケットプレイスエントリが完全な定義。プラグイン側に plugin.json があってコンポーネントを宣言していると競合になり、読み込みに失敗する。

使い分けは明快です。ふつうは true。false はマーケットプレイス運営者が完全に制御したい場合——プラグインリポジトリは生ファイルを提供し、どのファイルを skill / agent / hook として公開するかはカタログ側が決める。作者の意図とは違う形で再構成・キュレートしたいときの仕組みです。

skills パスの扱い（共有フォルダの罠）

デフォルトでは、プラグインの skills は source 直下の skills/ から読まれ、skills フィールドに書いたパスはそのスキャンに追加されます。

"skills": ["./skills/", "./extra-skills/"]

ただし例外があります。複数のエントリがマーケットプレイスルート（source: "./"）で1つの skills/ フォルダを共有する場合、各エントリが自分の skill だけを読むように個別のサブディレクトリを列挙します。

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

このときは列挙したパスがそのエントリの完全なセットになり、共有 skills/ 内の他のディレクトリは読まれません。./skills/ 自体やプラグインルートを列挙すれば完全スキャンが維持され、列挙したパスが存在しない場合はデフォルトスキャンが走ります。

ホスティングと配布

GitHub が推奨です。リポジトリを作り、.claude-plugin/marketplace.json を置き、/plugin marketplace add owner/repo で共有。GitLab / Bitbucket / 自己ホストでも、完全なリポジトリ URL で追加できます。

プライベートリポジトリの扱いには段差があります。

手動のインストールと更新は素直です。既存の Git 認証情報ヘルパーを使うので、HTTPS は gh auth login / macOS キーチェーン / git-credential-store 経由で動き、ターミナルと同じ挙動になります。SSH も、ホストが known_hosts にあり、キーが ssh-agent に読み込まれていれば動きます（Claude Code はフィンガープリントとパスフレーズの対話プロンプトを抑制するため）。なお GitHub の owner/repo ショートハンドは既定で SSH クローンで、HTTPS にしたければ CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 を設定します。

問題はバックグラウンド自動更新です。既定でバックグラウンドの git pull は Git 認証情報ヘルパーを無効化するので、ヘルパーを設定していても HTTPS のプライベートリポジトリには認証できません（SSH リモートは影響なし）。失敗するとゼロから再クローンにフォールバックし、そちらは保存済み認証情報を使いますが大きなリポジトリではタイムアウトしうる——結果としてプライベートマーケットプレイスの自動更新は断続的に失敗しうる。

対策は3系統あります。CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 で既存クローンを保持する（最後に同期した状態で動き続け、手動更新は認証情報でプルできる）。gh auth setup-git などで認証情報ヘルパーを設定して再クローンをプロンプトなしで通す。そしてグローバルな Git URL リライト——これだけがバックグラウンドプル自体を HTTPS で認証させます（トークンがリモート URL に埋め込まれるため、ヘルパー無効化の影響を受けない）。

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

リライトは必ずリポジトリか組織パスにスコープしてください。ホストだけを対象にすると、そのホストへの全フェッチ・全プッシュに適用され、自分のリポジトリへのプッシュの認証情報まで上書きします。ユーザー名はプロバイダーごとに違い、GitHub は x-access-token、GitLab は oauth2、Bitbucket は x-token-auth。そしてトークンは gitconfig に平文で保存されるので、読み取り専用トークンを使うこと。

なお GITHUB_TOKEN を環境に置くだけではバックグラウンド認証は有効になりません。トークンは設定済みの認証情報ヘルパー経由でのみ効きます（gh CLI のヘルパーは GH_TOKEN と GITHUB_TOKEN を読みます）。

チームにマーケットプレイスを要求する

.claude/settings.json に書けば、チームメンバーがプロジェクトフォルダを信頼したときに自動的にインストールを促されます。

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

既定で有効にするプラグインも指定できます。

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

worktree 利用者向けの注記が1つ。ローカルの directory / file ソースを相対パスで使うと、パスはリポジトリのメインチェックアウトに対して解決されます。worktree から起動してもメインチェックアウトを指し続けるので、全 worktree が同じマーケットプレイス位置を共有します。マーケットプレイス状態はプロジェクト単位ではなくユーザー単位で ~/.claude/plugins/known_marketplaces.json に保存されます。

コンテナ用にプラグインを事前入力する

CLAUDE_CODE_PLUGIN_SEED_DIR を使うと、ビルド時にプラグインディレクトリを焼き込み、実行時のクローンなしで起動できます。複数のシードをUnix は :、Windows は ; で区切ってレイヤーでき、先に見つかったものが優先します。

シードは ~/.claude/plugins の構造をミラーします。

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

作り方は2通り。ビルド中に Claude Code を1回動かして必要なプラグインを入れ、~/.claude/plugins をイメージにコピーするか、CLAUDE_CODE_PLUGIN_CACHE_DIR をシードパスにしてコピー工程を省くか。

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

挙動で押さえるべき点が5つ。シードは読み取り専用（読み取り専用 FS で git pull が失敗するため自動更新は無効）。シードのエントリがユーザー設定の同名エントリを起動時に上書きする（オプトアウトはマーケットプレイス削除ではなく /plugin disable）。パスは実行時にプローブして解決されるので、ビルド時と違う場所にマウントしても動く。シード管理のマーケットプレイスに remove / update を実行すると失敗し、管理者にイメージ更新を促すガイダンスが出る。そして**extraKnownMarketplaces や enabledPlugins がシードに既にあるものを宣言していれば、クローンせずシードのコピーを使う**。

管理者による制限

strictKnownMarketplaces は管理設定で指定し、ユーザーとプロジェクトの設定では上書きできません。

値	動作
未定義（デフォルト）	制限なし
空配列 `[]`	完全ロックダウン。新規追加不可
ソースのリスト	ホワイトリストと正確に一致するものだけ追加可

完全ロックダウンはこれだけです。

{
  "strictKnownMarketplaces": []
}

GitHub Enterprise Server や自己ホスト GitLab には hostPattern が推奨されています。

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

pathPattern（ファイルシステム上のパスを正規表現で許可）もあり、".*" にすればネットワーク側を hostPattern で締めつつ任意のローカルパスを許可できます。

制限の効き方で重要なのはタイミングと厳密さです。チェックはネットワーク／ファイルシステム操作の前に走り、追加時だけでなくインストール・更新・リフレッシュ・自動更新でも実行されます。ポリシー設定より前に追加されたマーケットプレイスでも、ソースが一致しなくなればプラグインのインストールと更新が拒否されます（blockedMarketplaces も同じ）。

そして**正確マッチは URL を正規化しません。末尾スラッシュ、.git サフィックス、ssh:// と https:// の違いは別の値として扱われます。**複数の URL 形式でクローンされうる組織なら、リテラル URL より hostPattern を優先すべきです。

補足として、strictKnownMarketplaces は追加できるものを制限するだけで、自動登録はしません。自動的に使えるようにするには同じ managed-settings.json で extraKnownMarketplaces と併用します。関連して、CLI フラグでプラグイン・エージェント・MCP サーバーをサイドロードするのを拒否する disableSideloadFlags、提案として表示できるマーケットプレイスを絞る pluginSuggestionMarketplaces もあります。

バージョン解決とリリースチャネル

解決順は第55回と同じ構造ですが、マーケットプレイス側の version が2番目に入るのが違いです。

プラグインの plugin.json の version
マーケットプレイスエントリの version
プラグインソースの Git コミット SHA

Git ベースのソースなら version を完全に省略でき、すべての新規コミットが新バージョン扱いになります。内部・開発中のプラグインにはこれが最も簡単です。

警告は第55回と同じですが、ここではもう一段厳しい注意が加わります。plugin.json とマーケットプレイスエントリの両方に version を書かないでください。plugin.json の値が常に無言で優先するため、古いマニフェストのバージョンがカタログ側の指定をマスクします。

リリースチャネルは、同じリポジトリの異なる ref を指すマーケットプレイスを2つ作り、管理設定でグループに割り当てて実現します。ここに落とし穴があります——各チャネルは異なるバージョンに解決されなければなりません。明示バージョンを使うなら各 ref の plugin.json が異なる version を宣言する必要があり、省略するならコミット SHA が自動的にチャネルを区別します。2つの ref が同じバージョン文字列に解決されると、Claude Code は同一とみなして更新をスキップします。

プラグインの名前変更と削除

name は安定識別子です。enabledPlugins、pluginConfigs、/plugin install コマンドで参照されるので、**変えると既存インストールが全部壊れます。**UI のラベルだけ変えたいなら displayName を設定して name は据え置きです。

それでも変える／削除する必要があるときのために renames があります（v2.1.193 以降）。

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

挙動は3通り。新しい名前を指すエントリなら、新名で読み込んで1行の通知を出し、ユーザー・プロジェクト・ローカルの各スコープで enabledPlugins と pluginConfigs のキーを書き換えるので通知は1回だけ。null エントリなら古いキーを削除し、削除された旨を通知。ただし**github や npm などリモートソースのプラグインを名前変更した場合は plugin-cache-miss が報告され、ユーザーが新名で /plugin install を1回実行する必要**があります。

運用上の指針が明確です。renames は追加のみの履歴として扱い、全員が移行したと思っても古いエントリを残す。Claude Code はチェーンを辿るので、後で code-formatter を formatter-pro にするなら最初のエントリを編集せず2つ目を追加します。そうすれば元の formatter のままのユーザーも両エントリを通って解決されます。編集後は claude plugin validate . を実行してください——サイクルや、null にも plugins の名前にも行き着かないエントリを拒否してくれます。

なお**管理設定とポリシー設定は読み取り専用なので自動で書き換えられません。**名前変更されたプラグインは読み込まれ続けますが、管理者が管理設定の enabledPlugins を新名に更新するまで通知が毎セッション繰り返されます。--add-dir などの読み取り専用ソースも同様です。

検証とテスト

配布前の検証はこれです。

claude plugin validate .

マーケットプレイスディレクトリを指定した場合、バリデータは marketplace.json のスキーマエラー、プラグイン名の重複、ソースパストラバーサルをチェックし、source がローカルパスのエントリについては、そのプラグインの plugin.json も検証して、エントリの version が plugin.json と一致しない場合に警告します（問題は plugins[2] plugin.json → の形で報告）。

v2.1.196 以降は、source が . のプラグイン、marketplace.json が .claude-plugin の外にある場合の解決、ファイルの別部分にスキーマエラーがあっても各エントリの問題を報告することも加わりました。

個別プラグインの plugin.json と skill / agent / command / hook ファイルを検証したいなら、プラグインディレクトリ自体を指定します（claude plugin validate ./plugins/my-plugin）。

警告のうち1つは配布に直結します。Plugin name "x" is not kebab-case——Claude Code 自体は他の形式も受け付けますが、claude.ai のマーケットプレイス同期は拒否します。

CLI コマンド

対話セッションの /plugin marketplace と同等の非対話コマンドがあります。

コマンド	役割	押さえどころ
`claude plugin marketplace add <source>`	追加	`--scope`（`user` / `project` / `local`）、`--sparse <paths...>` でモノレポのチェックアウトを限定。GitHub ショートハンドは `@ref`、Git URL は `#ref` でピン
`claude plugin marketplace list`	一覧	`--json` でソース種別ごとのフィールド（`repo` / `url` / `path`、ピンした場合は `ref`）が出る
`claude plugin marketplace remove <name>`	削除	引数は渡したソースではなく `marketplace.json` の `name`。`--scope` 省略時は全編集可能スコープから削除。エイリアス `rm`
`claude plugin marketplace update [name]`	更新	`ref` 付きで追加したものはその ref の最新コミットへ。省略で全件

add の入力形式に v2.1.196 の変更があります。URL はスキーム必須になり、gitlab.example.com/team/plugins のようにスキームなしで書くと無効な owner/repo ショートハンドとして拒否され、https:// を足すかローカルパスなら ./ を使えというエラーが出ます。以前のバージョンは GitHub のリポジトリパスと誤読して、GitHub の not found で失敗していました。

remove には強い警告があります。**最後に残ったスコープから削除すると、そこからインストールしたプラグインもアンインストールされます。**インストール済みを失わずに更新したいなら update を使ってください。

そして remove と update はどちらもシード管理のマーケットプレイスに対しては失敗します（全件更新時はスキップされ、他は更新されます）。

トラブルシューティングの要点

代表的なものを4つ。

オフライン環境で更新が失敗し続ける → git pull 失敗後の再クローンも失敗し、各セッションが失敗を繰り返し、各 git 操作が120秒のタイムアウトを待つ。CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 で再クローンを飛ばすか、シードディレクトリを使う。

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Git 操作がタイムアウトする → すべての Git 操作が120秒。大きなリポジトリや遅い回線では伸ばす。

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 分

URL ベースのマーケットプレイスで相対パスのプラグインが失敗 → 前述のとおり。外部ソース（GitHub / npm / Git URL）に変えるか、Git リポジトリでホストして Git URL で追加する（リポジトリ全体がクローンされるので相対パスが効く）。
インストール後にファイルが見つからない → プラグインはキャッシュにコピーされるので、プラグインディレクトリ外への参照は機能しない（第55回のシンボリックリンク3分岐を参照）。

4. まとめ＋次回予告

マーケットプレイスは .claude-plugin/marketplace.json 1枚。必須は name / owner / plugins。GitHub ホストが推奨。
**マーケットプレイスソースとプラグインソースは別物。**前者は ref のみ、後者は ref と sha の両方が使え、独立にピンできる。
**マーケットプレイス名は1ユーザーにつき1つ。**同名を追加すると置き換わる。予約名（16個＋なりすまし名）は使えず、読み込みのたびに再チェックされる。
ソースは相対パス / github / url / git-subdir / npm の5種。sha が ref に優先。モノレポは git-subdir でスパースクローン。
strict: false はカタログ側が完全に定義するモード。プラグイン側がコンポーネントを宣言していると失敗する。
source: "./" を共有する複数エントリでは、skills に列挙したパスが完全なセットになる（追加ではなく置き換え）。
プライベートリポジトリのバックグラウンド更新は既定で HTTPS 認証できない。KEEP_MARKETPLACE_ON_FAILURE、認証情報ヘルパー、リポジトリにスコープした URL リライトのいずれかで対処する。
**CLAUDE_CODE_PLUGIN_SEED_DIR でコンテナに事前焼き込みできる。**読み取り専用で自動更新は無効、シードが設定を上書きする。
strictKnownMarketplaces は正確マッチで URL を正規化しない。hostPattern を優先する。チェックは追加時だけでなく更新・自動更新でも走る。
version は片方だけに書く。plugin.json が常に無言で勝つ。リリースチャネルは異なるバージョンに解決される必要がある。
**name を変えたら renames を追加する。**追加のみの履歴として残し、チェーンで辿らせる。管理設定は自動で書き換わらない。
**marketplace remove は最後のスコープから消すとプラグインごと消える。**更新目的なら update を使う。

第54〜56回で「作る（channels-reference）→ 包む（plugins-reference）→ 配る（plugin-marketplaces）」が揃いました。残るのは受け取る側です。

次回予告（暫定）：**プラグインの検出とインストール（discover-plugins）**を取り上げ、ユーザー側の視点——マーケットプレイスの追加方法、プラグインの探し方、インストールと管理——を扱う予定です。