Claude Code Plugins 完全リファレンス 2026 — 7コンポーネント型・plugin.json・Marketplace 完全解説

Claude Code の プラグイン は、skills / subagents / hooks / MCP servers / LSP servers / monitors / commands を 1つのインストール可能な単位 にバンドルした自己完結ディレクトリ。本記事はその完全リファレンス：全コンポーネント型、全スキーマ、全CLIコマンドを Anthropic 公式 Claude Code plugin docs（2026年5月版）で検証して整理。

機能を配布のためにパッケージ化したい人（自分用・チーム用問わず）は、このページをブックマーク。

Skills / Subagents / Hooks を既に読んだ人へ：本記事は「それらを一緒に出荷する方法」の話。

プラグインとは

公式 docs（2026年5月）原文：「A plugin is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, LSP servers, and monitors.」

実際のところプラグインは Git リポジトリ（またはローカルディレクトリ）で：

• .claude-plugin/plugin.json — マニフェスト
• skills/ — slash command の Skills（または commands/ で簡易版）
• agents/ — 専門 subagents
• hooks/hooks.json — イベント駆動 hooks
• .mcp.json — プラグイン同梱の MCP サーバ
• .lsp.json — 言語インテリジェンス用 LSP サーバ
• monitors/monitors.json — バックグラウンド監視

Plugin Marketplace 経由（またはローカルパス / Git URL から）配布、Claude Code の /plugin インターフェースで管理。

なぜ Plugin？（vs バラの Skill / Subagent / Hook）

Skills、subagents、hooks は各単独で動く — Plugin 化は 必須ではない。じゃあ Plugin パッケージの価値は？

目安: 2人以上が使うコンポーネントなら Plugin 化。

Plugin マニフェスト (plugin.json)

.claude-plugin/plugin.json に置く（注意：.claude-plugin/ の中、他のコンポーネントは plugin ルートに置く）。最小例：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description",
  "author": {
    "name": "Your Name",
    "email": "[email protected]"
  }
}

オプションで plugin.json 内に inline で hooks、mcpServers、lspServers、monitors、userConfig（API endpoint 等のユーザー提供値）、dependencies（必要な他 Plugin）を持てる。

重要レイアウトルール（公式 docs より）：「Components must be at the plugin root, not inside .claude-plugin/, with only plugin.json belonging in .claude-plugin/ while commands/, agents/, and hooks/ stay at root level.」

7つのコンポーネント型

1. Skills

プラグインが /name slash command として skills を追加。

• 配置: skills/<skill-name>/SKILL.md（ディレクトリ）または commands/<command>.md（単ファイル）
• 自動検出 プラグインインストール時
• Claude が自動 invoke タスクコンテキスト依存、または /skill-name でユーザー手動 invoke

Skill ファイルは SKILL.md の横に補助ファイル（参考 docs、スクリプト、テンプレ）を含められる。SKILL.md の書き方は Skills ガイド 参照。

2. Agents（Subagents）

Claude が委譲できる専門 subagent。

• 配置: agents/<agent-name>.md
• Frontmatter フィールド: name、description、model、effort、maxTurns、tools、disallowedTools、skills、memory、background、isolation

Plugin 固有のセキュリティ制限（ユーザー定義 agent と異なる）：「For security reasons, hooks, mcpServers, and permissionMode are not supported for plugin-shipped agents.」 これらが必要なら、ユーザーが plugin から自分の .claude/agents/ にコピーする必要がある。

Plugin agent の isolation 唯一有効な値は "worktree"。

完全 subagent リファレンスは Claude Code Subagents 完全リファレンス 2026 参照。

3. Hooks

イベント駆動のシェルコマンド、HTTP webhook、MCP tool 呼び出し、prompt、agent。

• 配置: hooks/hooks.json（別ファイル）または plugin.json 内 hooks キーに inline
• 27 event types サポート（ユーザー hooks と同じ）：SessionStart、PreToolUse、PostToolUse、PostToolBatch、SubagentStart、TaskCreated など — フルリストは Hooks 完全リファレンス

hooks/hooks.json 例：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

${CLAUDE_PLUGIN_ROOT} はプラグインのインストールディレクトリ — プラグイン内スクリプトやアセットへのパスに使う。

4. MCP Servers

プラグイン有効化時に自動起動する MCP サーバをバンドル。

• 配置: .mcp.json（plugin root）または plugin.json の mcpServers に inline
• 自動起動/停止 プラグイン有効化・無効化に連動
• ユーザー level MCP と独立 に設定（衝突しない）

.mcp.json 例：

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    }
  }
}

5. LSP Servers

Language Server Protocol サーバで Claude に real-time なコードインテリジェンス（診断、go-to-definition、hover）を提供。

• 配置: .lsp.json（plugin root）または plugin.json の lspServers に inline
• 必須フィールド: command、extensionToLanguage
• オプション: args、transport（stdio or socket）、env、initializationOptions、settings、workspaceFolder、startupTimeout、shutdownTimeout、restartOnCrash、maxRestarts

Go の例：

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": { ".go": "go" }
  }
}

公式 docs の警告：「You must install the language server binary separately.」 LSP プラグインは Claude Code が LSP に接続する方法を設定するが、サーバ自体は含まれない。pip install pyright、npm install -g typescript-language-server 等を別途実行。

公式 marketplace プラグインには pyright-lsp（Python）、typescript-lsp、rust-analyzer-lsp がある。

6. Monitors

プラグイン起動時に Claude Code が自動で開始するバックグラウンドコマンド。各 monitor はセッションのライフタイム中シェルコマンドを実行、stdout の全行を Claude に通知として配信。

• 配置: monitors/monitors.json または plugin.json に inline
• 要件: Claude Code v2.1.105+
• 制約: インタラクティブ CLI セッションのみ、hooks と同じ信頼レベルで unsandboxed 実行

例：

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

オプションの when フィールドで、毎セッション開始ではなく特定 skill invoke 時のみ monitor を起動できる。

7. Commands

Skills の Markdown のみ軽量版。同じ /name invocation パターン。

• 配置: commands/<command>.md
• Frontmatter 不要（Skills と違って）
• 使うべき時: ワークフローが単一 Markdown ファイル + 補助スクリプト不要で完結する短さ

レイアウトチートシート

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # マニフェスト（.claude-plugin/ に入る唯一）
├── skills/
│   └── my-skill/
│       ├── SKILL.md
│       └── reference.md
├── commands/
│   └── quick-cmd.md
├── agents/
│   └── code-reviewer.md
├── hooks/
│   └── hooks.json
├── .mcp.json
├── .lsp.json
├── monitors/
│   └── monitors.json
└── README.md

「プラグインが動かない」報告の半分を解決する唯一のレイアウトルール：plugin.json 以外は全部 plugin ルートに置く、.claude-plugin/ の中ではない。

CLI コマンド

/plugin install のソース URI 形式：

# Marketplace から
/plugin install caveman

# Git URL から
/plugin install https://github.com/user/my-plugin

# ローカルディレクトリから
/plugin install ~/dev/my-plugin

# npm-style スコープ
/plugin install @company/internal-plugin

Plugin Marketplace

Plugin marketplace は発見可能な plugin レジストリ。Anthropic 公式 marketplace は Claude Code 同梱、ユーザーは追加 marketplace URL を加えられる。

• デフォルト marketplace: https://marketplace.claude.ai/（または類似、/plugin marketplace list で確認）
• カスタム marketplace: /plugin marketplace add <url>
• Marketplace フォーマット: <marketplace>/catalog.json に JSON カタログ、plugins・versions・install URLs を列挙

社内 plugin 向けに、会社 URL でプライベート marketplace も運用可能。

本番パターン

Pattern 1: チームオンボーディングプラグイン

Skills + hooks + MCP サーバを1プラグインにバンドル、新メンバーが同じ Claude Code セットアップを1コマンドで取得：

acme-onboarding/
├── .claude-plugin/plugin.json
├── skills/
│   ├── deploy/SKILL.md
│   └── postmortem/SKILL.md
├── hooks/hooks.json         # secret-guard, format-after-edit など
└── .mcp.json                # 社内 API MCP サーバ

新メンバーが /plugin install acme-onboarding を1回 → 他チームメンバーと同じ skills、hooks、MCP。

Pattern 2: ベンダー SDK プラグイン

ベンダー（例：Linear）が Claude Code に API アクセスを提供する plugin を出荷：

linear-plugin/
├── .claude-plugin/plugin.json
├── skills/
│   ├── create-issue/SKILL.md
│   ├── list-issues/SKILL.md
│   └── sprint-summary/SKILL.md
└── .mcp.json                # Linear MCP サーバ

ユーザーは1回インストール、Claude が Linear と話せるようになる（プロジェクト別の設定不要）。

Pattern 3: 言語スタックプラグイン

LSP サーバ + companion Skills + linting hooks を特定言語向けにバンドル：

typescript-stack/
├── .claude-plugin/plugin.json
├── .lsp.json                # typescript-language-server
├── hooks/hooks.json         # PostToolUse → prettier --write
├── skills/
│   ├── add-type-guards/SKILL.md
│   └── eliminate-anys/SKILL.md
└── agents/
    └── type-reviewer.md

Pattern 4: Caveman 出力圧縮スタイル

2026年5月時点で最人気の例 — 詳細は Caveman.MD 完全ガイド 参照。Caveman plugin がバンドルするもの：

• ルール集が skills/caveman/SKILL.md
• コマンド: /caveman、/caveman-commit、/caveman-review、/caveman-stats
• MCP middleware: caveman-shrink で他サーバのツール記述を圧縮

1 plugin インストール → セッション全体で65% 出力トークン削減。

セキュリティモデル

Plugin コンポーネントはユーザー信頼レベルで動く。3つの制限：

1. Plugin agent は hooks、mcpServers、permissionMode を使えない — plugin agent frontmatter にこれらフィールドがあっても silently 無視。ユーザーが必要なら plugin から ~/.claude/agents/ や .claude/agents/ にコピーする必要あり。
2. Plugin hook は unsandboxed で実行 — ユーザー hook と同じ信頼度。インストール前に plugin ソースを検証。
3. disableAllHooks: true をユーザー/プロジェクト設定に書いても、managed policy 設定で配備された plugin hook は無効化されない — managed level の disableAllHooks のみが managed hook を無効化できる。

信頼できない plugin はインストール前に監査：

git clone https://github.com/<user>/<plugin>
cd <plugin>
# plugin.json + hooks/hooks.json + あらゆるスクリプトを /plugin install 前に読む

よくある落とし穴

1. .claude-plugin/ の中にコンポーネントを置く。plugin.json だけがそこに入る。Skills、agents、hooks、MCP、LSP、monitors は全部 plugin ルート に。
2. スクリプトで ${CLAUDE_PLUGIN_ROOT} を忘れる。これがないと、シェルコマンドがユーザー環境に存在しないパスを参照する。常に："command": "${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh"。
3. LSP plugin に LSP バイナリなし。Plugin は接続方法を設定するだけ。ユーザー（or あなた）が pip install pyright / npm install -g <lsp> を別途実行する必要がある。Plugin docs が明示的に警告。
4. Plugin agent が mcpServers or hooks frontmatter を使う。silently 無視される。フィールドを削除するか、ユーザーが agent ファイルをコピーして使う必要があると明記する。
5. Monitor がブロッキングコマンドを実行。Monitor は stdout の全行を Claude に配信。コマンドが毎分1000行出力するなら、Claude のコンテキストが溢れる。ソースで filter：tail -F log | grep ERROR。
6. plugin.json の version 更新を忘れる。version が変わらないとユーザーに update が届かない。CI：main に merge するたび bump。

FAQ

Claude Code プラグインとバラの skill / subagent / hook の違いは？

プラグイン は1つ以上のコンポーネント（skills、subagents、hooks、MCP、LSP、monitors）を含むパッケージディレクトリ。バラのコンポーネント は個別ファイルを ~/.claude/skills/、~/.claude/agents/ 等に放り込む形式。プラグインは (1) プロジェクト横断で再利用、(2) チームと共有、(3) 公開配布、(4) 複数コンポーネント型をアトミックにバンドル、したい時の答え。

プラグインは skills のみで構成できる？それとも 7 全部必要？

Skills のみで完全に OK。最小プラグインは .claude-plugin/plugin.json + 1 skill（skills/<name>/SKILL.md）だけ。他は必要に応じて追加。人気プラグイン（Caveman、Impeccable）の多くは skills 重視で、補助コンポーネントは1-2個。

plugin.json はどこに置く？

.claude-plugin/plugin.json。.claude-plugin/（ドット付き）はプラグインルート内のマニフェストディレクトリ。それ以外（skills、agents、hooks、MCP、LSP、monitors）はプラグイン ルート に置く、.claude-plugin/ の中ではない。

${CLAUDE_PLUGIN_ROOT} とは？

ランタイムでのプラグインインストールディレクトリ。plugin 内のあらゆるコマンド/スクリプトパスに使う："command": "${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh"。実行時に Claude Code が実際のパスに置換する。

Plugin agent は hooks や MCP サーバを使える？

使えない（セキュリティ理由）。Plugin agent frontmatter は hooks、mcpServers、permissionMode を silently 無視。ユーザーが必要なら、plugin から agent ファイルを手動で .claude/agents/ または ~/.claude/agents/ にコピーする必要がある。

プラグインをチームに配布するには？

3つの選択肢：(1) Git URL — /plugin install https://github.com/team/plugin（最シンプル）、(2) ローカルパス — /plugin install ~/dev/team-plugin（開発）、(3) プライベート marketplace — 会社 URL に catalog.json をホストして、チームメンバーに /plugin marketplace add https://... を依頼。公開配布は Anthropic marketplace を使う。

disableAllHooks: true を設定すると plugin hook も無効化される？

状況による。ユーザー/プロジェクトレベルの disableAllHooks: true は自分の hook と plugin パッケージで installed された plugin hook を無効化する。ただし managed policy 設定 で配備された hook（組織 admin）は生き残る — managed level の disableAllHooks のみが managed hook を無効化できる。

Monitor とは何か、Hook とどう違う？

Monitor はプラグイン起動時に開始されるバックグラウンドシェルコマンド、stdout の全行が Claude への通知になる。Hook はイベント駆動で、マッチイベントごとに1回 fire（PreToolUse、PostToolUse 等）。「Claude のために X を常時 watch する」ワークフローは monitor、「Z が起きたら Y する」ワークフローは hook。

plugin.json で特定 Claude Code バージョンを require できる？

できる — "engines": { "claude-code": ">=2.1.105" } を plugin.json に。Monitors（2.1.105+ 必要）や他のバージョン依存機能に有用。古い Claude Code のユーザーは謎のランタイム失敗ではなく明確な install-time エラーを得る。

インストール済みプラグインを update するには？

/plugin update <name> は単一プラグインをソースの最新版に update。/plugin update（名前なし）は全インストール済みプラグインを update。バージョン pinning を尊重（インストール時に "version": "1.2.x" 指定した場合）。

関連記事

• Claude Code Subagents 完全リファレンス 2026
• Claude Code Hooks 完全リファレンス 2026
• Caveman.MD 完全ガイド 2026
• AGENTS.md vs CLAUDE.md vs .cursor/rules 3方比較
• 2026年インストールすべきClaude Code Skillsベスト15
• 165以上のAIコーディングルール実例集

外部参考

• Plugins reference — Claude Code Docs（Anthropic、2026年5月）
• Plugins overview
• Plugin marketplaces