agent-development

Claude Code プラグイン向けエージェント開発

概要

エージェントは、自律的に動作するサブプロセスであり、複雑な複数ステップのタスクを個別に処理します。各エージェントは agents/ ディレクトリ内の Markdown ファイルで、YAML フロントマターで設定を定義し、Markdown の本文をシステムプロンプトとして使用します。

エージェントの標準フロントマターテンプレート（必須の形式）

新しいエージェントはすべて、このテンプレートに従う必要があります。この形式から逸脱すると、エージェントが起動しない原因の第1位になります。

---
name: my-agent                                    # REQUIRED: kebab-case, 3-50 chars, alphanumeric start/end
model: inherit                                    # REQUIRED: always `inherit` unless you have a hard reason
color: blue                                       # RECOMMENDED: one of blue/cyan/green/yellow/magenta/red
tools: Read, Write, Edit, Glob, Grep, Bash        # RECOMMENDED: minimal set; omit for full access
description: |
  One-sentence summary of what the agent does. PROACTIVELY activate for: (1) concrete trigger, (2) concrete trigger, ..., (N) concrete trigger. Provides: comma-separated capability nouns.

  <example>
  Context: Realistic situation where the agent should fire
  user: "A realistic user quote -- the kind of thing someone would actually type"
  assistant: "Short 1-2 sentence response. Mention loading a specific skill if relevant."
  <commentary>Triggers for specific-keyword-1, specific-keyword-2, specific-keyword-3</commentary>
  </example>

  <example>
  Context: Another realistic situation covering a different capability
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>

  <example>
  Context: A debugging / troubleshooting scenario
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>

  <example>
  Context: A "when to pick this vs. that" scenario
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>
---

You are [role] specializing in [domain]. [Lean orchestrator body -- see "Lean Orchestrator Pattern" below.]

フロントマターに関する厳格なルール

1. name: は必須です。 非推奨の agent: true フラグは使用しないでください。このパターンは旧式であり、名前がなく、確実に参照または振り分けできないエージェントになります。既存ファイルに agent: true がある場合は、name: <kebab-name-from-filename> に置き換えてください。
2. model: inherit は必須です。 エージェントに文書化された機能要件がない限り、モデルをハードコードしないでください。
3. description: には、列挙形式の PROACTIVELY activate for: (1)... (2)... (N)... パターンと、Provides: ... の機能一覧を必ず含めてください。 「X についての支援にはこのエージェントを使用してください」とだけ記載した説明では、確実に振り分けられません。
4. <example> ブロックは必須ではなく、条件付きです。 説明に <example> ブロックが必要かどうかは、エージェントの本文の語数によって異なります。詳しくは、以下の 「エージェント本文のサイズ別の例ブロック要件」 を参照してください。簡潔なオーケストレーターでは意図的に省略し、大規模なエージェントでは必要になります。すべてのエージェントに一律で例を必須にしないでください。
5. 説明が複数行にわたる場合、または <example> ブロックを含む場合は、description: |（YAML ブロックスカラー）を使用してください。 折りたたみスカラー（>）や暗黙的なフロースカラーでは、例が正しく保持されません。
6. 横断的な定型文（Windows のパス規則、ドキュメントに関する方針など）を YAML の description: ブロックに入れないでください。 このテキストは振り分けの判定に使われるため、多くのエージェントに共通する定型文が含まれると、判定のシグナルが損なわれます。代わりに、Markdown 本文内の ## Windows file path requirements など、内容が明確に分かるセクションに記載してください。

エージェント本文のサイズ別の例ブロック要件（統一ルール）

説明に必要な <example> ブロックの数は、エージェントの Markdown 本文の語数に応じて決まります。このルールにより、「常に例を 4～6 個追加する」と「簡潔なオーケストレーターには例は不要」という、以前の相反する推奨事項を、作成ガイダンス、標準チェックリスト、および scripts/validate_plugins.py で共通の階層表に統一します。

エージェント本文の語数	階層	例ブロックの要件
< 1,500 語	目標未満	任意
1,500-2,500 語	簡潔なオーケストレーター（目標範囲）	任意。意図的に省略されることも多い
2,500-3,000 語	目標超過	推奨（3～5 個）
> 3,000 語	過大	必須（3～5 個）、かつ分割が必須

バリデーターが「例の不足」を指摘するのは、本文が 2,500 語を超えた場合のみです（AGENT_EXAMPLES_THRESHOLD_WORDS）。このしきい値未満の簡潔なオーケストレーターは、例がなくても問題なく検証に合格します。例がないのは意図的なものです。

執筆時の要点： まず、簡潔なオーケストレーターと大規模なエージェントのどちらにするかを決めてください。簡潔なオーケストレーターの場合は、PROACTIVELY activate for: の列挙が振り分けを担うため、例は不要です。大規模なエージェントを簡潔なエージェントにリファクタリングする際は、例を削除することも正当な作業の一部です。監査時は、例ブロックの修正を推奨する前に本文の語数を数えてください。以下の「推奨前の意図確認」を参照してください。

廃止予定／不適切なパターンと移行方法

不適切なパターン	動作	修正方法
agent: true（name: なし）	エージェントの命名やルーティングが確実に行えません	name: <kebab-name> に置き換えます
<example> ブロックのない description:（エージェント本文が 2,500 語超）	例がないため、ルーティングが曖昧になる肥大化したエージェントです	<example> ブロックを 3～5 個追加するか、オーケストレーターとスキルに分割します（推奨）
「Use this agent for X」の説明文のみを含む description:	ルーティングが曖昧になり、トリガーも不十分です	PROACTIVELY activate for: (1)... の列挙形式に書き換えます
YAML の description: 内にある Windows 用定型文	ルーティングシグナルを汚します	本文内の ## Windows file path requirements に移動します
model: がない、または固定値（例：model: sonnet）	セッションモデルを継承できません	model: inherit に設定します
assistant: にコード全体を含む単一の <example> ブロック	マッチングの精度を下げ、説明文を肥大化させます	assistant の応答は 1～2 文にとどめ、コードはスキルに記載します

Frontmatter フィールドのリファレンス

各 frontmatter フィールド（name、description、model、color、tools）の詳細なルールは、references/frontmatter-fields-reference.md に記載されています。要点：

• name — kebab-case、3～50 文字、英数字で開始・終了すること。役割ベースの命名規則（code-reviewer、domain-expert）。
• description — 最も重要なフィールドです。PROACTIVELY activate for: (1)... (N)... の列挙と、Provides: ... の機能一覧を含める必要があります。<example> ブロックの要否は、上記の本文語数の段階別テーブルに従います。
• model — デフォルトは inherit です。文書化された機能上の理由がある場合にのみ変更します。
• color — blue／cyan（分析）、green（生成）、yellow（検証）、red（重大／セキュリティ）、magenta（創造／アーキテクチャ）。
• tools — 最小権限の原則に従います。一般的な値：Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Skill, Agent。MCP ツールは mcp__server__tool の形式です。

実際のエージェントを作成または監査する際は、references/frontmatter-fields-reference.md を読み込んでください。

システムプロンプトの設計

Markdown の本文がエージェントのシステムプロンプトになります。二人称（「You are...」「You will...」）で記述してください。必須セクション：Core Responsibilities、Process、Quality Standards、Output Format、Edge Cases。具体的に記述し、出力を明確に定義してください。一人称で書くこと、曖昧な表現、スキルに記載すべきドメイン知識を埋め込むことは避けてください。テンプレートと DO／DON'T の一覧は、references/design-principles-and-mistakes.md を参照してください。

スリムなオーケストレーターパターン（重要）

エージェントの本文は、ドメイン知識を詰め込んだ内容ではなく、スリムなオーケストレーターにしてください。詳細な知識はスキルに委ねます。

エージェント本文のサイズ制限

指標	目標	絶対上限
語数	1,500～2,500 語	3,000 語
文字数	約 10,000～15,000 文字	20,000 文字

エージェント本文に含める内容

セクション	必須	目的
役割の定義	はい	「あなたは [ドメイン] を専門とする [役割] です」
スキルの有効化ルール	はい	トピックとスキルの対応表
大まかなプロセス	はい	設計／ワークフローの手順
出力形式	はい	応答に含める内容
簡潔なサービス概要	任意	どのスキルを読み込むか判断するための、分野ごとの 2～3 文
エッジケース／トラブルシューティングのヒント	任意	簡易リファレンスのみ

エージェント本文に含めない内容

• 詳細なドメイン知識 — スキルに記載します
• CLI／API の完全なリファレンス — スキルの references/ に記載します
• 完全なコード例 — スキルの examples/ に記載します
• スキル内容の重複 — スキルに記載されている内容をエージェント本文で繰り返さないでください

アンチパターン：コンテンツの重複

エージェント本文とスキルの間でコンテンツを重複させてはいけません。 これは最もよくある間違いで、コンテキストが大幅に肥大化する原因になります。

悪い例： エージェント本文に「Plugin.json Schema」セクション全体が含まれ、plugin-master スキルにも同じ内容が含まれている。 良い例： エージェント本文では「plugin.json スキーマの詳細については、plugin-master:plugin-master を読み込んでください」と述べ、1文の概要だけを残す。

簡潔なオーケストレーターのテンプレート

You are [role] specializing in [domain].

## Skill Activation - CRITICAL
[Topic-to-skill mapping table -- this is the heart of the agent]

## Core Responsibilities
[2-5 bullet points on what this agent does]

## Process
[5-7 step workflow for handling user requests]

## Quality Standards
[Brief checklist -- 5-10 items]

## Output Format
[What to include in responses]

説明のサイズ制限

エージェントの説明は簡潔で効果的にしてください。

要素	ガイドライン
導入文	いつ起動するかを1～2文で説明
例のブロック	多様なシナリオを網羅する3～7個のブロック
説明全体	自然な長さに収める — 長さよりも、質の高い起動例を重視

エージェント設計の原則とよくある間違い

詳細な設計原則（エージェントファースト設計、単一責任、スキル統合、起動フレーズの重複防止）と「よくある間違い」の表全体は、references/design-principles-and-mistakes.md にあります。要点は次のとおりです。

• プラグインごとに1つの専門エージェントを用意し、{domain}-expert という名前を付けます。ユーザーはメニューを操作するのではなく、対話します。
• エージェントごとに単一の責任を持たせます。複数のトピックに対応する必要がある場合は、新しいエージェントではなくスキルにします。
• スキルの有効化に関する指示は、システムプロンプトに含めます。
• スキル間で起動フレーズが重複しないように監査し、スキル有効化テーブルで曖昧さを解消します。

検証チェックリスト

エージェントを確定する前に、次の項目を確認してください。

• 名前：3～50文字、小文字とハイフンを使用し、英数字で始まり、英数字で終わる
• 説明：PROACTIVELY activate for: の列挙と Provides: の機能リストを含む
• <example> ブロック：エージェント本文の語数に応じて必要な場合に限り含める（「エージェント本文のサイズ別の例ブロック要件」階層テーブルを参照）。2,500語未満の簡潔なオーケストレーターは対象外です。
• 例が含まれる場合： エージェントが処理を委任する各スキルについて、そのスキルに振り分けられる例が少なくとも1つある
• 起動フレーズの重複がない： 複数のスキルが曖昧なキーワードを主張していない。主張する場合は曖昧さを解消している
• モデル：inherit に設定（特別な必要がある場合を除く）
• 色：エージェントの機能に適している
• ツール：必要最小限に制限（またはフルアクセスにする場合は省略）
• システムプロンプト：二人称で、責任、定義されたプロセス、出力が明確
• フロントマター：必須フィールドをすべて含む有効な YAML
• ファイルの場所：agents/agent-name.md

テスト

1. 具体的な起動例を含めてエージェントを作成します
2. テストクエリでは、例と似た表現を使います
3. 該当するリクエストに対して Claude がエージェントを読み込むことを確認します
4. エージェントが定義されたプロセスに従うことをテストします
5. 出力が定義された形式と一致することを確認します
6. システムプロンプトで言及されているエッジケースをテストします

よくある間違い

表全体（曖昧な説明、モデルの上書き、ツールの過剰な付与、すべてのスキルに横断的な定型文を含めること、簡潔なオーケストレーターに例を再追加することなど）は、references/design-principles-and-mistakes.md にあります。

推奨前の意図確認（監査時の注意点）

既存のエージェントに修正を推奨する前に、特に削除済みのコンテンツを再追加する修正を提案する場合は、見かけ上の問題が過去の意図的な判断によるものではないことを確認してください。簡潔なオーケストレーターへのリファクタリングで例のブロックを削除するのは一般的かつ意図的な対応です。語数を確認せずに「エージェントに例がない」と指摘する後続監査は、矛盾する修正作業の誤検知を大量に生みます。

簡潔なルール： エージェントに関する指摘を列挙する前に、3つの質問による意図確認（サイズ階層、git log、バリデーターの出力）を実施します。3つすべてが「実際の問題」を示す場合にのみ、監査レポートに記載してください。

確認の全容、根拠、意図的に削除されたパターンの拡張リスト、作成時と監査時の違いについては、references/validation-and-audits.md を参照してください。

scripts/validate_plugins.py による検証

このリポジトリには、読み取り専用の品質ゲートとして scripts/validate_plugins.py が用意されています。このマーケットプレイスで「適切な」エージェントのフロントマターとみなされるものの唯一の基準です。バリデーターとこのスキルの内容が食い違う場合は、バリデーターを優先してください。

簡単な実行方法：

python scripts/validate_plugins.py                    # whole marketplace
python scripts/validate_plugins.py --plugin my-plugin # one plugin
python scripts/validate_plugins.py --strict           # warnings fail the build

ルールの完全な一覧（エージェントレベル、スキルレベル、プラグインレベル）と、既知のバリデーターの不足点は references/validation-and-audits.md に記載されています。