Claude Codeのプラグインとは？/pluginマーケットプレイスの使い方とplugin.json入門

Claude Codeのプラグインは、Skills・サブエージェント・Hooks・MCPサーバー・LSPサーバーを1つのディレクトリにまとめ、バージョン管理しながら配布するための仕組みです。本記事は、plugin.jsonの構造、配布スコープ、/pluginコマンドでの利用、claude-plugins-officialとclaude-communityの関係、公開時の注意点までを整理します。

結論：「自分用の.claude/」と「共有・配布」を分ける装置

プラグインを作る判断は次の2軸でほぼ決まります。

1. 共有するか：自分のプロジェクトだけで使うのか、チームや公開コミュニティで使うのか
2. バージョン管理するか：手元のコピペで運用するのか、リリース単位で配布したいのか

「Claude CodeのSkillsとは？SKILL.mdの書き方と使いどころ」で扱った.claude/配下のStandalone構成は、「自分のプロジェクトで素早く回す」用途に最適です。一方、プラグインはバンドル単位で配布でき、Skill名が/plugin-name:skill-nameという形で名前空間化されるため、複数プラグインの衝突を防ぎながら更新できます。

公式ドキュメントの推奨は明確で、まずStandalone構成で試し、共有したくなったらプラグインへ変換するという順序です。

プラグインの最小構成

プラグインはディレクトリ単位で管理し、.claude-plugin/plugin.jsonがエントリポイントです。最小構成は次のとおりです。

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── hello/
        └── SKILL.md

plugin.jsonの最小形は次のとおりです。

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

homepage・repository・licenseは任意ですが、配布時には埋めておくと便利です。

公式が強調しているよくある間違いとして、「commands/・agents/・skills/・hooks/を.claude-plugin/の中に入れてはいけない」と明記されています。.claude-plugin/に入るのはplugin.jsonだけで、それ以外はプラグインルートに配置します。

プラグインに同梱できる構成要素

プラグインルートに次のディレクトリ・ファイルを置くと、Claude Codeがそれぞれ読み込みます。

Skillsは「Claude CodeのSkillsとは？SKILL.mdの書き方と使いどころ」、サブエージェントは「Claude Codeのサブエージェントとは？使いどころと注意点」、Hooksは「Claude CodeのHooksで開発ワークフローを自動化する方法」、MCPは「Claude CodeとMCPサーバーの基本：できることと導入前の注意点」に整理してあります。プラグインはこれらをまとめて配布する「梱包箱」と捉えるのが正確です。

ローカル開発：--plugin-dirでの試運転

プラグインを開発するときは、インストールせずに--plugin-dirフラグで直接読み込ませる運用が推奨されています。

このフラグは.zipアーカイブも受け取れます（v2.1.128以降）。同名のインストール済みプラグインがあっても、--plugin-dirで渡したローカルコピーが優先されるため、上書きインストールせずに変更を試せます。

セッション中にプラグインを編集したら、/reload-pluginsで再読み込みできます。

URLでホストされた.zipを直接読みたい場合は--plugin-urlを使います（取得失敗・無効アーカイブはエラーで起動失敗）。CI成果物のテスト時などに便利ですが、信頼するアーカイブにのみ向けるよう公式が注意しています。

/pluginコマンドとマーケットプレイス

プラグインの公開・配布はマーケットプレイスの仕組みを通じて行います。マーケットプレイスは、複数のプラグインをまとめたカタログで、GitHubリポジトリやURLで配布できます。

代表的なコマンドは次の通りです（公式仕様に従い、コピペで使えるテンプレートとして提示）。

Anthropicが運営する公式マーケットプレイスは2つあります。

公式カタログとコミュニティカタログでは、掲載のための審査プロセスが異なります。コミュニティ提出はclaude.ai/settings/plugins/submitまたはplatform.claude.com/plugins/submitから行えます。承認後はSHA固定でカタログにピン留めされ、リポジトリへの新規コミットでCIがピンを自動更新します。

配布スコープと優先順位

プラグインはどこに置くかで「誰に対して有効か」が決まります。Skillsと同様の4スコープです。

「チームでClaude Codeを導入するときに最初に決めるルール」で扱った通り、.claude/settings.jsonはGit管理する前提で運用します。プロジェクトで使うプラグインは、enabledPluginsに宣言してリポジトリにコミットすると、クラウドセッション（「Claude Code on the webの使い方とローカルCLIとの違い」）でも自動で取得されます。

バージョン管理：versionを切るか、SHAに任せるか

プラグインのバージョン戦略は2通りあります。

• versionを明示する：plugin.jsonのversionをバンプしたときだけ、ユーザーがアップデートを受け取る
• versionを省略してSHAに任せる：git経由配布ならコミットSHAが版扱いになり、全コミットが新版になる

リリース単位の安定性を担保するなら前者、開発を素早く回したいなら後者、というのが目安です。公式ドキュメントのversion managementに詳細があります。

依存関係とプラグインの無効化

v2.1.143以降、プラグインの依存関係強制が導入されています。あるプラグインが別のプラグインに依存する場合、/disableは依存元が他プラグインに必要とされる限り拒否されます。これによりプラグイン同士の不整合な無効化を防げます。

/pluginマーケットプレイス画面では、ターン単位／呼び出し単位の予測コンテキストコストも表示されるため、Skillsやサブエージェントを多く含むプラグインを入れる前に、コンテキスト圧迫の度合いを見積もれます。コンテキスト設計全体は「Claude Codeに必要な情報だけ渡すコンテキスト設計」で扱っています。

Standalone→プラグイン移行の手順

既存の.claude/をプラグインに変換するときの基本ステップは次のとおりです。

1. my-plugin/.claude-plugin/を作り、plugin.jsonを置く
2. .claude/commands/をmy-plugin/commands/へ、.claude/agents/をmy-plugin/agents/へコピー
3. .claude/skills/をmy-plugin/skills/へコピー
4. .claude/settings.jsonのHooks設定をmy-plugin/hooks/hooks.jsonへ（同じ形式）
5. claude --plugin-dir ./my-pluginで動作確認

変換が終わったら、元の.claude/から重複ファイルを消すと混乱が減ります。プラグインバージョンが優先されるので、両方残すと意図しない上書きの原因になります。

セキュリティと運用の注意点

プラグインはSkills・Hooks・MCPなど強力な拡張をまとめて配布できる反面、インストール時点でローカルに広い権限を委ねることになります。公式が暗黙的に置いている前提は次の通りです。

• 信頼できる発行元のプラグインだけインストールする：公式・コミュニティカタログのいずれであっても、内容の確認は利用者の責任
• allowed-toolsを含むSkillsは中身を読む：Skills記事で触れた通り、Bash(*)のような広い許可を含むSkillはプラグインに同梱されると攻撃面になる
• MCPサーバーを同梱するプラグインは、.mcp.jsonの中身を確認する：取得先・認証情報・取得コンテンツ由来のプロンプトインジェクションを評価する（「Claude Codeを使うときのセキュリティチェックリスト」を参照）
• 依存関係を把握する：依存先プラグインの内容まで含めてレビューする
• マーケットプレイスの自動承認に頼らない：claude-plugins-communityはレビューを経るが、それは最低限のチェックであって完全な保証ではない

組織レベルでは、managed settingsで許可するプラグインを絞ったり、/plugin install自体を無効化したりできます。チーム導入時は「チームでClaude Codeを導入するときに最初に決めるルール」の7ルールの一部としてプラグインポリシーを決めると整理が早いです。

プラグイン設計チェックリスト

• plugin.jsonを.claude-plugin/内に、それ以外のディレクトリはプラグインルートに置いた
• nameは名前空間として機能するため、Skill名の前置詞として読みやすい命名にした
• descriptionはマーケットプレイス検索で見つけやすい言葉で書いた
• versionを明示するか、SHAに任せるかを決めた
• Skillsのallowed-toolsは最小権限で書いた
• MCPサーバーを同梱する場合は.mcp.jsonの取得先・スコープをレビューした
• --plugin-dirでローカル動作確認を済ませた
• 共有先（社内private／コミュニティ／公式）と配布スコープ（Project／Personal／Enterprise）を決めた
• チーム導入時はmanaged settingsとの整合性を確認した

次に読むおすすめ記事：

• 「Claude CodeのSkillsとは？SKILL.mdの書き方と使いどころ」：プラグインに同梱するSkillの作り方
• 「Claude Codeのサブエージェントとは？使いどころと注意点」：プラグインに含めるサブエージェント設計
• 「チームでClaude Codeを導入するときに最初に決めるルール」：プラグイン許可制を組織で運用する土台