【2026年最新版】Claude Codeプラグイン開発入門 — 自作プラグインでチームの開発体験を拡張する

Last updated at 2026-03-19Posted at 2026-03-19

はじめに

こんばんは、mirukyです。

Claude Code を使い始めると、プロジェクト固有のスキルやフック、MCP サーバーの設定を .claude/ ディレクトリに蓄積していくことになります。しかし、チームメンバーにその設定を共有したい、他のプロジェクトでも再利用したい、バージョン管理をして安定した配布をしたい と思ったとき、どうすればいいでしょうか？

Claude Code プラグインは、スキル、エージェント、フック、MCP サーバー、LSP サーバーを1つのパッケージとしてまとめ、マーケットプレイスを通じて配布・インストールできる仕組みです。2025年10月9日のv2.0.12で初めてリリースされて以降、LSP サーバー対応（v2.0.74）、プラグイン設定（v2.1.51）、永続データディレクトリ（v2.1.78）など、急速に進化しています。

この記事では、プラグインの作成からテスト、マーケットプレイスでの配布まで、ゼロからプラグイン開発者になるための完全ロードマップを提供します。

プラグインとは何か？スタンドアロン設定との違い
最初のプラグインを作る — Quickstart
プラグインの構造を理解する
コンポーネント別開発ガイド
plugin.json マニフェスト完全リファレンス
環境変数とパス解決
テストとデバッグ
マーケットプレイスで配布する
既存設定からプラグインへの移行
実践: エンタープライズ向けプラグインを作る
インストールスコープと設定
トラブルシューティング
バージョン別進化の歴史
まとめ

1. プラグインとは何か？スタンドアロン設定との違い

2つのアプローチの比較

	スタンドアロン（`.claude/`）	プラグイン（`.claude-plugin/`）
スキル呼び出し	`/hello`	`/plugin-name:hello`
共有のしやすさ	手動でコピーが必要	マーケットプレイスで簡単インストール
スコープ	単一プロジェクト	ユーザー / プロジェクト / ローカル横断
バージョン管理	なし	セマンティックバージョニング対応
名前衝突	起こりうる	ネームスペースで防止
適した用途	個人ワークフロー、実験	チーム共有、コミュニティ配布

いつプラグインにすべきか？

スタンドアロン設定が適切な場合:

単一プロジェクトのカスタマイズ
個人的な設定で共有不要
スキルやフックの実験段階
/hello のような短いスキル名を使いたい

プラグインが適切な場合:

チームやコミュニティに機能を共有したい
同じスキル/エージェントを複数プロジェクトで使いたい
バージョン管理と簡単なアップデートを実現したい
マーケットプレイスを通じて配布したい

推奨ワークフロー: まずは .claude/ でスタンドアロン設定として素早くイテレーションし、共有の準備ができたらプラグインに変換しましょう。

2. 最初のプラグインを作る — Quickstart

前提条件

Claude Code がインストール＆認証済み
Claude Code v1.0.33 以降（claude --version で確認）

Step 1: プラグインディレクトリを作成

mkdir my-first-plugin

Step 2: マニフェストを作成

mkdir my-first-plugin/.claude-plugin

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"
  }
}

フィールド	役割
`name`	一意識別子＆スキルの名前空間。スキルは `/my-first-plugin:hello` のようにプレフィックスされる
`description`	プラグインマネージャーでの説明表示
`version`	セマンティックバージョニングによるリリース追跡
`author`	帰属情報（任意）

Step 3: スキルを追加

mkdir -p my-first-plugin/skills/hello

my-first-plugin/skills/hello/SKILL.md:

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

Step 4: テスト

claude --plugin-dir ./my-first-plugin

Claude Code が起動したら、新しいスキルを試します：

/my-first-plugin:hello

Claude がグリーティングで応答すれば成功です。/help でプラグインの名前空間の下にスキルが表示されます。

なぜネームスペース？ プラグインのスキルは衝突を防ぐために常にネームスペースされます（/my-first-plugin:hello）。ネームスペースのプレフィックスを変更するには、plugin.json の name フィールドを更新します。

Step 5: 引数を追加

$ARGUMENTS プレースホルダーでユーザー入力をキャプチャできます。

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

変更を反映するには /reload-plugins を実行：

/my-first-plugin:hello Alex

Claude が「Alex」を名前で呼んでグリーティングします。

3. プラグインの構造を理解する

標準ディレクトリレイアウト

enterprise-plugin/
├── .claude-plugin/           # メタデータディレクトリ（任意）
│   └── plugin.json            # プラグインマニフェスト
├── commands/                 # コマンド（Markdown ファイル）
│   ├── status.md
│   └── logs.md
├── agents/                   # カスタムエージェント定義
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # スキル（SKILL.md 構造）
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # フック設定
│   ├── hooks.json             # メインフック設定
│   └── security-hooks.json    # 追加フック
├── settings.json             # プラグイン有効時のデフォルト設定
├── .mcp.json                 # MCP サーバー定義
├── .lsp.json                 # LSP サーバー設定
├── scripts/                  # フック・ユーティリティスクリプト
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE
└── CHANGELOG.md

.claude-plugin/ ディレクトリには plugin.json ファイルのみを配置してください。commands/、agents/、skills/、hooks/ などのディレクトリはプラグインルートに配置する必要があります。これは最も多い設定ミスの1つです。

ファイル配置リファレンス

コンポーネント	場所	説明
マニフェスト	`.claude-plugin/plugin.json`	プラグインメタデータと設定（任意）
コマンド	`commands/`	スキル Markdown ファイル（レガシー。新規は `skills/` を推奨）
エージェント	`agents/`	サブエージェント Markdown ファイル
スキル	`skills/`	`<name>/SKILL.md` 構造のスキル
フック	`hooks/hooks.json`	フック設定
MCP サーバー	`.mcp.json`	MCP サーバー定義
LSP サーバー	`.lsp.json`	言語サーバー設定
設定	`settings.json`	プラグイン有効時のデフォルト設定（現在は `agent` キーのみ対応）

4. コンポーネント別開発ガイド

1. スキル（Skills）

スキルはプラグインのコア機能です。Claude が自動的にタスクコンテキストに基づいて呼び出せます。

ディレクトリ構造:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (任意)
│   └── scripts/ (任意)
└── code-reviewer/
    └── SKILL.md

SKILL.md の例:

---
name: code-review
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

動作:

プラグインインストール時にスキルとコマンドは自動的に検出される
Claude がタスクコンテキストに基づき自動的に呼び出し可能
スキルは SKILL.md と一緒にサポートファイルを含められる

2. エージェント（Agents）

特定タスクに特化したサブエージェントを提供します。

エージェント Markdown の例（agents/security-reviewer.md）:

---
name: security-reviewer
description: Specialized agent for reviewing code security. Invoke when analyzing security vulnerabilities, checking authentication flows, or auditing sensitive operations.
---

You are a security-focused code reviewer. Your role is to:

1. Identify potential security vulnerabilities
2. Check for common OWASP issues
3. Verify authentication and authorization patterns
4. Flag sensitive data handling concerns

Be thorough but concise. Prioritize critical issues.

動作:

/agents インターフェースに表示
Claude がタスクコンテキストに基づき自動呼び出し可能
ユーザーが手動で呼び出すことも可能
プラグインエージェントは組み込みエージェントと並んで動作

3. フック（Hooks）

イベントハンドラーとして、Claude Code のイベントに自動で応答します。

hooks/hooks.jsonの例:

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

利用可能なイベント（全 21 種）:

カテゴリ	イベント名
ツール関連	`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`
セッション	`SessionStart`, `SessionEnd`, `ConfigChange`
ユーザー操作	`UserPromptSubmit`, `Notification`
エージェント	`SubagentStart`, `SubagentStop`, `Stop`
チーム	`TeammateIdle`, `TaskCompleted`
コンパクション	`PreCompact`, `PostCompact`
エリシテーション	`Elicitation`, `ElicitationResult`
ワークツリー	`WorktreeCreate`, `WorktreeRemove`
その他	`InstructionsLoaded`

フックタイプ（全 4 種）:

タイプ	説明
`command`	シェルコマンドやスクリプトを実行
`http`	HTTP エンドポイントに JSON を POST 送信
`prompt`	LLM でプロンプトを評価（`$ARGUMENTS` プレースホルダーでコンテキスト展開）
`agent`	ツールアクセス付きのエージェント検証（複雑な検証タスク向け）

フックスクリプト内では必ず ${CLAUDE_PLUGIN_ROOT} を使ってプラグイン内のファイルを参照してください。プラグインはインストール時にキャッシュディレクトリにコピーされるため、相対パスは正しく動作しません。

4. MCP サーバー

外部ツールやサービスと Claude Code を接続する Model Context Protocol サーバーをバンドルできます。

.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"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

動作:

プラグイン有効時に MCP サーバーは自動的に起動
サーバーは Claude のツールキットに標準 MCP ツールとして表示
ユーザーの MCP サーバーとは独立して設定可能

5. LSP サーバー

Language Server Protocol サーバーを提供し、Claude にリアルタイムのコードインテリジェンスを提供します。

LSP が提供するもの:

即座の診断: 編集直後にエラーと警告を検出
コードナビゲーション: 定義ジャンプ、参照検索、ホバー情報
言語認識: コードシンボルの型情報とドキュメント

.lsp.jsonの例:

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

必須フィールド:

フィールド	説明
`command`	実行する LSP バイナリ（PATH にある必要あり）
`extensionToLanguage`	ファイル拡張子と言語識別子のマッピング

オプションフィールド:

フィールド	説明
`args`	LSP サーバーのコマンドライン引数
`transport`	通信トランスポート: `stdio`（デフォルト）または `socket`
`env`	サーバー起動時の環境変数
`initializationOptions`	初期化時にサーバーに渡すオプション
`settings`	`workspace/didChangeConfiguration` で渡す設定
`workspaceFolder`	ワークスペースフォルダのパス
`startupTimeout`	サーバー起動の最大待機時間（ミリ秒）
`shutdownTimeout`	グレースフルシャットダウンの最大待機時間（ミリ秒）
`restartOnCrash`	クラッシュ時の自動再起動
`maxRestarts`	最大再起動試行回数

利用可能な公式 LSP プラグイン:

プラグイン名	言語サーバー	インストール方法
`pyright-lsp`	Pyright (Python)	`pip install pyright` または `npm install -g pyright`
`typescript-lsp`	TypeScript Language Server	`npm install -g typescript-language-server typescript`
`rust-lsp`	rust-analyzer	rust-analyzer のインストールガイド

LSP プラグインは言語サーバーの設定方法を提供するだけで、サーバー自体は含まれません。ユーザーは個別に言語サーバーバイナリをインストールする必要があります。

6. デフォルト設定（settings.json）

プラグイン有効時にデフォルト設定を適用できます。現在は agent キーのみ対応しています。

{
  "agent": "security-reviewer"
}

この設定により、agents/ ディレクトリのエージェントがメインスレッドとして有効化され、そのシステムプロンプト、ツール制限、モデルが適用されます。

5. plugin.json マニフェスト完全リファレンス

完全スキーマ

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

必須フィールド

マニフェストを含める場合、name のみが必須です。

フィールド	型	説明	例
`name`	string	一意識別子（kebab-case、スペース不可）	`"deployment-tools"`

メタデータフィールド

フィールド	型	説明
`version`	string	セマンティックバージョン
`description`	string	プラグインの簡単な説明
`author`	object	作者情報（`name`, `email`, `url`）
`homepage`	string	ドキュメント URL
`repository`	string	ソースコード URL
`license`	string	ライセンス識別子
`keywords`	array	検索用タグ

コンポーネントパスフィールド

フィールド	型	説明
`commands`	string/array	コマンドファイル/ディレクトリへのパス
`agents`	string/array	エージェントファイルへのパス
`skills`	string/array	スキルディレクトリへのパス
`hooks`	string/array/object	フック設定パスまたはインライン設定
`mcpServers`	string/array/object	MCP 設定パスまたはインライン設定
`outputStyles`	string/array	出力スタイルファイル/ディレクトリ
`lspServers`	string/array/object	LSP サーバー設定

パスの動作ルール

カスタムパスはデフォルトディレクトリを補完するものであり、置換するものではありません。commands/ ディレクトリが存在する場合、カスタムパスのコマンドに加えて読み込まれます。

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

すべてのパスはプラグインルートからの相対パスで、./ で始まる
複数パスは配列で柔軟に指定可能

6. 環境変数とパス解決

2つの重要な環境変数

プラグイン開発では、以下の2つの環境変数を正しく理解することが極めて重要です。

`${CLAUDE_PLUGIN_ROOT}`

プラグインのインストールディレクトリへの絶対パスです。

用途: スクリプト、バイナリ、設定ファイルなど、プラグインにバンドルされたファイルの参照

注意: プラグインのアップデート時にパスが変更されるため、ここに書き込んだファイルはアップデートで消失します。

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

`${CLAUDE_PLUGIN_DATA}`

プラグインの永続データディレクトリへのパスです（~/.claude/plugins/data/{id}/）。

用途: node_modules や Python 仮想環境などのインストール済み依存関係、生成コード、キャッシュ、バージョン間で永続化すべきファイル

特徴:

プラグインのアップデートをまたいで永続化
初回参照時に自動作成
アンインストール時に自動削除（--keep-data で保持可能）

永続データの実践パターン — 依存関係の管理

ディレクトリ存在チェックだけでは、プラグインアップデート時の依存関係マニフェスト変更を検出できません。推奨パターンはバンドルされたマニフェストとデータディレクトリのコピーを比較する方法です。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

動作の仕組み:

diff でバンドル版と保存版の package.json を比較
保存版がない or 差異がある → コピーして npm install を実行
npm install が失敗 → 保存版を削除（次セッションでリトライ）

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

7. テストとデバッグ

ローカルテスト

--plugin-dir フラグでプラグインをインストールなしでテストできます。

# 基本的なテスト
claude --plugin-dir ./my-plugin

# 複数プラグインの同時テスト
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

テストチェックリスト:

/plugin-name:skill-name でスキルが動作するか確認
/agents にエージェントが表示されるか確認
フックが期待通りに発火するか確認

ホットリロード

コード変更後は /reload-plugins で再起動なしにリロードできます。コマンド、スキル、エージェント、フック、プラグイン MCP サーバー、プラグイン LSP サーバーがすべてリロードされます。

--plugin-dir で読み込んだプラグインがインストール済みのマーケットプレイスプラグインと同名の場合、ローカルコピーが優先されます。マネージドポリシーで強制有効化されたプラグインのみ例外です。

バリデーション

# プラグインの検証
claude plugin validate .

# Claude Code 内から
/plugin validate .

バリデーターは plugin.json、スキル/エージェント/コマンドのフロントマター、hooks/hooks.json の構文とスキーマエラーをチェックします。

デバッグ

# デバッグモードで起動
claude --debug

デバッグ出力で確認できること：

読み込み中のプラグイン
プラグインマニフェストのエラー
コマンド、エージェント、フックの登録状況
MCP サーバーの初期化

よくある問題

症状	原因	解決策
プラグインが読み込まれない	無効な plugin.json	`claude plugin validate` または `/plugin validate` で確認
コマンドが表示されない	ディレクトリ構造が間違い	`commands/` がルートにあることを確認（`.claude-plugin/` 内ではない）
フックが発火しない	スクリプトが実行不可	`chmod +x script.sh`
MCP サーバーが失敗	`${CLAUDE_PLUGIN_ROOT}` 未使用	すべてのプラグインパスにこの変数を使用
パスエラー	絶対パスを使用	パスは相対で `./` 始まりにする
LSP の "Executable not found"	言語サーバー未インストール	バイナリを個別にインストール

8. マーケットプレイスで配布する

マーケットプレイスの基本構造

マーケットプレイスは、プラグインのカタログ（marketplace.json）とプラグイン本体を含むリポジトリです。

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json        # プラグインカタログ
└── plugins/
    ├── code-formatter/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   └── skills/
    └── deployment-tools/
        ├── .claude-plugin/
        │   └── plugin.json
        └── hooks/

marketplace.json を作成

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

マーケットプレイススキーマ

必須フィールド

フィールド	型	説明
`name`	string	マーケットプレイス識別子（kebab-case）
`owner`	object	メンテナー情報（`name` 必須、`email` 任意）
`plugins`	array	プラグインリスト

予約名: claude-code-marketplace、claude-code-plugins、claude-plugins-official、anthropic-marketplace、anthropic-plugins、agent-skills、life-sciences などの名前は公式 Anthropic 用に予約されています。

プラグインエントリの必須フィールド

フィールド	型	説明
`name`	string	プラグイン識別子（kebab-case）
`source`	string/object	プラグインの取得元

プラグインソースの種類

ソースタイプ	形式	説明
相対パス	`"./plugins/my-plugin"`	マーケットプレイスリポジトリ内のローカルディレクトリ
GitHub	`{"source": "github", "repo": "owner/repo"}`	GitHub リポジトリ（`ref`, `sha` でバージョン固定可能）
Git URL	`{"source": "url", "url": "https://..."}`	GitLab 等の Git リポジトリ
Git サブディレクトリ	`{"source": "git-subdir", "url": "...", "path": "..."}`	モノレポ内のサブディレクトリ（sparse clone）
npm	`{"source": "npm", "package": "@org/plugin"}`	npm パッケージ（`version`, `registry` 指定可能）
pip	`{"source": "pip", "package": "plugin-name"}`	pip パッケージ（`version`, `registry` 指定可能）

GitHub での配布（推奨）

マーケットプレイス用リポジトリを作成
.claude-plugin/marketplace.json を配置
ユーザーは以下でマーケットプレイスを追加：

/plugin marketplace add owner/repo

インストールと更新

# マーケットプレイスの追加
/plugin marketplace add owner/repo

# プラグインのインストール
/plugin install code-formatter@company-tools

# プロジェクトスコープでインストール（チーム共有）
/plugin install code-formatter@company-tools --scope project

# プラグインの更新
/plugin update code-formatter@company-tools

# プラグインのアンインストール
/plugin uninstall code-formatter@company-tools

チーム向け設定

.claude/settings.json にマーケットプレイスを設定すると、チームメンバーがプロジェクトフォルダを信頼したときにマーケットプレイスのインストールが自動的に案内されます。

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

公式マーケットプレイスへの投稿

プラグインを公式 Anthropic マーケットプレイスに投稿するには：

Claude.ai: claude.ai/settings/plugins/submit
Console: platform.claude.com/plugins/submit

9. 既存設定からプラグインへの移行

移行手順

Step 1: プラグイン構造を作成

mkdir -p my-plugin/.claude-plugin

my-plugin/.claude-plugin/plugin.json:

{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}

Step 2: 既存ファイルをコピー

# コマンドをコピー
cp -r .claude/commands my-plugin/

# エージェントをコピー（あれば）
cp -r .claude/agents my-plugin/

# スキルをコピー（あれば）
cp -r .claude/skills my-plugin/

Step 3: フックを移行

mkdir my-plugin/hooks

.claude/settings.json の hooks オブジェクトを my-plugin/hooks/hooks.json にコピー（フォーマットは同一）:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}

Step 4: テスト

claude --plugin-dir ./my-plugin

移行による変更点

移行前（スタンドアロン）	移行後（プラグイン）
1つのプロジェクトでのみ利用可能	マーケットプレイスで共有可能
`.claude/commands/` 内のファイル	`plugin-name/commands/` 内のファイル
`settings.json` 内のフック	`hooks/hooks.json` 内のフック
共有には手動コピーが必要	`/plugin install` で簡単インストール

10. 実践: エンタープライズ向けプラグインを作る

ここでは、セキュリティレビュー、コードフォーマット、MCP サーバーを統合したエンタープライズ向けプラグインの完全な例を紹介します。

ディレクトリ構造

enterprise-security-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── security-review/
│       └── SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/
│   └── hooks.json
├── scripts/
│   ├── validate-security.sh
│   └── format-on-save.sh
├── .mcp.json
├── settings.json
├── LICENSE
├── README.md
└── CHANGELOG.md

plugin.json

{
  "name": "enterprise-security",
  "version": "1.0.0",
  "description": "Enterprise security review and code quality automation",
  "author": {
    "name": "Security Team",
    "email": "security@example.com"
  },
  "repository": "https://github.com/company/enterprise-security-plugin",
  "license": "MIT",
  "keywords": ["security", "enterprise", "code-quality"]
}

skills/security-review/SKILL.md

---
name: security-review
description: Comprehensive security review of code changes. Use when analyzing code for security vulnerabilities, checking authentication flows, or auditing API endpoints.
---

# Security Review Skill

Perform a comprehensive security review:

1. **Input Validation**: Check all user inputs for proper sanitization
2. **Authentication**: Verify auth flows and token handling
3. **Authorization**: Check access control patterns
4. **Data Protection**: Flag sensitive data exposure risks
5. **Dependencies**: Check for known vulnerable dependencies

Use $ARGUMENTS as the scope of the review.

agents/security-reviewer.md

---
name: security-reviewer
description: Deep security analysis agent with code inspection capabilities
---

You are a senior security engineer conducting a thorough code review.

## Your Responsibilities
- Identify OWASP Top 10 vulnerabilities
- Check for hardcoded credentials or secrets
- Verify proper error handling (no stack traces leaked)
- Assess dependency security

## Output Format
Provide findings as:
- Critical: Must fix before merge
- Warning: Should fix soon
- Info: Best practice suggestions

hooks/hooks.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-security.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-on-save.sh"
          }
        ]
      }
    ]
  }
}

scripts/validate-security.sh

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty')

# .env ファイルや秘密鍵への書き込みをブロック
PROTECTED_PATTERNS=(".env" ".pem" ".key" "secrets" "credentials")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: Writing to sensitive file '$FILE_PATH' is not allowed" >&2
    exit 2
  fi
done

# ハードコードされたシークレットを検出
if echo "$CONTENT" | grep -qiE "(password|secret|api_key|token)[[:space:]]*=[[:space:]]*[\"'][^\"']+[\"']"; then
  echo "Warning: Potential hardcoded secret detected in $FILE_PATH" >&2
  exit 2
fi

exit 0

chmod +x scripts/validate-security.sh

settings.json

{
  "agent": "security-reviewer"
}

11. インストールスコープと設定

スコープの選択

スコープ	設定ファイル	用途
`user`	`~/.claude/settings.json`	個人用プラグイン（デフォルト）
`project`	`.claude/settings.json`	チーム共有（バージョン管理に含める）
`local`	`.claude/settings.local.json`	プロジェクト固有（gitignore 対象）
`managed`	マネージド設定	管理者制御（読み取り専用、更新のみ）

CLI コマンドリファレンス

# インストール（デフォルト: user スコープ）
claude plugin install formatter@my-marketplace

# プロジェクトスコープ（チーム共有）
claude plugin install formatter@my-marketplace --scope project

# ローカルスコープ（gitignore 対象）
claude plugin install formatter@my-marketplace --scope local

# アンインストール
claude plugin uninstall formatter@my-marketplace

# 永続データを保持してアンインストール
claude plugin uninstall formatter@my-marketplace --keep-data

# 有効化
claude plugin enable formatter@my-marketplace

# 無効化
claude plugin disable formatter@my-marketplace

# 更新
claude plugin update formatter@my-marketplace

プラグインキャッシュ

プラグインはインストール時にローカルのプラグインキャッシュ（~/.claude/plugins/cache）にコピーされます。これはセキュリティと検証のためです。

パス走査の制限: インストール済みプラグインはディレクトリ外のファイルを参照できません。../shared-utils のようなパスはコピー後に動作しません。

外部依存関係の回避策: シンボリックリンクを使用できます。

# プラグインディレクトリ内で
ln -s /path/to/shared-utils ./shared-utils

シンボリックリンクの内容はコピープロセスで追随されます。

12. トラブルシューティング

マニフェスト検証エラー

エラー	原因	対策
`Invalid JSON syntax: Unexpected token }...`	JSON 構文エラー	カンマの過不足、クォートの漏れを確認
`Plugin has an invalid manifest file... name: Required`	必須フィールドの欠落	`name` フィールドを追加
`Plugin has a corrupt manifest file...`	JSON パースエラー	JSON 構文を修正

プラグインロードエラー

エラー	原因	対策
`Warning: No commands found in plugin...`	コマンドパスにファイルなし	`.md` ファイルまたは `SKILL.md` を配置
`Plugin directory not found...`	ソースパスが不正	`marketplace.json` のパスを確認
`Plugin has conflicting manifests...`	マニフェスト重複	重複コンポーネント定義を削除

フックのトラブルシューティング

スクリプトが実行可能か確認: chmod +x ./scripts/your-script.sh
シバン行を確認: #!/bin/bash または #!/usr/bin/env bash
パスに ${CLAUDE_PLUGIN_ROOT} を使用: "command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"
スクリプトを手動テスト: ./scripts/your-script.sh
イベント名の大文字小文字を確認（ケースセンシティブ）: PostToolUse（正） / postToolUse（誤）

Git 操作のタイムアウト

デフォルトのタイムアウトは120秒です。大きなリポジトリや遅いネットワークの場合：

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5分

13. バージョン別進化の歴史

バージョン	リリース日	追加された機能
v2.0.12	2025年10月9日	プラグインシステム初回リリース
v2.0.74	2025年12月19日	LSP サーバー対応追加
v2.1.32	2026年2月5日	Agent Teams（実験的）— プラグインエージェントの連携強化
v2.1.51	2026年2月24日	プラグイン `settings.json` 対応追加
v2.1.78	2026年3月17日	プラグイン永続データ（`${CLAUDE_PLUGIN_DATA}`）追加

バージョン管理のベストプラクティス

{
  "name": "my-plugin",
  "version": "2.1.0"
}

MAJOR.MINOR.PATCH 形式
MAJOR: 破壊的変更
MINOR: 後方互換の新機能
PATCH: バグ修正
初回安定リリースは 1.0.0 から開始
テスト用にプレリリースバージョン（2.0.0-beta.1）を使用可能

Claude Code はバージョン番号を使用してプラグインのアップデートを判断します。コードを変更しても plugin.json のバージョンを上げないと、既存ユーザーにはキャッシングのため変更が反映されません。

14. まとめ

プラグイン開発の全体像

Claude Code プラグインシステムの主要要素をまとめます。

6つのコンポーネント:

Skills — カスタムスキル（/plugin:skill で呼び出し）
Agents — 特化型サブエージェント
Hooks — イベント駆動の自動化
MCP — 外部ツール・サービス統合
LSP — リアルタイムコードインテリジェンス
Settings — デフォルト設定の適用

配布方法:

--plugin-dir — ローカルテスト
マーケットプレイス — チーム・コミュニティ配布
公式マーケットプレイス — Anthropic 公式ストア

開発フロー:

mkdir + plugin.json — 構造を作る
skills/ agents/ hooks/ — コンポーネントを追加
--plugin-dir テスト — 動作確認
/reload-plugins — ホットリロード
marketplace.json — 配布の準備
/plugin install — チームに配布

クイックリファレンス

# プラグイン作成
mkdir -p my-plugin/.claude-plugin
echo '{"name":"my-plugin","version":"1.0.0"}' > my-plugin/.claude-plugin/plugin.json

# スキル追加
mkdir -p my-plugin/skills/hello && cat > my-plugin/skills/hello/SKILL.md << 'EOF'
---
description: Greet the user
---
Greet the user warmly.
EOF

# テスト
claude --plugin-dir ./my-plugin

# バリデーション
claude plugin validate ./my-plugin

# マーケットプレイス配布
# /plugin marketplace add owner/repo
# /plugin install my-plugin@marketplace-name

いつものことですが、Claude Codeを隅から隅まで使い倒して、快適なエンジニアライフを送りましょう！
ではまた、お会いしましょう。

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

【2026年最新版】Claude Codeプラグイン開発入門 — 自作プラグインでチームの開発体験を拡張する

はじめに

目次

1. プラグインとは何か？スタンドアロン設定との違い

2つのアプローチの比較

いつプラグインにすべきか？

2. 最初のプラグインを作る — Quickstart

前提条件

Step 1: プラグインディレクトリを作成

Step 2: マニフェストを作成

Step 3: スキルを追加

Step 4: テスト

Step 5: 引数を追加

3. プラグインの構造を理解する

標準ディレクトリレイアウト

ファイル配置リファレンス

4. コンポーネント別開発ガイド

1. スキル（Skills）

2. エージェント（Agents）

3. フック（Hooks）

4. MCP サーバー

5. LSP サーバー

6. デフォルト設定（settings.json）

5. plugin.json マニフェスト完全リファレンス

完全スキーマ

必須フィールド

メタデータフィールド

コンポーネントパスフィールド

パスの動作ルール

6. 環境変数とパス解決

2つの重要な環境変数

${CLAUDE_PLUGIN_ROOT}

${CLAUDE_PLUGIN_DATA}

永続データの実践パターン — 依存関係の管理

7. テストとデバッグ

ローカルテスト

ホットリロード

バリデーション

デバッグ

よくある問題

8. マーケットプレイスで配布する

マーケットプレイスの基本構造

marketplace.json を作成

マーケットプレイススキーマ

必須フィールド

プラグインエントリの必須フィールド

プラグインソースの種類

GitHub での配布（推奨）

インストールと更新

チーム向け設定

公式マーケットプレイスへの投稿

9. 既存設定からプラグインへの移行

移行手順

Step 1: プラグイン構造を作成

Step 2: 既存ファイルをコピー

Step 3: フックを移行

Step 4: テスト

移行による変更点

10. 実践: エンタープライズ向けプラグインを作る

ディレクトリ構造

plugin.json

skills/security-review/SKILL.md

agents/security-reviewer.md

hooks/hooks.json

scripts/validate-security.sh

settings.json

11. インストールスコープと設定

スコープの選択

CLI コマンドリファレンス

プラグインキャッシュ

12. トラブルシューティング

マニフェスト検証エラー

プラグインロードエラー

フックのトラブルシューティング

Git 操作のタイムアウト

13. バージョン別進化の歴史

バージョン管理のベストプラクティス

14. まとめ

プラグイン開発の全体像

クイックリファレンス

`${CLAUDE_PLUGIN_ROOT}`

`${CLAUDE_PLUGIN_DATA}`