背景

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

1. これは一言でいうと何か

プラグインマーケットプレイスは、他のユーザーにプラグインを配布するためのカタログです。実体はリポジトリに置く .claude-plugin/marketplace.json 1ファイルで、ここに「どのプラグインが」「どこから取れるか」を並べます。

前回（第10回）で作ったプラグインは、--plugin-dir で手元では動きますが、配るには手渡しが要ります。マーケットプレイスを挟むと、一元化された検出、バージョン追跡、自動更新、複数ソースタイプ（Git リポジトリ、ローカルパスなど）のサポートが手に入ります。利用者は /plugin marketplace add して /plugin install するだけになります。

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

• チームに配って更新も届けたい：リポジトリに変更をプッシュすれば、利用者は /plugin marketplace update でローカルコピーを更新できます。手動コピーの運用から抜けられます。
• 社内リポジトリを1つのカタログに束ねたい：プラグイン本体は別リポジトリでも構いません。マーケットプレイスの source に GitHub リポジトリや npm パッケージ、Git サブディレクトリを指定できます。モノレポの一部だけを配りたいなら git-subdir がスパースクローンで取得します。
• チーム参加時に自動でセットアップさせたい：リポジトリの .claude/settings.json に extraKnownMarketplaces を書いておくと、メンバーがプロジェクトフォルダを信頼したときにインストールを促されます。enabledPlugins で既定有効にするプラグインも指定できます。
• 安定版と最新版を出し分けたい：同じリポジトリの別 ref を指す2つのマーケットプレイスを用意し、管理設定でユーザーグループごとに割り当てます。

向かないケース・注意すべきケース。

1. 個人利用だけなら不要です。手元で完結するなら --plugin-dir、あるいは ~/.claude/skills/ に置く skills-dir 形式で十分で、カタログを作る手間に見合いません。
2. marketplace.json への直リンク URL で配るなら、相対パスは使えません。 URL 追加ではそのファイルしかダウンロードされないため、"./plugins/my-plugin" のようなソースは解決に失敗します。URL 配布なら GitHub / npm / Git URL ソースを使ってください。
3. プラグインディレクトリの外を参照する設計は破綻します。 インストール時にプラグインはキャッシュへコピーされるため、../shared-utils のような参照先はコピーされません。共有が要るならシンボリックリンクを使います。

3. コード・コマンドの実例と解説

前提条件

• 配布するプラグインが既にあること（作り方は第10回）。
• マーケットプレイス名は公開されます。 利用者は /plugin install my-tool@your-marketplace の形で目にします。ケバブケースで、スペースなし。
• 1ユーザーにつき同名マーケットプレイスは1つだけ登録できます。同名を追加すると先のものが置き換わるため、複数プラグインを配るなら1つの marketplace.json にまとめて並べます。
• claude-plugins-official や anthropic-plugins など、Anthropic 公式用の名前は予約されており使えません（なりすまし名もブロックされます）。

最小のカタログを書く

{
  "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"
    }
  ]
}

リポジトリルートの .claude-plugin/marketplace.json に置きます。必須は name / owner / plugins の3つで、各プラグインエントリの必須は name と source だけです。相対パスは ./ で始め、マーケットプレイスルート（.claude-plugin/ を含むディレクトリ）を基準に解決されます。../ で外に出てはいけません。

追加してインストールする

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

配布前のローカルテストがそのままこの2行です。インストール後、スキルはプラグイン名で名前空間化されるので /quality-review-plugin:quality-review のように呼び出します。本番では add の引数を owner/repo や Git URL に差し替えるだけです。

外部リポジトリのプラグインを載せる

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

source をオブジェクトにすると、GitHub リポジトリを指定できます。ref はブランチ／タグ、sha は40文字のコミット SHA で、両方あるときは sha が有効なピンです。同様に url（任意の Git URL）、git-subdir（モノレポのサブディレクトリ）、npm（npm install で取得）が使えます。

検証する

claude plugin validate .

共有前に必ず通します。マーケットプレイスディレクトリを指すと、スキーマエラー、プラグイン名の重複、.. を含む危険なソースパスを検出します。source がローカルパスのエントリについては、そのプラグインの plugin.json も検証し、エントリ側の version と plugin.json の version が食い違えば警告します。個別プラグインの SKILL.md や hooks.json まで見たい場合は、そのプラグインディレクトリを指して実行します。

チームに配る

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

リポジトリの .claude/settings.json に置くと、メンバーがプロジェクトを信頼した時点でマーケットプレイスのインストールを促されます。あわせて enabledPlugins に "code-formatter@company-tools": true のように書けば、既定で有効なプラグインも指定できます。

名前を変える・消すときは移行を書く

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

プラグインの name は安定識別子で、利用者の enabledPlugins や pluginConfigs から参照されています。変えると既存インストールが壊れます。 表示ラベルだけ変えたいなら displayName を使い、name は据え置くのが正解です。どうしても改名・削除するなら renames に「旧名 → 新名」（削除なら null）を書けば、利用者側の設定キーが自動で書き換わります（v2.1.193 以降）。このマップは追記のみで運用し、古いエントリは残しておきます。

その他（metadata.pluginRoot、strict モード、category / tags / defaultEnabled などのオプション、relevance、プライベートリポジトリ認証と git URL リライト、CLAUDE_CODE_PLUGIN_SEED_DIR によるコンテナ事前入力、strictKnownMarketplaces による組織的制限、claude plugin marketplace の各サブコマンドとオプション、コミュニティマーケットプレイスへの送信）は公式ドキュメントを参照してください。

4. まとめと次回予告

• マーケットプレイスは .claude-plugin/marketplace.json 1枚。必須は name / owner / plugins だけです。
• ローカルで add → install → claude plugin validate . の順に確認してから配ります。
• 配布後に効いてくるのはバージョン運用と名前の安定性。name は変えない、変えるなら renames を書く。

最も事故りやすいのはバージョンの扱いです。 Claude Code はバージョンを「プラグインの plugin.json の version」→「マーケットプレイスエントリの version」→「ソースのコミット SHA」の順に解決します。ここで version を "1.0.0" のまま新しいコミットをプッシュしても、利用者には何も届きません。同じバージョンだと判断され、キャッシュが保持されるためです。リリースのたびに必ずバンプするか、いっそ version を省略してコミット SHA を使わせる（=全コミットが新バージョン扱い）かの二択です。

もう1点、plugin.json とマーケットプレイスエントリの両方に version を書かないでください。 plugin.json 側が常に無言で優先されるため、古いマニフェストのバージョンが marketplace.json の指定をマスクします。

次回予告：連載の締めくくりとして、実務での使い方をまとめた「ベストプラクティス」を取り上げる予定です。

関連ページ（本記事で触れた概念の詳細）：プラグイン本体の作り方 →「プラグインを作成する」、完全な技術仕様とキャッシュ挙動 →「プラグインリファレンス」、利用者側の操作 →「既成プラグインの検出とインストール」、extraKnownMarketplaces と strictKnownMarketplaces →「設定」、依存関係のバージョン制限 →「プラグイン依存関係」。

---

本記事は執筆時点の公式ドキュメント（プラグインマーケットプレイスの作成と配布）に基づきます。最新は公式ドキュメントをご確認ください。