plugin-structure

Claude Code のプラグイン構成

概要

Claude Code のプラグインは、コンポーネントを自動検出する標準化されたディレクトリ構成に従います。この構成を理解すると、Claude Code とシームレスに連携する、整理された保守しやすいプラグインを作成できます。

主な概念：

• 自動検出のための標準的なディレクトリ構成
• .claude-plugin/plugin.json によるマニフェスト駆動型の設定
• コンポーネントごとの整理（コマンド、エージェント、スキル、フック）
• ${CLAUDE_PLUGIN_ROOT} を使ったポータブルなパス参照
• コンポーネントの明示的な読み込みと自動検出による読み込み

ディレクトリ構成

すべての Claude Code プラグインは、次の構成に従います。

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Slash commands (.md files)
├── agents/                   # Subagent definitions (.md files)
├── skills/                   # Agent skills (subdirectories)
│   └── skill-name/
│       └── SKILL.md         # Required for each skill
├── hooks/
│   └── hooks.json           # Event handler configuration
├── .mcp.json                # MCP server definitions
└── scripts/                 # Helper scripts and utilities

重要なルール：

1. マニフェストの場所：plugin.json マニフェストは .claude-plugin/ ディレクトリに置く必要があります
2. コンポーネントの場所：すべてのコンポーネントディレクトリ（commands、agents、skills、hooks）は、.claude-plugin/ の中ではなく、プラグインのルート階層に置く必要があります
3. 任意のコンポーネント：プラグインで実際に使用するコンポーネントのディレクトリのみを作成してください
4. 命名規則：すべてのディレクトリ名とファイル名に kebab-case を使用してください

プラグインマニフェスト（plugin.json）

マニフェストでは、プラグインのメタデータと設定を定義します。.claude-plugin/plugin.json に配置します。

必須フィールド

{
  "name": "plugin-name"
}

名前の要件：

• kebab-case 形式（小文字とハイフン）を使用します
• インストール済みのプラグイン間で一意である必要があります
• スペースや特殊文字は使用できません
• 例：code-review-assistant、test-runner、api-docs

推奨メタデータ

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief explanation of plugin purpose",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://example.com"
  },
  "homepage": "https://docs.example.com",
  "repository": "https://github.com/user/plugin-name",
  "license": "MIT",
  "keywords": ["testing", "automation", "ci-cd"]
}

バージョン形式：セマンティックバージョニング（MAJOR.MINOR.PATCH）に従います キーワード：プラグインの検索と分類に使用します

コンポーネントのパス設定

コンポーネントにカスタムパスを指定できます（デフォルトのディレクトリを補完します）。

{
  "name": "plugin-name",
  "commands": "./custom-commands",
  "agents": ["./agents", "./specialized-agents"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./.mcp.json"
}

重要：カスタムパスはデフォルトを補完するものであり、置き換えるものではありません。デフォルトのディレクトリとカスタムパスの両方にあるコンポーネントが読み込まれます。

パスのルール：

• プラグインのルートからの相対パスである必要があります
• ./ で始める必要があります
• 絶対パスは使用できません
• 複数の場所を配列で指定できます

コンポーネントの構成

コマンド

場所：commands/ ディレクトリ 形式：YAML フロントマター付きの Markdown ファイル 自動検出：commands/ 内のすべての .md ファイルが自動的に読み込まれます

構成例：

commands/
├── review.md        # /review command
├── test.md          # /test command
└── deploy.md        # /deploy command

ファイル形式：

---
name: command-name
description: Command description
---

Command implementation instructions...

使用方法：コマンドは Claude Code のネイティブなスラッシュコマンドとして統合されます

エージェント

場所：agents/ ディレクトリ 形式：YAML フロントマター付きの Markdown ファイル 自動検出：agents/ 内のすべての .md ファイルが自動的に読み込まれます

構成例：

agents/
├── code-reviewer.md
├── test-generator.md
└── refactorer.md

ファイル形式：

---
description: Agent role and expertise
capabilities:
  - Specific task 1
  - Specific task 2
---

Detailed agent instructions and knowledge...

使用方法：ユーザーはエージェントを手動で呼び出せます。また、Claude Code がタスクのコンテキストに基づいて自動的に選択することもできます

スキル

場所：スキルごとのサブディレクトリを含む skills/ ディレクトリ 形式：各スキルを専用のディレクトリに配置し、SKILL.md ファイルを含めます 自動検出：スキルのサブディレクトリ内にあるすべての SKILL.md ファイルが自動的に読み込まれます

構成例：

skills/
├── api-testing/
│   ├── SKILL.md
│   ├── scripts/
│   │   └── test-runner.py
│   └── references/
│       └── api-spec.md
└── database-migrations/
    ├── SKILL.md
    └── examples/
        └── migration-template.sql

SKILL.md の形式：

---
name: Skill Name
description: When to use this skill
version: 1.0.0
---

Skill instructions and guidance...

補助ファイル：スキルのサブディレクトリには、スクリプト、リファレンス、例、アセットを含めることができます

使用方法：説明とタスクのコンテキストが一致すると、Claude Code がスキルを自律的に有効化します

フック

場所：hooks/hooks.json または plugin.json 内 形式：イベントハンドラーを定義する JSON 設定 登録：プラグインを有効にすると、フックが自動的に登録されます

構成例：

hooks/
├── hooks.json           # Hook configuration
└── scripts/
    ├── validate.sh      # Hook script
    └── check-style.sh   # Hook script

設定形式：

{
  "PreToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh",
      "timeout": 30
    }]
  }]
}

利用可能なイベント：PreToolUse、PostToolUse、Stop、SubagentStop、SessionStart、SessionEnd、UserPromptSubmit、PreCompact、Notification

使用方法：Claude Code のイベントに応じて、フックが自動的に実行されます

MCP サーバー

場所：プラグインのルートにある .mcp.json、または plugin.json 内 形式：MCP サーバーの定義に使用する JSON 設定 自動起動：プラグインを有効にすると、サーバーが自動的に起動します

形式の例：

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

使用方法：MCP サーバーは Claude Code のツールシステムとシームレスに連携します

ポータブルなパス参照

${CLAUDE_PLUGIN_ROOT}

プラグイン内のすべてのパス参照には、環境変数 ${CLAUDE_PLUGIN_ROOT} を使用します。

{
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"
}

重要な理由：プラグインのインストール先は、次の要因によって異なります。

• ユーザーのインストール方法（マーケットプレイス、ローカル、npm）
• オペレーティングシステムの慣習
• ユーザーの設定

使用する場所：

• フックのコマンドパス
• MCP サーバーのコマンド引数
• スクリプトの実行参照
• リソースファイルのパス

使用しないもの：

• ハードコードされた絶対パス（/Users/name/plugins/...）
• 作業ディレクトリからの相対パス（コマンド内の ./scripts/...）
• ホームディレクトリのショートカット（~/plugins/...）

パス解決ルール

マニフェストの JSON フィールド内（フック、MCP サーバー）：

"command": "${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh"

コンポーネントファイル内（コマンド、エージェント、スキル）：

Reference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py

実行されるスクリプト内：

#!/bin/bash
# ${CLAUDE_PLUGIN_ROOT} available as environment variable
source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"

ファイル命名規則

コンポーネントファイル

コマンド：ケバブケースの .md ファイルを使用します

• code-review.md → /code-review
• run-tests.md → /run-tests
• api-docs.md → /api-docs

エージェント：役割が分かるケバブケースの .md ファイルを使用します

• test-generator.md
• code-reviewer.md
• performance-analyzer.md

スキル：ケバブケースのディレクトリ名を使用します

• api-testing/
• database-migrations/
• error-handling/

補助ファイル

スクリプト：適切な拡張子を付けた、内容が分かるケバブケースの名前を使用します

• validate-input.sh
• generate-report.py
• process-data.js

ドキュメント：ケバブケースの Markdown ファイルを使用します

• api-reference.md
• migration-guide.md
• best-practices.md

設定：標準的な名前を使用します

• hooks.json
• .mcp.json
• plugin.json

自動検出の仕組み

Claude Code はコンポーネントを自動的に検出して読み込みます。

1. プラグインマニフェスト：プラグインが有効になると .claude-plugin/plugin.json を読み込みます
2. コマンド：commands/ ディレクトリ内の .md ファイルをスキャンします
3. エージェント：agents/ ディレクトリ内の .md ファイルをスキャンします
4. スキル：SKILL.md を含むサブディレクトリを skills/ 内でスキャンします
5. フック：hooks/hooks.json またはマニフェストから設定を読み込みます
6. MCP サーバー：.mcp.json またはマニフェストから設定を読み込みます

検出のタイミング：

• プラグインのインストール時：コンポーネントが Claude Code に登録されます
• プラグインの有効化時：コンポーネントが使用可能になります
• 再起動は不要：変更は次回の Claude Code セッションで反映されます

上書きの動作：plugin.json 内のカスタムパスは、デフォルトのディレクトリを置き換えるのではなく、補足します

ベストプラクティス

構成

1. 論理的なグループ化：関連するコンポーネントをまとめます

   • テスト関連のコマンド、エージェント、スキルをまとめます
   • 目的ごとに scripts/ 内にサブディレクトリを作成します

2. 最小限のマニフェスト：plugin.json は簡潔に保ちます

   • 必要な場合にのみカスタムパスを指定します
   • 標準的な構成では自動検出を利用します
   • インライン設定はシンプルなケースにのみ使用します

3. ドキュメント：README ファイルを含めます

   • プラグインのルート：全体的な目的と使い方
   • コンポーネントのディレクトリ：個別のガイダンス
   • スクリプトのディレクトリ：使い方と要件

命名

1. 一貫性：コンポーネント間で命名を統一します

   • コマンドが test-runner の場合、関連するエージェントには test-runner-agent という名前を付けます
   • スキルのディレクトリ名は、その目的に合わせます

2. 明確さ：目的が分かる説明的な名前を使用します

   • 良い例：api-integration-testing/、code-quality-checker.md
   • 避ける例：utils/、misc.md、temp.sh

3. 長さ：簡潔さと明確さのバランスを取ります

   • コマンド：2～3 語（review-pr、run-ci）
   • エージェント：役割を明確に示します（code-reviewer、test-generator）
   • スキル：トピックを中心にします（error-handling、api-design）

ポータビリティ

1. 必ず ${CLAUDE_PLUGIN_ROOT} を使用する：パスをハードコードしないでください
2. 複数のシステムでテストする：macOS、Linux、Windows で検証します
3. 依存関係を文書化する：必要なツールとバージョンを記載します
4. システム固有の機能を避ける：ポータブルな bash/Python の構文を使用します

メンテナンス

1. バージョンを一貫して管理する：リリース時に plugin.json のバージョンを更新します
2. 段階的に非推奨にする：削除する前に、古いコンポーネントを明確に示します
3. 破壊的変更を文書化する：既存ユーザーに影響する変更を記載します
4. 十分にテストする：変更後にすべてのコンポーネントが動作することを確認します

よくあるパターン

最小限のプラグイン

依存関係のない単一のコマンド：

my-plugin/
├── .claude-plugin/
│   └── plugin.json    # Just name field
└── commands/
    └── hello.md       # Single command

フル機能のプラグイン

すべての種類のコンポーネントを備えた完全なプラグイン：

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/          # User-facing commands
├── agents/            # Specialized subagents
├── skills/            # Auto-activating skills
├── hooks/             # Event handlers
│   ├── hooks.json
│   └── scripts/
├── .mcp.json          # External integrations
└── scripts/           # Shared utilities

スキルに特化したプラグイン

スキルのみを提供するプラグイン：

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── skill-one/
    │   └── SKILL.md
    └── skill-two/
        └── SKILL.md

トラブルシューティング

コンポーネントが読み込まれない：

• ファイルが正しいディレクトリにあり、拡張子も正しいことを確認します
• YAML フロントマターの構文を確認します（コマンド、エージェント、スキル）
• スキルに SKILL.md があることを確認します（README.md やその他の名前ではありません）
• Claude Code の設定でプラグインが有効になっていることを確認します

パス解決エラー：

• すべてのハードコードされたパスを ${CLAUDE_PLUGIN_ROOT} に置き換えます
• パスが相対パスで、マニフェスト内で ./ から始まっていることを確認します
• 参照先のファイルが指定されたパスに存在することを確認します
• フックスクリプトで echo $CLAUDE_PLUGIN_ROOT を実行してテストします

自動検出が機能しない：

• ディレクトリがプラグインのルートにあることを確認します（.claude-plugin/ 内ではありません）
• ファイル名が規則に従っていることを確認します（ケバブケース、正しい拡張子）
• マニフェスト内のカスタムパスが正しいことを確認します
• プラグイン設定を再読み込みするため、Claude Code を再起動します

プラグイン間の競合：

• 一意でわかりやすいコンポーネント名を使用します
• 必要に応じて、コマンド名にプラグイン名を含めます
• プラグインの README に競合の可能性を記載します
• 関連する機能にはコマンドのプレフィックスを検討します

---

詳しい例や高度なパターンについては、references/ および examples/ ディレクトリ内のファイルを参照してください。