Claude Codeのプラグインは、スキル・サブエージェント・フック・MCPサーバーをひとまとめにして、1コマンドで入れられるようにする仕組みです。個人で公式マーケットプレイスから入れるだけなら数分で終わりますが、チームへ配る段階で詰まる箇所がいくつもあります。この記事では2026年9月時点の公式ドキュメントとv2.1.282系の挙動をもとに、plugin.jsonを書いて自作プラグインを動かす手順、marketplace.jsonで社内マーケットプレイスを立てる手順、managed settingsで入手元を絞る設定までを、コピーして使えるコマンドとJSONで整理しました。
まとめ：プラグインにする条件と社内配布で最初に決める設定
プラグインにする価値が出るのは、同じスキルやフックを3つ以上のリポジトリ、または複数人で使い回すときです。1人・1案件なら、.claude/配下にファイルを置くだけで足ります。プラグインは有効になっている間、使わないセッションでもスキル名と説明文を毎ターン読み込ませるため、作れば得というものではありません。
チームへ配ると決めたら、先に3点を決めてください。マーケットプレイスをどのリポジトリに置くか。projectスコープで配るのか、managed settingsで全端末に強制するのか。自社マーケットプレイスの自動更新を有効にするか（既定は無効）。この3点が曖昧なまま始めると、「設定はコミットしたのに同僚の端末で動かない」「レビューした後にファイルが差し替わった」という事故が起きます。
Claude Codeプラグインの中身とv2.1.282時点で入る4種類の部品
最初に、プラグインが何を束ねるものなのかを揃えておきます。
plugin.jsonと4つのディレクトリで決まる最小構成と名前空間
公式のプラグイン概要は、プラグインを「Claude Codeが1単位としてインストールし読み込む、スキル・エージェント・フック・MCPサーバーなどのディレクトリ」と定義しています。目印は.claude-plugin/plugin.jsonというマニフェストで、必須はnameだけです。このnameがスキルの接頭辞になり、helloというスキルは/my-plugin:helloとして呼び出されます。2つのプラグインが同名のスキルを持っていても衝突しないのは、この名前空間があるためです。
| 置き場所 | 中身 |
|---|---|
| plugin.json（専用フォルダ内） | マニフェスト |
| skills/ | SKILL.mdを持つ1スキル1フォルダ |
| agents/ | サブエージェント定義 |
| hooks/hooks.json | フック設定 |
| .mcp.json | MCPサーバー定義 |
つまずきやすいのは置き場所です。.claude-plugin/の中に入れてよいのはplugin.jsonだけで、skillsフォルダをその中に置くと読み込まれません。commands/は旧形式なので、新しく作るならskills/に寄せてください。各部品そのものの書き方は、Claude Skillsとは？SKILL.mdの書き方とClaude Code Hooksの設定方法｜全33イベント一覧で個別に扱っています。
単体のスキルやフックで足りる場面とプラグイン化へ進む判断基準
スキルもフックもMCPサーバーも、プラグインにしなくても動きます。~/.claude/skills/に置いたスキルは、その端末のすべてのプロジェクトで使えます。公式ドキュメントがプラグインを勧めるのは、複数の部品を1単位で配りたいとき、複数プロジェクトへ入れたいとき、版を切って配布したいときの3つです。
見落とされがちなのがコストです。有効なプラグインは、Claudeが自発的に呼べるスキル・エージェント・コマンドの名前と説明を毎ターンのコンテキストに載せます。本文が読み込まれるのは使ったときだけですが、一覧の分は何もしないセッションでも使用量に数えられます。部品が1つしかなく、使う人も自分だけなら、プラグインにする理由はありません。
公式マーケットプレイスから入れる手順とスコープ別の書き込み先
自作の前に、入れる側の挙動を押さえておくと配布設計で迷いません。
セッション内とシェルで異なる導入コマンドの挙動と常駐トークンの測定
公式マーケットプレイスclaude-plugins-officialは、対話型のターミナルセッションを初めて起動したときに自動で登録されます。インストール手順のドキュメントによると、セッション内の/plugin installはすぐには入れず、詳細ペインを開いて中身とスコープを確認させる動きです。シェルからのclaude plugin installは確認なしで入り、既定はuserスコープです。
# 公式マーケットプレイスから入れる（未登録の新しい端末では1行目が要る）
claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install commit-commands@claude-plugins-official
# 入れた後に常駐トークンと部品の内訳を確認する
claude plugin details commit-commands詳細ペインには、公式マーケットプレイスのプラグインに限り「Context cost」として毎ターン分と呼び出し時の2つの推定トークン数が出ます。導入後はclaude plugin detailsのAlways-on行で、そのプラグインが毎セッションに足すトークン数を確認できる仕組みです。claude -pなどの非対話実行では/pluginは使えませんが、導入済みのプラグインは読み込まれます。
user・project・localの3スコープと同僚の端末に入らない仕様
スコープごとに、enabledPluginsを書き込むファイルが変わります。userは~/.claude/settings.json、projectはコミットする.claude/settings.json、localは.claude/settings.local.jsonです。同じプラグインが複数に書かれていれば、local、project、userの順で勝ちます。
チーム配布で最も多い誤解がprojectスコープです。.claude/settings.jsonをコミットしても、同僚の端末へプラグイン本体はダウンロードされません。公式ドキュメントは、各自が一度claude plugin install <name>@<marketplace> --scope projectを実行する必要があると明記しています。例外は、マーケットプレイスが相対パスで持っているプラグインで、リポジトリ側のextraKnownMarketplacesが適用されればそこから読み込まれます。ただしその適用も、同僚がフォルダのワークスペース信頼を承認した後です。
空のディレクトリから自作プラグインを作り手元の1セッションで動かす手順
ここからは作る側です。マーケットプレイスは後回しにし、手元のフォルダで動くところまで進めます。
plugin.jsonとSKILL.mdの作成と検証コマンドによる動作確認
プラグイン作成のドキュメントの手順を、そのまま実行できる形にまとめました。disable-model-invocation: trueは、Claudeが自発的にこのスキルを呼ばず、人が打ったときだけ動かす指定です。
mkdir -p my-first-plugin/.claude-plugin my-first-plugin/skills/hello
# my-first-plugin/.claude-plugin/plugin.json
{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": { "name": "Your Name" }
}
# my-first-plugin/skills/hello/SKILL.md
---
name: hello
description: Greet the user with a friendly message
disable-model-invocation: true
---
Greet the user warmly and ask how you can help them today.
# 検証して1セッションだけ読み込む
claude plugin validate ./my-first-plugin
claude --plugin-dir ./my-first-plugin検証が通ると最終行に✔ Validation passedが出ます。起動後に/my-first-plugin:helloと打てば動作確認は完了です。ファイルを直したら/reload-pluginsで読み直せます。--strictを付けると警告も失敗扱いになるため、CIで回すならこちらを使ってください。v2.1.157以降ならclaude plugin init my-toolでひな形を作る手もあります。
既存の.claude配下をプラグインへ移すときにフックが2回走る落とし穴
すでに.claude/skills/や.claude/agents/がある場合は、プラグインのルートへコピーするだけで移せます。フックは設定ファイルのhooksオブジェクトをhooks/hooks.jsonへ同じ形で移します。
# my-plugin/hooks/hooks.json（編集のたびにlintを走らせる例）
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
}
]
}
}注意点は、移した後も元のファイルが残っている間の挙動です。スキルとエージェントは接頭辞が付くので/deployと/my-plugin:deployが並ぶだけですが、フックには接頭辞が無く、設定ファイル側とプラグイン側の両方が発火します。lintや通知なら2回走るだけで済みますが、コミットやデプロイを叩くフックなら二重実行になります。動作確認が済んだら、元のhooksを必ず消してください。
marketplace.jsonで社内マーケットプレイスを作りGitHubで配る手順
数人に渡すだけならフォルダやzipで足ります。更新を配り続けるなら、マーケットプレイスを立てます。
marketplace.jsonの必須3項目と登録名・宣言名を揃える理由
マーケットプレイス作成のドキュメントによると、.claude-plugin/marketplace.jsonの必須項目はname、owner、pluginsの3つです。各プラグインのエントリはnameとsourceを持ちます。
# my-marketplace/.claude-plugin/marketplace.json
{
"name": "my-marketplace",
"description": "Plugins for my team",
"owner": { "name": "Your Name" },
"plugins": [
{
"name": "my-first-plugin",
"source": "./plugins/my-first-plugin",
"description": "A greeting plugin to learn the basics"
}
]
}
claude plugin validate ./my-marketplace
claude plugin marketplace add ./my-marketplace
claude plugin install my-first-plugin@my-marketplace失敗の大半は2種類です。1つは相対パスの起点で、sourceは.claude-plugin/の親、つまりマーケットプレイスのルートから書きます。..を含むと検証で弾かれ、存在しないフォルダを指すと検証は通るのにインストール時に出るのはSource path does not existというエラーです。もう1つは名前の食い違いで、エントリのnameとplugin.jsonのnameが違うと、後者で入れようとしたときにnot found in marketplaceと出ます。両者は常に揃えてください。
相対パス・github・git-subdirの3ソースを置き場所で選ぶ基準
エントリのsourceは、プラグインのファイルがどこにあるかで選びます。表のgit-subdir指定は、sourceにgit-subdirを指定し、urlとpathを記述する形です。
| ソース | 向く置き方 | 最小の書き方 |
|---|---|---|
| 相対パス | マーケットプレイス内 | “./plugins/名前” |
| github | プラグインごとに別リポジトリ | source: github, repo |
| git-subdir | モノレポの一部 | git-subdir指定＋url・path |
立ち上げは相対パス一択です。前節のとおり、projectスコープで配るときに各自のinstallが要らなくなるのは相対パスだけだからです。プラグインごとに開発チームや権限を分けたくなった段階で、githubソースへ切り出してください。ほかにurl、archive、npm、commandの4種類もあります。
プライベートリポジトリの認証条件とCIのビルド時に行うseed事前投入
プライベートリポジトリも同じmarketplace addで登録できます。Claude Codeは端末にある既存のgit認証情報を使い、パスワードは尋ねません。HTTPSならgh auth loginなどの認証ヘルパーが効き、SSHならホストがknown_hostsに登録済みでパスフレーズ無しで通る鍵が要ります。
CIやコンテナで毎回クローンさせたくないときは、ビルド時にseedを作ります。GitHub Actionsで別リポジトリのマーケットプレイスを読むなら、既定のワークフロートークンでは届かないため、読み取り権限のあるトークンをGH_TOKENに入れてgh auth setup-gitを実行してください。
# イメージのビルド時にseedへ入れる
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/your-marketplace
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install code-formatter@your-marketplace
# 実行時の環境変数（初回の問い合わせ前にインストール完了を待たせる）
CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed
CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1seedは読み取り専用で自動更新も止まります。seed内のプラグインは自動では有効にならないので、enabledPluginsに別途書く必要があります。
managed settingsでプラグインを統制する書き方と効かない範囲
十数人を超えたら、各自の善意に頼らずmanaged settingsで配ります。ユーザー側では上書きできません。
全端末へプラグインを強制配布するマーケットプレイス登録と有効化の設定
組織向けのプラグイン管理ドキュメントが示す基本形は、extraKnownMarketplacesでマーケットプレイスを登録し、enabledPluginsで入れるプラグインを指名する組み合わせです。下の例は、公式と自社の2つだけを許可し、--plugin-dirでの持ち込みも禁じる構成です。
{
"strictKnownMarketplaces": [
{ "source": "github", "repo": "anthropics/claude-plugins-official" },
{ "source": "github", "repo": "your-org/*" },
{ "source": "skills-dir" }
],
"extraKnownMarketplaces": {
"your-marketplace": {
"source": { "source": "github", "repo": "your-org/your-marketplace" },
"autoUpdate": true
}
},
"enabledPlugins": {
"code-formatter@your-marketplace": true
},
"disableSideloadFlags": true
}enabledPluginsをfalseにすると、そのプラグインはすべてのスコープで止まり、一覧からも消えます。許可済みマーケットプレイスの中から1本だけ禁じたいときの手段はこれです。配布の反映は、次にセッションを起動したときです。
許可リストで入手元を絞るときに起きるskills-dirの停止
strictKnownMarketplacesは入手元の許可リストで、空配列[]にすると公式マーケットプレイスまで含めて全部止まります。blockedMarketplacesは拒否リストで、許可リストより先に判定されます。どちらもマーケットプレイスの入手元を見るもので、--plugin-dirは対象外です。持ち込みを止めるにはdisableSideloadFlagsを併用します。
事故になりやすいのが、上の例にある{ "source": "skills-dir" }の1行です。許可リストを1つでも設定し、この行を書かないと、~/.claude/skills/などにplugin.json付きで置いた個人のプラグインが一斉に読み込まれなくなります。manifestを持たない素のSKILL.mdは影響を受けません。また、/pluginコマンド自体を隠すキーは存在せず、サーバー管理設定は組織の全員に同じ内容が届くため、部署ごとに変えたいならMDMなど端末側の管理設定を分けることになります。
受託開発の現場でプラグイン配布を採用するチームの条件と見送る規模
ここからは判断です。仕組みが揃っていても、入れて得をする体制は限られます。
3リポジトリ以上で同じ規約を回すチームで採用する基準と見送る規模
採用してよいのは、同じレビュー観点・同じlintフック・同じ社内ツールのMCP接続を、3つ以上のリポジトリで回している場合です。この規模になると、各リポジトリの.claude/を手で揃える手間と、どれが古いか分からない状態のほうが高く付きます。PRレビューを束ねた実在のプラグイン例はpr-review-toolkitとは｜Claude Codeプラグインの導入とreview-prの使い方で確認できます。
見送るのは、1人か2人で1案件を回している段階です。この規模でマーケットプレイスまで立てると、plugin.jsonとmarketplace.jsonの版管理、名前の揃え、キャッシュの更新待ちという運用が増えるだけで、戻りがありません。.claude/配下に置いてリポジトリごとコミットし、規約が3リポジトリに広がった時点でプラグインへ移してください。移行手順は前述のとおりコピー中心で済みます。
フックとMCPがサンドボックス外で動く前提での審査と自動更新
プラグインのセキュリティ文書は冒頭で、インストールしたプラグインはユーザー権限で任意のコードを実行できると明言しています。フックとMCPサーバーはサンドボックスの外で動き、権限ルールが効くのはClaudeのツール呼び出しだけです。導入前の審査では、hooks/hooks.jsonが何を実行するか、.mcp.jsonの接続先、bin/配下のファイルの3点を必ず読んでください。
自動更新は、公式名のマーケットプレイスでは一部を除き既定で有効、自社を含むその他では既定で無効です。有効にすると、審査したファイルが裏で差し替わります。社内マーケットプレイスは自動更新を有効にしてよいですが、外部の第三者マーケットプレイスは無効のまま、コミットやタグで固定して入れる運用を勧めます。誰が何を入れたかは、OpenTelemetryのclaude_code.plugin_installedとclaude_code.plugin_loadedで追えます（設定はClaude CodeのOpenTelemetry設定を参照）。規約とツール接続を含めたAIコーディングの開発体制づくりは、生成AI開発・AI受託開発でご相談いただけます。
よくある質問
プラグインの導入と配布で問い合わせの多い5点を、公式ドキュメントの記載に沿って答えます。
Claude CodeのプラグインとClaude Marketplaceは同じものですか？
両者は名前が似ていますが、指している対象が異なります。/plugin marketplace addで登録するマーケットプレイスは、プラグインの一覧と取得先を書いたmarketplace.jsonを持つリポジトリやフォルダです。一方のClaude Marketplaceはclaude.com上のWebサイトで、プラグインやコネクタ、パートナー製品を探す場所です。企業購買の仕組みとしての側面はClaude Marketplaceの全体像で扱っています。
入れたプラグインはどのコマンドで無効化や削除ができますか？
セッション内なら/pluginのInstalledタブで、Spaceキーで有効と無効を切り替えられます。シェルからはclaude plugin disable、claude plugin enable、claude plugin uninstallを使い、--scopeで対象を指定します。アンインストール後もキャッシュのファイルは14日間ディスクに残るため、すぐに消したい場合は~/.claude/plugins/cache/配下のフォルダを手で削除してください。
プラグインを入れると使用量やコンテキストは増えますか？
増えます。有効なプラグインは、Claudeが自発的に呼べるスキルやエージェントの名前と説明を毎ターンのコンテキストに載せるため、使わないセッションでも使用量に数えられる仕組みです。公式マーケットプレイスのプラグインは導入前にContext costの推定が見られ、導入後はclaude plugin detailsのAlways-on行で確認できます。Installedタブには最近使っていないプラグインの一覧も出ます。
クラウドのセッションやclaude.ai/codeでもプラグインは使えますか？
手元の設定は引き継がれません。ブラウザのclaude.ai/codeを含むクラウドセッションは、自分の端末で入れたプラグインも、リポジトリの.claude/settings.jsonが有効にしたプラグインも読み込みません。組織として配りたい場合は、claude.aiの管理コンソールから届くサーバー管理設定を使います。ターミナル・デスクトップアプリのローカルセッション・VS Code拡張は同じ設定ファイルを読むため、userスコープで入れれば3つで共通になります。
おすすめのプラグインはどこで探せばよいですか？
まずは/pluginのDiscoverタブで公式マーケットプレイスの一覧を見るのが確実です。中身はGitHubのclaude-plugins-officialで公開されており、Anthropic自身の作例はclaude-codeリポジトリのpluginsフォルダにまとまっています。用途別の選び方はClaude Codeのおすすめ拡張機能6つを役割別に整理で紹介しています。
関連記事
- Claude Codeとは？できること・使い方・料金とコード解析の実力：Claude Code本体の機能と料金です
- Claude Codeの使い方｜導入から権限とCLAUDE.md設定まで実務手順：プラグイン以前の導入と権限設定です
- Claude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方：プラグインに入れるスキルの書き方です
- Claude Code Hooksの設定方法｜全33イベント一覧とsettings.jsonの書き方：hooks.jsonに書くイベントの一覧です
- MCPとは？AIと外部ツールをつなぐ標準規格とMCPサーバーの仕組み・作り方を解説：.mcp.jsonで束ねるMCPの規格です
