plugin-master

プラグイン開発ガイド

クイックリファレンス

コンポーネント	場所	必須
プラグインマニフェスト	.claude-plugin/plugin.json	はい
コマンド	commands/*.md	いいえ（自動検出）
エージェント	agents/*.md	いいえ（自動検出）
スキル	skills/*/SKILL.md	いいえ（自動検出）
フック	hooks/hooks.json	いいえ
MCP サーバー	.mcp.json	いいえ

タスク	操作
プラグインを作成	「X 用のプラグインを作成して」と依頼
プラグインを検証	/validate-plugin を実行
マーケットプレイスからインストール	/plugin marketplace add user/repo を実行してから /plugin install name@user を実行

重要なルール

ディレクトリ構造

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # MUST be inside .claude-plugin/
├── agents/
│   └── domain-expert.md
├── commands/
├── skills/
│   └── skill-name/
│       ├── SKILL.md
│       ├── references/
│       └── examples/
└── README.md

Plugin.json スキーマ

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Complete [domain] expertise. PROACTIVELY activate for: (1) ...",
  "author": {
    "name": "Author Name",
    "email": "[email protected]"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

検証ルール:

• author は必ずオブジェクト { "name": "..." } にしてください。文字列は不可です
• version は必ず文字列 "1.0.0" にしてください。数値は不可です
• keywords は必ず配列 ["word1", "word2"] にしてください。文字列は不可です
• agents、skills、slashCommands は含めないでください。これらは自動検出されます

YAML フロントマター（必須）

agents/、commands/、skills/ 内のすべての Markdown ファイルは、必ずフロントマターで始めてください。

---
description: Brief description of what this component does
---

# Content...

フロントマターがない場合、コンポーネントは読み込まれません。

プラグイン設計の方針（2025）

エージェント優先設計

• 主要インターフェース: {domain}-expert という名前の専門エージェントを1つ
• 最小限のコマンド: 自動化ワークフロー用に0～2個のみ
• 理由: ユーザーが求めているのは、コマンドメニューではなく、対話形式でのやり取りです

命名基準:

• docker-master → docker-expert という名前のエージェント
• terraform-master → terraform-expert という名前のエージェント

スキルの段階的な情報開示

スキルは3段階で読み込まれます。

1. フロントマター - トリガーに備えて起動時に読み込まれます
2. SKILL.md の本文 - スキルが有効になったときに読み込まれます
3. references/ - 特定の詳細が必要な場合にのみ読み込まれます

これにより、コンテキストを肥大化させずに、容量を制限なく拡張できます。

プラグインの作成

ステップ 1: リポジトリのコンテキストを確認する

ファイルを作成する前に、次を確認します。

# Check if in marketplace repo
if [[ -f .claude-plugin/marketplace.json ]]; then
    PLUGIN_DIR="plugins/PLUGIN_NAME"
else
    PLUGIN_DIR="PLUGIN_NAME"
fi

# Get author from git config
AUTHOR_NAME=$(git config user.name)
AUTHOR_EMAIL=$(git config user.email)

ステップ 2: 構造を作成する

mkdir -p $PLUGIN_DIR/.claude-plugin
mkdir -p $PLUGIN_DIR/agents
mkdir -p $PLUGIN_DIR/skills/domain-knowledge

ステップ 3: ファイルを作成する

1. plugin.json - メタデータを含むマニフェスト
2. agents/domain-expert.md - 主要な専門エージェント
3. skills/domain-knowledge/SKILL.md - 中核となるナレッジ
4. README.md - ドキュメント

ステップ 4（条件付き）: 帰属表示マニフェスト

プラグインに、同梱、派生、またはライセンス対象となるサードパーティのコンテンツが含まれる場合は、マーケットプレイスに登録する前に、プラグインのルートに NOTICES.md を作成してください。これはドキュメントの仕上げではなく、plugin.json や README.md と並ぶ、出荷に不可欠な成果物として扱ってください。構造の整合性、ライセンステキストの保持、相互参照の要件については、references/publishing-guide.md の「ライセンス対象／同梱／派生コンテンツ」チェックリストを参照してください。

プラグインにサードパーティのコンテンツが含まれない場合は、このステップを省略してください。

ステップ 5: マーケットプレイスに登録する

重要: リポジトリのルートに .claude-plugin/marketplace.json が存在する場合は、必ずプラグインを追加してください。

{
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "Same as plugin.json description",
      "version": "1.0.0",
      "author": { "name": "Author" },
      "keywords": ["same", "as", "plugin.json"]
    }
  ]
}

コンポーネントの種類

コマンド

commands/*.md にある、ユーザーが開始するスラッシュコマンド:

---
description: What this command does
---

# Command Name

Instructions for Claude to execute...

エージェント

agents/*.md にある、自律型サブエージェント:

---
name: agent-name
description: |
  Brief role summary. PROACTIVELY activate for: (1) trigger, (2) trigger, ..., (N) trigger. Provides: capability list.

  # Optional. Include 3-5 <example> blocks ONLY when the agent body
  # exceeds 2,500 words. Lean orchestrators omit them by design.
  # See agent-development "Example-block requirement by agent body size".
model: inherit
color: blue
---

System prompt for agent...

スキル

skills/skill-name/SKILL.md にある、動的なナレッジ:

---
name: skill-name
description: When to use this skill...
---

# Skill content with progressive disclosure...

フック

hooks/hooks.json にある、イベントの自動化:

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

イベント: PreToolUse、PostToolUse、SessionStart、SessionEnd、UserPromptSubmit、PreCompact、Notification、Stop、SubagentStop

ベストプラクティス

命名規則

• プラグイン: kebab-case（例: code-review-helper）
• コマンド: 動詞ベース（例: review-pr、run-tests）
• エージェント: 役割ベース（例: code-reviewer、test-generator）
• スキル: トピックベース（例: api-design、error-handling）

移植性

内部パスにはすべて ${CLAUDE_PLUGIN_ROOT} を使用してください。

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

絶対パスをハードコードしないでください。

プラットフォームに関する注意

• Windows: GitHub マーケットプレイスからインストールしてください（ローカルパスでは失敗する場合があります）
• Git Bash/MinGW: $MSYSTEM で検出し、GitHub 方式を使用してください
• Mac/Linux: すべてのインストール方法を利用できます

トラブルシューティング

問題	解決方法
プラグインが読み込まれない	plugin.json が .claude-plugin/ にあることを確認してください
コマンドが見つからない	フロントマターに description フィールドがあることを確認してください
エージェントが起動しない	説明に PROACTIVELY activate for: の列挙があることを確認してください。エージェントの本文が 2,500 語を超える場合に限り、<example> ブロックを 3～5 個追加してください。詳しくは agent-development SKILL.md の「エージェント本文のサイズに応じた Example ブロックの要件」を参照してください。簡潔なオーケストレーターは対象外です。
マーケットプレイスが見つからない	リポジトリが公開されていることを確認し、marketplace.json のパスを確認してください

追加リソース

詳しくは、以下を参照してください。

• references/manifest-reference.md - plugin.json の全フィールド
• references/component-patterns.md - 高度なコンポーネントのパターン
• references/publishing-guide.md - マーケットプレイスへの公開に関する詳細
• examples/minimal-plugin.md - 最小限の動作するプラグイン
• examples/full-plugin.md - すべての機能を備えた完全なプラグイン