Claude Codeプラグイン(Plugins)完全ガイド — /pluginの使い方・マーケットプレイス・自作と配布

プラグインとは何か

Claude Codeに独自のスキルやサブエージェント、フック、MCPサーバーを足していくと、.claude/ 配下の設定ファイルが増えていきます。これらを1つのディレクトリにまとめ、配布・バージョン管理・チーム共有まで可能にするのがプラグインです。マーケットプレイスからワンコマンドで導入する使い方から、.claude-plugin/plugin.json を書いて自作・配布する手順まで、2026年6月時点の仕様に沿って順に見ていきます。

Claude Code全体の機能や立ち位置から確認したい場合は、Claude Code完全ガイドを起点にすると全体像がつかみやすくなります。

プラグインは、スキル・サブエージェント・フック・MCPサーバー・LSPサーバー・モニターなどを1つにまとめた「自己完結型のディレクトリ」です。Claude Codeの機能を拡張し、それを他者と共有したり、バージョン管理したりできるようにする仕組みと位置づけられています。

個別に設定していた拡張要素を「まとめて配る単位」にしたもの、と捉えると分かりやすくなります。たとえばコミット支援のスキルとそれを補助するフックを別々に共有すると受け取り側の組み込みが煩雑ですが、プラグインなら1つのインストールで両方が揃います。

各プラグインは任意で .claude-plugin/plugin.json というマニフェストを持ちます。配布は marketplace.json というカタログを介して、gitリポジトリやローカルパスから行います。ここで重要な注意点として、プラグイン本体はnpmパッケージそのものではありません(後述しますが、npmは配布元の選択肢の1つに過ぎません)。インストールすると、プラグインは ~/.claude/plugins/cache にバージョン別でコピーされ、そこから読み込まれて使われます。

構成要素ごとの役割は、それぞれ単独の機能としても解説しています。あわせて参照すると、プラグインが「何を束ねているか」が具体的になります。

• スキルの仕組みはClaude Codeスキル完全ガイド
• サブエージェントはClaude Codeサブエージェント実践ガイド
• フックはClaude Codeフック設定ガイド
• MCPサーバーはClaude CodeでMCPサーバーを使う

/pluginで何ができるか(コマンド一覧)

プラグインの操作は、対話セッション中のスラッシュコマンドと、CIやスクリプト向けの非対話CLI(claude plugin ...)の2系統があります。まず日常的に使うスラッシュコマンドをまとめます。

CIやスクリプトなど、対話セッションの外から操作したいときは claude plugin サブコマンドを使います(install / uninstall / enable / disable / update / list / initなどのサブコマンドがあります)。

claude plugin install formatter@my-marketplace --scope project
claude plugin validate .          # /plugin validate . と同等
claude plugin init                # ローカル開発用プラグインの雛形を生成
claude --plugin-dir ./my-plugin   # 開発中プラグインを一時ロード(.zip 可)

--scope には user(個人グローバル) / project(プロジェクト固有) / local を指定できます。スコープの使い分けは後半の早見表でまとめます。

マーケットプレイスの仕組みと追加方法

マーケットプレイスは「カタログを追加(add)してから、個別プラグインをinstallする」という2段階の構造です。アプリストアを端末に追加してから、各アプリを個別に入れる関係に近いと考えると整理しやすくなります。

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

ここで押さえておきたいのは、/plugin marketplace add が行うのは「カタログ(marketplace.json)を取得して登録する」ことだけで、この時点ではプラグインは1つもインストールされない、という点です。実際の導入は /plugin install <name>@<marketplace> で行います。

マーケットプレイスのカタログは、リポジトリ直下の .claude-plugin/marketplace.json に置かれます。配布元として指定できるのはGitHubの owner/repo、任意のgit URL(GitLab / Bitbucket / 自前ホスト)、ローカルパス、marketplace.json への直接URLです。

なお、プラグインのインストールはユーザー権限での任意コード実行を伴います。ドキュメントでも信頼できる提供元のみを導入するよう案内されています。出所の確認は最初の判断軸にしておくと安全です。

代表的なマーケットプレイスとプラグイン

ここで挙げるのは、一次情報(公式ドキュメント・GitHubリポジトリの README / marketplace.json)で実在を確認できたものだけです。マーケットプレイスとプラグインは更新が速いため、最新の収録状況は /plugin のマネージャや各リポジトリで確認してください。

マーケットプレイス

anthropics/claude-plugins-official は起動時に自動で利用可能なため、原則として手動addは不要です。もし候補に出てこないときだけ /plugin marketplace add anthropics/claude-plugins-official を実行します。

公式マーケットプレイスのプラグイン例

公式系のマーケットプレイスからは、次のようなプラグインを導入できます(例: /plugin install github@claude-plugins-official)。下表は代表例の抜粋です。feature-dev / code-review / plugin-dev のように公式デモ(@claude-code-plugins)由来のものも含むため、名前と収録先(@claude-plugins-official か @claude-code-plugins か)は /plugin のDiscoverで確認してください。

security-guidance は、各編集ごとのパターン文字列マッチ(モデルを使わない軽量チェック)、ターン終了時の差分レビュー、Claudeのコミット/プッシュ時のエージェントレビューという複数の層で動作します。固定の観点数があるわけではなく、動的コード実行(eval / os.system / child_process.exec 等)、安全でないデシリアライズ、DOMインジェクション(dangerouslySetInnerHTML / .innerHTML 等)、ワークフローファイルの編集といったカテゴリを対象に検知します。

typescript-lsp 系のLSPプラグインは、対応する言語サーバーのバイナリを別途インストールしておく必要がある点に注意してください(導入しただけでは動きません)。なおLSPは言語ごとに <言語>-lsp 形式の別プラグイン(typescript-lsp / Pythonは pyright-lsp / rust-analyzer-lsp など)として提供されています。対応言語は更新されるため、最新は /plugin のDiscoverで確認してください。

コミュニティや他マーケットプレイスのプラグインは、先にカタログをaddしてからinstallします。

/plugin marketplace add anthropics/claude-plugins-community
/plugin install <name>@claude-community

ドメイン特化エージェント群をまとめた wshobson/agents の場合も同じ流れです。

/plugin marketplace add wshobson/agents
/plugin install python-development

プラグインの構造(.claude-plugin/plugin.json)

ここがスタンドアロンの .claude/ 設定とプラグインを取り違えやすいポイントです。プラグインでは、コンポーネント(skills/ や agents/ など)はプラグインルート直下に置きます。.claude-plugin/ ディレクトリの中に入れてよいのは plugin.json だけで、ここにスキルやコマンドを入れてしまうと読み込まれません。ドキュメントでも「よくある間違い」として挙げられています。

my-plugin/
├── .claude-plugin/
│   └── plugin.json        ← マニフェスト(ここに入れるのはこれだけ)
├── skills/                ← <name>/SKILL.md 形式のスキル
│   └── my-skill/SKILL.md
├── agents/                ← サブエージェント定義(.md)
├── commands/              ← フラットな .md スキル(旧式。新規は skills/ 推奨)
├── hooks/
│   └── hooks.json         ← ライフサイクルイベントハンドラ
├── .mcp.json              ← MCP サーバー定義
├── .lsp.json              ← LSP サーバー設定
└── bin/                   ← 有効時に Bash の PATH へ追加される実行ファイル

plugin.json マニフェスト自体は任意です。省略するとコンポーネントは既定パスから自動検出され、プラグイン名はディレクトリ名から導出されます。置く場合の必須フィールドは name(kebab-case、名前空間に使われる)のみです。

{
  "name": "my-plugin",
  "displayName": "My Plugin",
  "version": "0.1.0",
  "description": "コミットとレビューを補助するスキル群",
  "author": { "name": "Your Name", "email": "you@example.com" },
  "license": "MIT",
  "keywords": ["git", "review"]
}

version を設定すると、更新はこの値をbumpしたときのみ反映されます。省略した場合はgit commit SHAがバージョンとして扱われます。なお、requires や permissions というキーはマニフェストのスキーマには存在しません。依存関係は dependencies フィールド、デフォルトの有効状態は defaultEnabled、ユーザー入力値は userConfig で扱います。認識されないトップレベルのフィールドは警告のみで無視される(--strict ではエラー化)ため、plugin.json を package.json などと兼用することも可能です。

プラグイン内で使えるパス変数も覚えておくと便利です。

自作の最小手順

最小構成なら、雛形生成からローカルテスト、ホットリロードまでを数ステップで回せます。

# 1. 雛形を生成する
claude plugin init
 
# 2. skills/<name>/SKILL.md を編集して機能を書く
#    (必要に応じて agents/・hooks/hooks.json・.mcp.json を追加)
 
# 3. インストールせずに一時ロードして試す
claude --plugin-dir ./my-plugin
 
# 4. 変更したら、セッションを切らずに反映する
/reload-plugins
 
# 5. 配布前にスキーマを検証する
claude plugin validate .

スキルは skills/<name>/SKILL.md の形式で置くと、モデルが自動起動するほか、/plugin-name:skill という名前空間付きコマンドとしても呼び出せます。commands/ に置くフラットな .md は旧式の扱いで、新規作成では skills/ が推奨されています。

サブエージェントを同梱する場合、hooks / mcpServers / permissionMode はセキュリティ上の理由でプラグイン同梱エージェントでは非対応です。これらはプラグインの hooks/hooks.json や .mcp.json 側で定義します。

スキルやサブエージェントそのものの書き方は、スキル完全ガイドやサブエージェント実践ガイドを組み合わせると、プラグイン化する前段の中身づくりが進めやすくなります。

配布したいときは、自前の marketplace.json をgitでホストし、利用者に /plugin marketplace add <owner/repo> してもらう形が基本です。marketplace.json の各pluginエントリでは name と source が必須で、source には相対パス(./ 始まり)のほか、{source:"github", repo, ref?, sha?} / {source:"url", url} / {source:"git-subdir", url, path} / {source:"npm", package, version?, registry?} のオブジェクト型を指定できます。

npmがsource型の1つとして存在するため「プラグイン = npmパッケージ」「npm publish で公開」と誤解されがちですが、これは誤りです。公開の標準フローは npm publish ではなく、(a)自前 marketplace.json をgitでホストする、(b)コミュニティマーケットプレイスへフォーム提出して審査・スクリーニングを通す、(c)公式マーケットプレイス(Anthropicの裁量でキュレーション、応募経路なし)のいずれかです。提出フォームの対象はあくまで「コミュニティ」マーケットプレイスで、claude-plugins-officialには応募フォームがありません。

使い分け早見表

スコープと配布方法は、目的に応じて次のように整理できます。

設定全般の格納場所についてはsettings.json完全ガイド、コマンド体系についてはスラッシュコマンドガイドもあわせて参照できます。

よくあるつまずきと回避策

直接URLで marketplace.json をaddした場合、相対パスsourceは解決できません。この場合は github / npm / git URLのsource型を使う必要があります。

FAQ

プラグインとMCPの違いは何ですか

MCPサーバーは外部ツールやデータソースへの接続そのものを指します。プラグインは、そのMCPサーバー定義(.mcp.json)に加えて、スキル・エージェント・フック・LSPなどをまとめて1パッケージにし、配布・バージョン管理できるようにした上位の単位です。MCP単体の使い方はMCP実践ガイドで扱っています。

スキルとプラグインの関係は何ですか

スキルはプラグインに含められるコンポーネントの1つです。スキル単体でも .claude/ 配下で使えますが、関連するフックやエージェントとまとめて配布したいときにプラグイン化する、という関係になります。

無料プランでも使えますか

プラグインの利用可否は、利用しているプラン構成とClaude Code本体のバージョンに依存します。料金やプランの対応範囲は変更されることがあるため、最新の対応状況は、自分の環境で /plugin を開けるかどうかを確かめるか、Anthropicの料金・プランの記載を参照するのが確実です。

チーム全員に配布できますか

プロジェクトスコープ(--scope project)でリポジトリにコミットしておくと、チームで共有しやすくなります。自社限定で配る場合は、marketplace.json をprivateリポジトリでホストして各自にaddしてもらう形が基本です。

アンインストールと無効化はどう違いますか

/plugin disable <name>@<marketplace> は削除せず一時的に無効化するだけで、/plugin enable で戻せます。完全に消したいときは /plugin uninstall を使います。

まとめ

プラグインは、スキル・エージェント・フック・MCP・LSPなどを1つのディレクトリに束ね、配布とバージョン管理を可能にする仕組みです。日常的には /plugin を開いてマーケットプレイスから入れ、/plugin-name:skill で呼び出すのが最短ルートになります。自作する場合は claude plugin init で雛形を作り、.claude-plugin/plugin.json を置き、コンポーネントはプラグインルート直下に配置します。配布は marketplace.json をgitでホストする形が基本で、npmはsource型の1つに過ぎない点だけ押さえておけば、誤解なく扱えます。

次の一歩として、束ねる中身そのものを磨くならスキル・サブエージェント・フックの各ガイドが、全体像の確認にはClaude Code完全ガイドが手がかりになります。