Claude Code のプラグイン：マーケットプレイスの追加、チームへの配布、plugin.json

Claude Code のプラグインは、スキルやサブエージェント、フック、MCP サーバーを1つの単位として配る仕組みだ。マーケットプレイスの追加からインストール、有効・無効の切り替えと更新、チームへの配布、導入前の安全確認、plugin.json を書く最小プラグインの作り方までを公式ドキュメントに沿って整理する。

プラグインは何を束ねるか

公式ドキュメントの定義では、プラグインはスキル、エージェント、フック、MCP サーバーなどを収めたディレクトリで、Claude Code はそれを1つの単位としてインストールし読み込む。名前やバージョンは `.claude-plugin/plugin.json` というマニフェストに書く。標準レイアウトには LSP サーバーや出力スタイル、実行ファイル置き場の `bin/` も含まれる。

これらの構成要素は、プラグインにしなくても単体で動く。公式がプラグインを勧めるのは、複数をまとめてチームメイトに渡したい、いくつものプロジェクトに入れたい、バージョンを付けて配りたい場面だ。まとめるとスキル名にプラグイン名の接頭辞が付き、`my-plugin` の `review` スキルは `/my-plugin:review` で実行する。別のプラグインと同名のスキルがあっても衝突しない。

ただし、有効なプラグインは使っていないセッションにも加わる。Claude が自分で呼び出せるスキルやエージェントは、名前と説明が毎ターンのコンテキストに入り、トークン使用量に数えられる。MCP サーバーはセッションと並行して動き、フックはイベントのたびに発火する。入れっぱなしにする前に、この常時コストは意識しておきたい。

マーケットプレイスを追加してインストールする流れ

マーケットプレイスは `.claude-plugin/marketplace.json` を持つリポジトリやディレクトリで、プラグインの取得先を並べたカタログにあたる。Anthropic の公式マーケットプレイス `claude-plugins-official` は、対話型のターミナルセッションを初めて起動したときに自動で追加される（管理ポリシーで止められていなければ）。それ以外は、Anthropic のコミュニティ版やデモ版も含めて自動では追加されない。

セッション内では、プラグイン名とマーケットプレイス名を `@` でつないで指定する。

/plugin install commit-commands@claude-plugins-official

このコマンドはその場ではインストールせず、`/plugin` パネルの詳細画面を開く。Will install 欄に追加されるコマンド、エージェント、スキル、フック、MCP・LSP サーバーが並び、公式マーケットプレイスのものならトークン見積もり（Context cost）も出る。スコープを選ぶとインストールが走る。`Run /reload-plugins to activate.` と出ても再読み込みは自動で行われ、プロンプトキャッシュを無効にする場合だけ警告して保留される。

公式以外のプラグインは、先に `/plugin marketplace add` でマーケットプレイスを登録する。引数には GitHub の `owner/repo`、任意ホストの git URL、ローカルのパス、ホストされた `marketplace.json` の URL を渡せ、git 系は `#ref` でブランチやタグを固定できる。つまずきやすいのは URL の書き方だ。

```text # NG: https:// が無いと GitHub の owner/repo 省略形と解釈され、拒否される /plugin marketplace add gitlab.example.com/your-group/your-marketplace.git

# OK: https:// を付ける。ローカルなら ./ か ../ で始める /plugin marketplace add https://gitlab.example.com/your-group/your-marketplace.git#v1.0.0 /plugin marketplace add ./my-marketplace ```

非公開リポジトリも同じコマンドで追加できるが、Claude Code は手元の git 認証情報で clone し、入力を求めない。一度も認証していないホストは問い合わせずに失敗する。セッションを開かずに入れるなら、シェルの `claude plugin install` を使う（既定は user スコープ）。

インストールのスコープと有効・無効・更新

スコープは、誰に対して有効にし、どの設定ファイルに記録するかを決める。user スコープは `~/.claude/settings.json`、project スコープはコミット対象の `.claude/settings.json`、local スコープは `.claude/settings.local.json` の `enabledPlugins` に書かれる。複数のスコープで設定されていれば local、project、user の順に優先される。ターミナル、デスクトップアプリのローカルセッション、VS Code 拡張は同じ設定ファイルを読むが、claude.ai/code を含むクラウドセッションはローカル設定のプラグインを読み込まない。

入れた後の操作は `/plugin` の Installed タブに集まっており、Space で有効・無効を切り替え、Enter で開く詳細から Update now や Uninstall を選ぶ。シェルからも同じ設定を操作できる。

claude plugin disable formatter@your-org
claude plugin enable formatter@your-org
claude plugin update formatter@your-org

更新は、取得元のマーケットプレイスで自動更新がオンかどうかで分かれる。2026 年 9 月時点の既定では、`claude-plugins-official` など公式名のマーケットプレイス（`knowledge-work-plugins` と `first-party-plugins` を除く）と claude.ai から追加したものがオン、コミュニティ版・サードパーティ・ローカル開発用はオフだ。切り替えは Marketplaces タブで行う。更新後も実行中のセッションは読み込み済みの版を使い続け、新しい版は次のセッションか `/reload-plugins` で反映される。なお、マーケットプレイスを削除すると、そこから入れたプラグインもすべてアンインストールされる。

チームで同じプラグインを使わせる

リポジトリ単位で揃える入口は project スコープだ。ただ、`.claude/settings.json` にエントリをコミットしても有効になるだけで、各自のマシンへのダウンロードは行われない。共同作業者はそれぞれ一度 `claude plugin install <name>@<marketplace> --scope project` を実行する。

マーケットプレイスの登録ごと共有するには、`extraKnownMarketplaces` と `enabledPlugins` の2つのキーを使う。次の JSON は公式ドキュメントが管理設定の例として示すもので、設定リファレンス上はどちらのキーもどの設定ファイルにも書ける（`autoUpdate` は任意）。

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true,
    "deploy-helper@your-marketplace": true
  }
}

リポジトリの `.claude/settings.json` に置いた `extraKnownMarketplaces` は、参加者がそのフォルダを信頼して初めて適用され、未信頼のフォルダではメッセージもなく無視される。マーケットプレイス内の相対パスで列挙されたプラグインはそのコピーから読み込まれるが、外部リポジトリを取得元とするプラグインは設定だけでは入らず、各自のインストールが要る。組織全体に配るなら同じキーを管理設定に置く。管理設定で有効化されたものは、利用者が自分のスコープで無効にしても読み込まれ続ける。

逆に、プロジェクトが有効にしたプラグインを個人だけ外したいこともあるだろう。Uninstall を選ぶと確認が入り、y なら自分の `.claude/settings.local.json` に false を書き、u なら共有の `.claude/settings.json` から削除する。

信頼と安全の注意

公式のセキュリティページは、インストールしたプラグインはユーザー権限で任意のコードを実行できる、と明記している。フックはシェルコマンドとして動き、stdio 型の MCP サーバーはローカルのプロセスになる。有効なプラグインの `bin/` は Bash ツールの PATH に加わり、スキルやエージェントは指示として Claude のコンテキストに入る。