Claude Code プラグイン完全ガイド2026——スキル・フック・MCPを1パッケージにする「プラグイン」の正体と実践的な作り方
Claude Codeのプラグイン機能を徹底解説。スタンドアロンスキルとプラグインの違い、plugin.jsonの書き方、公式マーケットプレイスの使い方、チームへの展開方法まで。2026年公式ドキュメント準拠のエンジニア向けガイド。
エンジニアのゆとです。
「Claude Codeのプラグインって、MCPと何が違うの？」「スキルを作ったけど、プラグインにしないといけない？」という疑問をよく見かける。この記事はその答えを出すのが目的だ。
結論から言うと、**プラグインはスキル・フック・MCP・エージェントを1つのインストール可能なユニットにまとめる「パッケージ形式」**で、スキルやMCPそのものとは別の概念だ。個人プロジェクトで使うだけなら.claude/のスタンドアロン設定で十分で、プラグイン形式にする必要はない。
チームで共有したい、マーケットプレイスで配布したい、複数プロジェクトで使い回したい——そういうときに「プラグイン化」という選択肢が出てくる。
プラグインとスタンドアロン設定はどう違うか
Claude Codeには「カスタムスキルを追加する方法」が2つある。
| 項目 | スタンドアロン（.claude/） | プラグイン |
|---|---|---|
| スキル名 | /hello | /my-plugin:hello |
| 設置場所 | .claude/skills/ | {plugin-dir}/skills/ |
| 共有方法 | 手動コピー | /plugin install or マーケットプレイス |
| バージョン管理 | なし | plugin.json で管理 |
| 複数プロジェクト | 毎回コピーが必要 | 一度インストールすれば全体で使える |
| 向いているケース | 個人ワークフロー・実験・1プロジェクト専用 | チーム配布・複数プロジェクト・コミュニティ公開 |
スタンドアロンのスキルはスキル名に名前空間がない（/helloのように短い）。プラグイン内のスキルは/my-plugin:helloのように名前空間付きになる。これは複数プラグインが同名スキルを持ったときの衝突を防ぐ仕組みだ。
個人で使うだけなら.claude/にそのまま書けばいい。「チームのリポジトリにセットアップドキュメントとして含めたい」「バージョンを管理して更新を配信したい」という要件が出てきたときにプラグイン化を検討する、という流れが現実的だ。
プラグインの内部構造
プラグインの最小構成はこれだけ：
my-plugin/
└── .claude-plugin/
└── plugin.jsonplugin.json さえあればプラグインとして認識される。実際の機能（スキル・フック・MCPなど）は別ディレクトリに置く：
my-plugin/
├── .claude-plugin/
│ └── plugin.json ← マニフェスト（唯一 .claude-plugin/ に入る）
├── skills/ ← カスタムスキル
│ └── code-review/
│ └── SKILL.md
├── agents/ ← カスタムエージェント
├── hooks/ ← フック設定
│ └── hooks.json
├── .mcp.json ← MCPサーバー設定
├── .lsp.json ← LSPサーバー設定（言語インテリジェンス）
├── monitors/ ← バックグラウンドモニター
│ └── monitors.json
├── bin/ ← プラグイン有効中に PATH に追加される実行可能ファイル
└── settings.json ← プラグイン有効時に適用されるデフォルト設定よくある間違い：skills/ や hooks/ を .claude-plugin/ の中に入れてしまうこと。.claude-plugin/ には plugin.json だけが入る。スキル・フック・エージェントはプラグインのルートレベルに置く。
plugin.json の書き方
{
"name": "my-plugin",
"description": "コードレビューと品質チェックを自動化するプラグイン",
"version": "1.0.0",
"author": {
"name": "yuto"
},
"homepage": "https://github.com/yuto/my-plugin",
"repository": "https://github.com/yuto/my-plugin",
"license": "MIT"
}name はスキルの名前空間になる（/my-plugin:code-review のように）。version を省略してGit配布する場合、コミットSHAがバージョンとして使われ、プッシュするたびに「新バージョン」として扱われる。明示的にバージョン管理したい場合は version を書いておく。
公式マーケットプレイスを使う
利用可能なマーケットプレイス
Claude Codeには2つの公開マーケットプレイスがある：
claude-plugins-official：Anthropicが管理するキュレーションプラグイン集。Claude Codeをインストールすれば自動で利用可能になる。GitHub統合・Jira/Confluence・Figma・TypeScript/Python/Rust LSPなど2026年5月時点で55+のプラグインが含まれる。
claude-community：サードパーティが提出してレビュー後に登録されるコミュニティプール。デフォルトでは利用不可で、追加が必要：
/plugin marketplace add anthropics/claude-plugins-community追加後は @claude-community としてインストールできる。
プラグインのインストール
# UIから
/plugin
# CLIから
claude plugin install github-integration # 公式マーケットプレイスから
claude plugin install @claude-community/my-plugin # コミュニティから
# GitHub URLから直接
claude plugin install github.com/username/repoスコープを指定してインストールできる：
claude plugin install github-integration --scope user # 全プロジェクトで使う
claude plugin install github-integration --scope project # このプロジェクトのみ--scope project でインストールすると .claude/plugins.json にリストされ、チームメンバーも同じプラグインが使えるようになる。
マーケットプレイスの信頼性を評価する
Official（最も安全）：Anthropicが審査・管理。CI自動チェック＋人手レビュー。更新もAnthropicが制御。
Community（要確認）：レビューはあるが、コードの内容まで完全に担保されてはいない。インストール前にリポジトリのソースを確認する習慣をつける。
プライベート（最も制御可能）：チーム内のリポジトリをマーケットプレイスとして使う方式。社内ポリシーに合わせて管理できる。外部マーケットプレイスに依存しない。
URLダイレクト（注意が必要）：claude plugin install github.com/unknown/plugin のような直接インストールはコードの確認なしに実行されるリスクがある。信頼できるソースからのみ使う。
MCPと同様に、プラグインもシェルコマンドを実行できる（hooks経由）。提供元が不明なプラグインをインストールするのはnpm installで信頼できないパッケージを入れるのと同じリスクがある。
実際にプラグインを1本作る
コードレビュープラグインを例に、ゼロから作る流れを示す。
最速の方法：claude plugin init
claude plugin init code-review-pluginこれだけで ~/.claude/skills/code-review-plugin/ に plugin.json と雛形 SKILL.md が生成される。次のセッションから自動的に読み込まれる。
手動で作る場合
1. ディレクトリ構造を作る：
mkdir -p code-review-plugin/.claude-plugin
mkdir -p code-review-plugin/skills/review
mkdir -p code-review-plugin/hooks2. マニフェストを書く：
# code-review-plugin/.claude-plugin/plugin.json
{
"name": "code-review-plugin",
"description": "PRレビューのポイントをチェックするプラグイン",
"version": "1.0.0"
}3. スキルを書く：
# code-review-plugin/skills/review/SKILL.md
---
description: コードをレビューし、品質・セキュリティ・テストカバレッジの観点でフィードバックを出す。PRレビューやコード品質チェックに使う。
---
コードレビューの際は以下の観点でチェックしてください：
1. **コードの構成と可読性**
- 変数名・関数名が意図を表しているか
- 1関数が1つの責務を持っているか
2. **エラーハンドリング**
- 例外処理が漏れていないか
- エラーメッセージが意味のある内容か
3. **セキュリティ**
- SQLインジェクション・XSS等の脆弱性がないか
- 認証・認可の漏れがないか
4. **テストカバレッジ**
- 境界値・異常系のテストがあるか
- モックが適切に使われているか
問題点を見つけた場合は、ファイル名と行番号を明示して具体的な改善案を提示してください。4. フックを追加する（任意）：
ファイル保存後に自動でlintチェックを走らせる例：
# code-review-plugin/hooks/hooks.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx eslint --fix 2>/dev/null || true"
}
]
}
]
}
}5. ローカルでテストする：
claude --plugin-dir ./code-review-plugin起動後に /code-review-plugin:review でスキルが使えることを確認する。変更を加えたら /reload-plugins で再読み込み（再起動不要）。
既存の .claude/ 設定をプラグイン化する
.claude/skills/ や .claude/commands/ にすでに蓄積した設定がある場合、プラグイン化は3ステップで完了する：
# 1. プラグインディレクトリを作る
mkdir -p my-plugin/.claude-plugin
# 2. マニフェストを作る
cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
{
"name": "my-plugin",
"description": "既存設定をプラグイン化",
"version": "1.0.0"
}
EOF
# 3. 既存のファイルをコピー
cp -r .claude/skills my-plugin/
cp -r .claude/commands my-plugin/ # commandsがある場合
# フックは .claude/settings.json の "hooks" セクションを hooks/hooks.json に移行移行後は claude --plugin-dir ./my-plugin でテストし、問題なければ .claude/ の元ファイルを削除する。プラグイン版が優先されるので重複しても動くが、どちらが使われているか混乱するので削除しておく方がいい。
バックグラウンドモニターの活用
プラグインが持てるユニークな機能の一つが「バックグラウンドモニター」だ。プラグインが有効な間、ログやファイルの変更を監視して、イベントが発生したときにClaudeへ通知を送る。
# monitors/monitors.json
[
{
"name": "error-log",
"command": "tail -F ./logs/error.log",
"description": "アプリケーションエラーログの監視"
},
{
"name": "test-results",
"command": "fswatch -x ./test/results/",
"description": "テスト結果ファイルの変更監視"
}
]command のstdoutの各行がClaudeへの通知として届く。「テストが失敗したらすぐに知りたい」「エラーログにWARNINGが出たらフォロー」といった自動化に使える。
よくあるエラーと対処法
/plugin コマンドが表示されない
Claude Codeのバージョンが古い。npm update -g @anthropic-ai/claude-code でアップデートする。プラグイン機能は比較的新しい機能（2026年初頭追加）なので、古いバージョンには存在しない。
スキルが /plugin:skill-name で呼べない
ディレクトリ構造を確認する。skills/ が .claude-plugin/ の中に入っていないか？正しくはプラグインルート直下に skills/ を置く。/reload-plugins を実行してみる。
フックが動かない
hooks/hooks.json の command がshellコマンドとして正しいか確認する。jqコマンドが入っていない環境では jq -r ... が失敗する。--plugin-dir でテストするときにCLIのパスがhooks内で解決されているか確認する。
プラグインのマーケットプレイスへの追加が反映されない
コミュニティマーケットプレイスは毎晩同期される。承認後すぐには表示されないことがある。anthropics/claude-plugins-community のGitHub上の marketplace.json でプラグイン名を検索して、承認されているか確認する。
MCP・スキル・プラグインの整理
混乱しやすいので整理しておく。
| 機能 | 役割 | 使い方 |
|---|---|---|
| スキル | Claudeに「/コマンド」を追加する | .claude/skills/ or プラグイン内 |
| MCP | Claudeに外部ツール連携能力を追加する | .mcp.json or プラグイン内の .mcp.json |
| フック | ツール使用前後にシェルコマンドを実行する | .claude/settings.json or プラグイン内 |
| プラグイン | スキル・MCP・フック・エージェントをひとまとめにする配布形式 | マーケットプレイス or --plugin-dir |
プラグインは「入れ物」だ。中身はスキル・MCP・フックのいずれか（または全部）で構成される。MCPサーバーだけを配布したければプラグイン形式にする必要は必ずしもなく、.mcp.json を直接共有してもいい。プラグイン形式にする理由は「インストールを1コマンドで完結させたい」「バージョン管理したい」という場合だ。
コミュニティプラグインを送信する
作ったプラグインをコミュニティに公開したい場合のフロー：
1. バリデーション：
claude plugin validateこれでプラグインの構造・マニフェスト・権限要求が正しいかチェックできる。送信前に必ず実行する。
2. 送信：
- Claude.ai から:
claude.ai/settings/plugins/submit - Console から:
platform.claude.com/plugins/submit
審査パイプラインは自動チェック＋人手レビュー。承認されると anthropics/claude-plugins-community リポジトリの marketplace.json にピン留めされる。
公式マーケットプレイス（claude-plugins-official）はAnthropicが独自に選定するため、申請フォームは存在しない。
まとめ
プラグインについての要点：
- プラグイン = スキル・フック・MCP・エージェントを「1パッケージ」にする配布形式
- 個人利用・1プロジェクト専用 → スタンドアロン（
.claude/）で十分 - チーム共有・マーケットプレイス配布 → プラグイン形式へ
plugin.jsonはメタデータのみ。機能はルートレベルのディレクトリに置く（.claude-plugin/内に入れない）- 公式マーケットプレイス55+本が既にある。まずは
claude plugin installで試す
自分で作る前にマーケットプレイスを一度眺めてみると、既製品で解決できるケースも多い。
