プラグインマーケットプレイスを作って配布する

Claude Code のプラグインマーケットプレイスは、自作のプラグインをチームや社外に配るためのカタログです。マーケットプレイスを1つ用意しておくと、利用者はコマンド2行でプラグインを導入でき、更新もリポジトリに push するだけで届きます。この記事では marketplace.json の書き方から、GitHub での公開、チーム全員への自動配布までを順に説明します。

マーケットプレイスとは何か

マーケットプレイスは、プラグインの一覧と取得先を書いたカタログです。プラグインそのものを含むわけではありません。「どのプラグインが、どこにあるか」を並べた索引だと考えてください。

カタログの形にしておくと、単にリポジトリを配る場合と比べて次の4つが得られます。

まとめて見つけられる: 利用者はマーケットプレイスを1つ追加すれば、その中の全プラグインを一覧できます。
バージョンを追える: プラグインごとに version を持てます。
自動で更新される: リポジトリを更新すれば、利用者側にも反映されます。
取得先を混ぜられる: git リポジトリとローカルパスなど、複数の種類の取得先を1つのカタログに並べられます。

作業の流れは4段階です。

プラグインを作る: スキル、エージェント、フック、MCP サーバー、LSP サーバーなどを持つプラグインを用意します。作り方はClaude Code のプラグインを作るを参照してください。
カタログを作る: どのプラグインをどこから取るかを marketplace.json に書きます。
公開する: GitHub、GitLab などの git ホストに push します。
共有する: 利用者が /plugin marketplace add で追加し、個々のプラグインを導入します。

公開後に内容を変えたときは、利用者側は /plugin marketplace update で手元のコピーを更新します。

最小構成をローカルで試す

いきなり公開せず、ローカルディレクトリで一度動かしてみるのが確実です。次の構成は、コードレビュー用のスキルを1つ持つプラグインを、1つのマーケットプレイスに載せた最小の形です。

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/plugin.json に置きます。

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

version を設定すると、そのプラグインはこの文字列に固定されます。つまりこの値を変えないかぎり利用者に更新が届きません。リリースのたびに上げてください。

あとは my-marketplace を含むディレクトリから Claude Code を起動し、次の2行を実行します。導入コマンドはプラグインの詳細画面を開き、そこで導入スコープを選んで確定します。導入結果に Run /reload-plugins to activate. と出たときは、そのコマンドも実行してください。

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

プラグイン由来のスキルはプラグイン名で名前空間が付きます。上の例なら /quality-review-plugin:quality-review で呼び出せます。

marketplace.json を書く

カタログはリポジトリのルートに .claude-plugin/marketplace.json として置きます。必須のフィールドは name、owner、plugins の3つだけです。

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

必須フィールド

フィールド	型	説明
`name`	string	マーケットプレイスの識別子。ケバブケースで空白を含めない。利用者から見える名前で、導入時に `/plugin install my-tool@your-marketplace` の形で現れる
`owner`	object	管理者の情報。`name` が必須で、`email` と `url` は任意
`plugins`	array	提供するプラグインの一覧

name について、実務で効いてくる制約が2つあります。

1つ目は1利用者あたり同じ名前のマーケットプレイスは1つだけという点です。同じ名前で2つ目を追加すると、1つ目が置き換わります。1つの名前で複数のプラグインを配りたいなら、それらを1つの marketplace.json にまとめて列挙してください。

2つ目は予約名です。Anthropic 公式用に予約されており、第三者は使えない名前があります。claude-code-marketplace、claude-code-plugins、claude-plugins-official、anthropic-marketplace、anthropic-plugins、agent-skills などです。official-claude-plugins のように公式を装う名前も同様に拒否されます。予約名の判定はマーケットプレイスを読み込むたびに行われるため、後から予約された名前で登録済みだった場合、読み込み自体が止まります。その場合は一度削除し、別の名前で追加し直してください。

主な任意フィールド

フィールド	型	説明
`$schema`	string	エディタの補完・検証用の JSON Schema URL。Claude Code は読み込み時にこの値を無視する
`description`	string	マーケットプレイスの短い説明
`version`	string	カタログ自体のバージョン
`metadata.pluginRoot`	string	プラグインの取得先名を相対解決する基準ディレクトリ
`renames`	object	旧プラグイン名から現在の名前への対応表。削除した場合は `null` を指す。既存利用者を自動的に移行させられる

プラグインの項目

plugins の各項目で必須なのは name と source の2つです。source は文字列（相対パス）でも、オブジェクト（{"source": "github", "repo": "..."} など）でも書けます。

そのほか、プラグインマニフェストのフィールド（description、version、author、commands、hooks など）はここにも書けます。加えて、マーケットプレイス固有の source、category、tags、strict、relevance が使えます。

覚えておくと役に立つのは defaultEnabled です。既定は true で、導入した時点で有効になります。false にすると、導入はされるが利用者が明示的に有効化するまで無効のままになります。

導入されたプラグインは ~/.claude/plugins/cache の下にコピーされます。コピーなので、プラグインのディレクトリ外を ../shared-utils のような相対パスで参照できません。参照先はコピーされないためです。複数プラグインでファイルを共有したい場合はシンボリックリンクを使ってください。

GitHub で公開して配る

公開先として推奨されているのは GitHub です。手順は3つだけです。

マーケットプレイス用のリポジトリを作る
.claude-plugin/marketplace.json を置く
利用者に /plugin marketplace add owner/repo を実行してもらう

GitHub を推す理由は、バージョン管理、issue による報告受付、チームでの共同編集がそのまま使えるからです。

GitHub 以外の git ホスト

GitLab、Bitbucket、自前の git サーバーでも同じように使えます。この場合、利用者はリポジトリの完全な URL を渡します。

/plugin marketplace add https://gitlab.com/company/plugins.git

注意点として、URL にはスキームが必要です。gitlab.example.com/team/plugins のようにスキーム無しで書くと、Claude Code v2.1.196 以降は「不正な owner/repo 表記」として拒否し、https:// を付けるかローカルパスなら ./ を使うよう案内します。それより前のバージョンは GitHub のリポジトリパスと誤読し、clone の段階で not found になります。

非公開リポジトリで配る場合

非公開リポジトリからの導入にも対応していますが、利用者が自分で実行するコマンドと、裏で走る自動更新とで挙動が違う点に注意が要ります。ここが実運用でつまずきやすい箇所です。

/plugin marketplace add、/plugin install、/plugin update、/plugin marketplace update を利用者が実行するときは、既存の git 資格情報ヘルパーがそのまま使われます。gh auth login、macOS キーチェーン、git-credential-store による HTTPS 認証は、ターミナルで git を使うときと同じように機能します。SSH も、ホストが known_hosts にあり、鍵が ssh-agent に読み込まれていれば使えます。

一方、背景で走る自動更新は、既定では git pull の際に資格情報ヘルパーを無効にします。そのため、ヘルパーを設定していても HTTPS で非公開リポジトリを認証できません。SSH リモートはこの影響を受けず、ssh-agent の鍵で認証できます。背景の pull に失敗すると、Claude Code はマーケットプレイスを clone し直す動作に切り替わります。この再 clone では保存済みの資格情報が使われますが、大きなリポジトリではタイムアウトすることがあり、結果として自動更新が断続的に失敗します。

非公開マーケットプレイスの挙動を安定させるには、次の2つを設定します。

CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 を設定する。背景の pull が失敗しても既存の clone を保持し、削除して再 clone しなくなります。プラグインは最後に同期した状態のまま動き続け、手動の /plugin marketplace update は資格情報付きで pull できます。
git の資格情報ヘルパーを設定する。GitHub なら gh auth setup-git です。これで再 clone の際に対話なしで認証できます。

環境変数に GITHUB_TOKEN を置くだけでは、背景の認証は有効になりません。トークンが効くのは、設定済みの資格情報ヘルパー経由の場合だけです。たとえば gh CLI のヘルパーは GH_TOKEN と GITHUB_TOKEN を読みます。

背景の pull 自体を HTTPS で認証させたい場合は、git の URL 書き換えを設定します。書き換えはリモート URL にトークンを埋め込むため、資格情報ヘルパーが無効でも効きます。

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

この書き換えは必ずマーケットプレイスのリポジトリか組織のパスまで絞ってください。ホスト名だけを基準にすると、そのマシンからそのホストへの全ての fetch と push に適用され、自分のリポジトリへの push まで含めて通常の資格情報を上書きしてしまいます。またトークンは gitconfig に平文で残るので、対象リポジトリへの読み取り専用トークンを使ってください。

プロバイダごとにユーザー名部分が異なります。

プロバイダ	書き換え後の URL の形
GitHub	`https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins`
GitLab	`https://oauth2:YOUR_TOKEN@gitlab.com/acme-corp/plugins`
Bitbucket	`https://x-token-auth:YOUR_TOKEN@bitbucket.org/acme-corp/plugins`

チーム全員に自動で追加する

ここまでの手順では、利用者一人ひとりが /plugin marketplace add を実行する必要があります。チームで使うなら、リポジトリ側に設定を置いて自動で追加されるようにするほうが確実です。

.claude/settings.json に extraKnownMarketplaces を書きます。これでメンバーがそのプロジェクトフォルダを信頼した時点で、別途プロンプトを出さずにマーケットプレイスが追加されます。

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

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

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

ローカルの directory または file の取得先を相対パスで書いた場合、そのパスはリポジトリのメインのチェックアウトを基準に解決されます。git worktree から Claude Code を起動しても参照先はメインのチェックアウトのままなので、全ての worktree が同じマーケットプレイスの場所を共有します。なお、マーケットプレイスの状態はプロジェクト単位ではなく利用者ごとに1つ、~/.claude/plugins/known_marketplaces.json に保存されます。

コンテナや CI では事前に用意しておく

コンテナイメージや CI 環境では、実行時に clone せずに済むよう、ビルド時にプラグインのディレクトリを作り込めます。CLAUDE_CODE_PLUGIN_SEED_DIR にそのディレクトリを指定します。

シードディレクトリは ~/.claude/plugins と同じ構造です。

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

コピー作業を省きたい場合は、ビルド時に 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

そのうえで実行時の環境に CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed を設定します。挙動には次の特徴があります。

読み取り専用: シードディレクトリには書き込みません。読み取り専用のファイルシステムでは git pull が失敗するため、シード由来のマーケットプレイスは自動更新が無効になります。
シードが優先: シードで宣言されたマーケットプレイスは、起動のたびに利用者側の設定の同名エントリを上書きします。シードのプラグインを使いたくない場合は、マーケットプレイスを削除するのではなく /plugin disable を使ってください。
パスは実行時に解決: シードの JSON に書かれたパスを信用せず、実行時に $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ を探します。ビルド時と違う場所にマウントしても動きます。
変更操作は拒否される: シード管理のマーケットプレイスに対する /plugin marketplace remove や /plugin marketplace update は失敗し、管理者にシードイメージの更新を依頼するよう案内が出ます。

検証とCLIからの操作

公開する前に、手元で検証してください。マーケットプレイスのディレクトリから JSON の構文を確認します。

claude plugin validate .

Claude Code のセッション内からなら次の形です。

/plugin validate .

そのうえで、ローカルパスで実際に追加し、テスト用のプラグインを1つ導入して通しで動くことを確かめます。

/plugin marketplace add ./path/to/marketplace
/plugin install test-plugin@marketplace-name

CLI からの操作

対話セッションを開かずに操作したい場合のために、claude plugin marketplace というサブコマンドがあります。中身は対話セッションの /plugin marketplace と同じで、スクリプトや自動化から呼ぶためのものです。

claude plugin marketplace add <source> [options]

<source> には、GitHub の owner/repo 表記、git の URL、marketplace.json を直接返すリモート URL、ローカルのディレクトリパスが渡せます。ブランチやタグに固定したい場合は、GitHub 表記なら @ref を、git URL なら #ref を末尾に付けます。

オプション	説明	既定値
`--scope <scope>`	どこに宣言するか。`user`、`project`、`local` のいずれか	`user`
`--sparse <paths...>`	git の sparse-checkout で特定ディレクトリだけに絞る。モノレポで有用	—

実際の書き方は次のとおりです。

# GitHub の owner/repo 表記で追加する
claude plugin marketplace add acme-corp/claude-plugins

# ブランチやタグに固定する
claude plugin marketplace add acme-corp/claude-plugins@v2.0

# GitHub 以外の git URL から追加する
claude plugin marketplace add https://gitlab.example.com/team/plugins.git

# marketplace.json を直接返す URL から追加する
claude plugin marketplace add https://example.com/marketplace.json

# テスト用にローカルディレクトリから追加する
claude plugin marketplace add ./my-marketplace

# プロジェクトスコープで宣言し .claude/settings.json 経由でチームと共有する
claude plugin marketplace add acme-corp/claude-plugins --scope project

最後の --scope project は、前の節で手書きした extraKnownMarketplaces を、コマンドから書かせる形にあたります。設定ファイルを直接編集するか、コマンドで書かせるかの違いだけで、結果は同じです。

本記事は 2026年8月24日時点の Claude Code 公式ドキュメント（Create and distribute a plugin marketplace）に基づく非公式の日本語解説です。バージョンによって挙動が変わる項目には該当バージョンを併記しています。最新の仕様は公式ドキュメントで確認してください。