plugin-best-practices

プラグインの検証とベストプラクティス

Claude Code プラグインをアーキテクチャ標準に照らして検証します。このファイルはナビゲーションガイドです。詳細は references/ にあります。

クイックスタート

プラグインを検証します。

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py <plugin-path>

特定のチェックだけを実行する場合：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py <plugin-path> --check=manifest,frontmatter

コンポーネントの選択ガイド

コンポーネント	使用する場面	主な要件
指示型スキル	ユーザーが呼び出すワークフロー、直線的なプロセス	命令形、フェーズベース、commands で宣言すること；use-<action> の接頭辞を付けて命名する（例：use-kicad-cli）
ナレッジ型スキル	エージェント向けの参照知識	宣言形、トピックベース、skills で宣言すること；using-<topic> の接頭辞を付けて命名する（例：using-git-worktrees）
エージェント	独立した専門的な意思決定	使用ツールの制限、2〜4 個の <example> ブロック、分離されたコンテキスト
MCP サーバー	外部ツール／データの統合	stdio/http/sse トランスポート、${CLAUDE_PLUGIN_ROOT} パス
LSP サーバー	IDE 機能（定義へ移動）	言語サーバーのバイナリ、拡張機能のマッピング
フック	イベント駆動型の自動化	ライフサイクルイベント、command/http/mcp_tool/prompt/agent タイプ
モニター	長時間稼働する監視機能（ログ、デプロイ）	各エントリに name+command+description が必要；v2.1.105+
テーマ	同梱されたカラープリセット	name、base、overrides を含む JSON
出力スタイル	応答の書式を調整	name と description を含む Markdown のフロントマター

選択基準の詳細については ./references/component-model.md を、実装ガイドについては ./references/components/ を参照してください。

段階的な情報開示

3 段階のトークン構造により、コンテキストを効率よく使用できます。

レベル	内容	トークン予算	読み込み
1	メタデータ（名前＋説明）	約 100 トークン	常時（起動時）
2	SKILL.md の本文	5k トークン未満	スキルの起動時
3	References/ ファイル	実質無制限	bash によるオンデマンド

実装パターン：

• SKILL.md：概要と参照ファイルへのナビゲーション
• References/：詳細な仕様、例、パターン
• Scripts/：実行可能なユーティリティ（実行するまでコンテキストコストは発生しません）

トークン予算の完全なガイドラインについては ./references/component-model.md を参照してください。

検証ワークフロー

5 つの連続したチェックで、プラグインの品質をあらゆる面から確認します。

1. 構造：ファイルのパターン、ディレクトリ構成、ケバブケースの命名
2. マニフェスト：plugin.json の必須フィールドとスキーマへの準拠
3. フロントマター：コンポーネント内の YAML フロントマター、三人称の説明
4. ツール呼び出し：アンチパターンの検出（暗黙的なツール呼び出しと明示的なツール呼び出しの違い）
5. トークン予算：段階的な情報開示への準拠（SKILL.md は 5k トークン未満）

検証時に -v フラグを指定すると、合格したチェックもすべて表示する詳細な出力を確認できます。

完全な基準については ./references/validation-checklist.md を参照してください。

要件レベル（RFC 2119）

プラグインのドキュメントでは、RFC 2119 の要件レベルを使用します。

• MUST / MUST NOT：絶対的な要件または禁止事項
• SHOULD / SHOULD NOT：既知の例外がある推奨事項
• MAY：完全に任意の事項

RFC 2119 の仕様全体については ./references/rfc-2119.md を参照してください。

重要なパターン

ツール呼び出しのルール

ツール	形式	例
Read、Write、Edit、Glob、Grep	暗黙的	「条件に一致するファイルを検索する」
Bash	暗黙的	「git statusを実行する」
Task	暗黙的	「plugin-name:agent-nameエージェントを起動する」
Skill	明示的	「Skillツールを使用して、plugin-name:skill-nameスキルを読み込む」
TaskCreate	明示的	「進捗を追跡するためにTaskCreateツールを使用する」
AskUserQuestion	明示的	「[アクション]するためにAskUserQuestionツールを使用する」
MCPツール	暗黙的	「データベースに問い合わせてユーザーレコードを取得する」

修飾名：プラグインのコンポーネントには、必ずplugin-name:component-name形式を使用してください。

allowed-tools：単独のBashは絶対に使用せず、必ずBash(git:*)のようなフィルターを使用してください。

インラインBash：動的なコンテキストには、感嘆符＋バッククォート＋コマンド＋バッククォートのインライン構文を使用してください。

MCPツールの呼び出し：意図は自然言語で記述してください。Claudeが適切なMCPツールを自動的に特定します。スキルの内容でmcp__server__toolのような正確なMCPツール名を指定しないでください。

完全なパターンとアンチパターンについては、./references/tool-invocations.mdを参照してください。 MCP固有の呼び出しパターンについては、./references/mcp-patterns.mdを参照してください。

スキルのフロントマター（公式のベストプラクティス）

必須フィールド：

• name：最大64文字。小文字、数字、ハイフンのみ使用できます。種類ごとの命名規則：指示型スキルにはuse-<action>接頭辞（例：use-kicad-cli）を使用し、知識型スキルにはusing-<topic>接頭辞（例：using-git-worktrees）を使用してください。
• description：最大1024文字。具体的なトリガーフレーズを含む三人称の文体を必ず使用してください。

説明のベストプラクティス：

要件	説明
人称	三人称のみ（「このスキルは、次の場合に使用します……」）
構成	[機能の説明]。次の状況、[シナリオ1]、[シナリオ2]、または[ユーザーのフレーズ]の場合に使用します。
目的	スキルの検出 — Claudeはこれを使って100以上のスキルから選択します
トリガーフレーズ	「プラグインを検証する」「フロントマターを確認する」など、具体的なユーザーフレーズを含めます

追加フィールドもサポートされていますが、段階的な情報開示との整合性に影響します。

フロントマターの完全な仕様については、./references/components/skills.mdを参照してください。

エージェントのフロントマター

必須フィールド（上流仕様に準拠）：

• name：3～50文字、ケバブケース
• description：トリガー条件と2～4個の<example>ブロック

任意のフィールド：model、color、effort、maxTurns、tools、disallowedTools、skills、memory、background、isolation（"worktree"のみ有効）。

プラグインエージェントで禁止されているフィールド（セキュリティ）：hooks、mcpServers、permissionMode。

フィールドの順序：name → description（トリガー条件と<example>ブロックを含む|ブロックスカラー）→ その他のYAMLフィールド → 終了の---。descriptionの外にある単独の<example>ブロックは、YAMLの解析エラーを引き起こします。

CO-STARフレームワークを含む、エージェント設計ガイドラインの詳細については、./references/components/agents.mdを参照してください。

タスク管理

3つ以上の個別のステップ、複数ファイルにわたる作業、または順次依存する作業では、TaskCreateを使用します。単一ファイルの編集と1～2ステップの操作には必要ありません。

主な要件：

• 名前は二つの形式を使用します：subject（「テストを実行する」）とactiveForm（「テストを実行中」）
• 開始前にin_progressに設定し、完了後にcompletedに設定します
• 完全に完了した場合にのみcompletedに設定します

パターンと例の詳細については、./references/task-management.mdを参照してください。

MCPサーバーの設定

MCPサーバーは、プラグインのルートにある.mcp.json、またはplugin.json内のmcpServersにインラインで設定します。サポートされるトランスポートタイプは3種類です。stdio（ローカルのCLIツール）、http（リモートAPI。最も広くサポートされています）、sse（リアルタイムストリーミング）です。

シークレットをハードコードしないでください。必ず${ENV_VAR}構文を使用してください。

MCP統合パターンの詳細については、./references/mcp-patterns.mdを参照してください。 コンポーネントの設定詳細については、./references/components/mcp-servers.mdを参照してください。

フックの設定

フックイベントはセッションのライフサイクル全体をカバーします（PreToolUse、PostToolUse、PostToolUseFailure、PostToolBatch、PermissionRequest、PermissionDenied、UserPromptSubmit、UserPromptExpansion、Setup、Notification、Stop／StopFailure、SubagentStart／SubagentStop、TaskCreated／TaskCompleted、TeammateIdle、InstructionsLoaded、ConfigChange、CwdChanged、FileChanged、WorktreeCreate／WorktreeRemove、PreCompact／PostCompact、Elicitation／ElicitationResult、SessionStart／SessionEndなど、28以上のイベント）。フックの種類は5つです：command、http、mcp_tool、prompt、agent。

イベントの一覧表と、AI ネイティブな構造化出力のパターンについては、./references/components/hooks.mdを参照してください。

エージェントチームとサブエージェント

サブエージェントは分離された一方向のサブプロセスで、呼び出し元に結果を返します。エージェントチームは、タスクリストを共有し、エージェント同士が直接やり取りする複数の独立したセッションです。並列調査、複数モジュールにまたがる機能、競合する仮説の検討に適しています。

	サブエージェント	エージェントチーム
コンテキスト	呼び出し元に返されます	完全に独立しています
コミュニケーション	メインエージェントとのみ	エージェント同士が直接
トークンコスト	低い（要約されます）	高い（完全なインスタンスです）

エージェントチームは実験的な機能です。export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1で有効にしてください。

詳しいガイドについては./references/agent-teams.mdを、並列調整パターンについては./references/parallel-execution.mdを参照してください。

ディレクトリ構成

標準レイアウト：

plugin-name/
├── .claude-plugin/plugin.json    # Manifest (declare components here)
├── skills/                       # Agent Skills (RECOMMENDED)
│   └── skill-name/
│       ├── SKILL.md
│       └── references/
├── commands/                     # Skills as flat .md files (legacy)
├── agents/                       # Subagent definitions
├── output-styles/                # Output style markdown
├── themes/                       # Color theme JSON
├── monitors/monitors.json        # Background monitor configs
├── hooks/hooks.json              # Hook configuration
├── bin/                          # Executables added to Bash PATH
├── settings.json                 # Plugin default settings
├── .mcp.json                     # MCP server definitions
├── .lsp.json                     # LSP server configurations
└── scripts/                      # Executable scripts

重要なルール：

• コンポーネントはプラグインのルートに配置します。.claude-plugin/内には配置しません
• スクリプトにはシバンを付け、実行可能にする必要があります
• スクリプトではパスに${CLAUDE_PLUGIN_ROOT}を使用する必要があります
• すべてのパスは相対パスで、./から始める必要があります

レイアウトの詳しいガイドラインについては、./references/directory-structure.mdを参照してください。

リファレンスディレクトリ

検証と品質

• ./references/validation-checklist.md - 品質チェックリストの全項目
• ./references/rfc-2119.md - 要件レベル（MUST／SHOULD／MAY）

コンポーネントの実装

• ./references/component-model.md - コンポーネントの種類、選定基準、トークン予算
• ./references/components/skills.md - スキルの構造、フロントマター、段階的な情報開示
• ./references/components/agents.md - エージェントの設計、CO-STAR フレームワーク、使用禁止フィールド
• ./references/components/commands.md - コマンドのフロントマター、動的コンテキスト
• ./references/components/hooks.md - フックイベント、種類、AI ネイティブなパターン、テンプレート
• ./references/components/mcp-servers.md - MCP の設定、stdio／http／sse
• ./references/components/lsp-servers.md - LSP のセットアップ、バイナリ要件
• ./references/components/monitors.md - バックグラウンドモニターの設定
• ./references/components/themes.md - カラーテーマの JSON 構造
• ./references/components/output-styles.md - 出力スタイルのフロントマター

設定と統合

• ./references/directory-structure.md - プラグインのレイアウト、命名規則
• ./references/manifest-schema.md - plugin.json のスキーマ、必須フィールド
• ./references/mcp-patterns.md - MCP のトランスポートの種類、セキュリティのベストプラクティス

開発パターン

• ./references/tool-invocations.md - ツールの使用パターンとアンチパターン
• ./references/tool-design-philosophy.md - Claude の強みを活かすツールを設計するための原則
• ./references/task-management.md - TaskCreate のパターン、2種類の形式での命名
• ./references/cli-commands.md - プラグイン管理用の CLI コマンド

高度なトピック

• ./references/agent-teams.md - 並列化可能なタスク、複数の視点からの分析
• ./references/parallel-execution.md - エージェントの並列調整パターン
• ./references/debugging.md - よくある問題、エラーメッセージ、トラブルシューティング