agent-identifier

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

概要

エージェントは、複雑な複数ステップのタスクを独立して処理する自律型のサブプロセスです。エージェントの構造、起動条件、システムプロンプトの設計を理解すると、強力な自律機能を作成できます。

主な概念：

• エージェントは自律的な作業に使用し、コマンドはユーザーが開始するアクションに使用します
• YAML フロントマターを含む Markdown ファイル形式です
• description フィールドの例によって起動します
• システムプロンプトでエージェントの動作を定義します
• モデルと色をカスタマイズできます

使用する場合

ユーザーから次の依頼があった場合に、このスキルを使用します。

• エージェントを作成する
• エージェントを追加する
• サブエージェントを記述する
• エージェントのフロントマターを定義する
• description の例を使用するタイミングを判断する
• エージェントのツール、色、またはモデルの動作を設定する
• 自律型エージェントの構造、起動条件、またはシステムプロンプトを設計する

使用しない場合

次の場合は、このスキルを使用しないでください。

• スラッシュコマンドの設計
• フックの設定
• MCP サーバーのセットアップ
• plugin-structure が対象とする、一般的なプラグインの構成に関する質問

エージェントのファイル構造

完全な形式

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:

<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>

<example>
[Additional example...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]

フロントマターのフィールド

name（必須）

名前空間の指定と呼び出しに使用するエージェント識別子です。

形式： 小文字、数字、ハイフンのみ 長さ： 3～50 文字 パターン： 英数字で始まり、英数字で終わる必要があります

良い例：

• code-reviewer
• test-generator
• api-docs-writer
• security-analyzer

悪い例：

• helper（汎用的すぎます）
• -agent-（ハイフンで始まり、ハイフンで終わっています）
• my_agent（アンダースコアは使用できません）
• ag（短すぎます。3 文字未満です）

description（必須）

Claude がこのエージェントを起動するタイミングを定義します。最も重要なフィールドです。

必須項目：

1. 起動条件（「次の場合にこのエージェントを使用します……」）
2. 使用例を示す複数の <example> ブロック
3. 各例に含めるコンテキスト、ユーザーの依頼、アシスタントの応答
4. エージェントが起動する理由を説明する <commentary>

形式：

Use this agent when [conditions]. Examples:

<example>
Context: [Scenario description]
user: "[What user says]"
assistant: "[How Claude should respond]"
<commentary>
[Why this agent is appropriate]
</commentary>
</example>

[More examples...]

ベストプラクティス：

• 具体的な例を 2～4 件含めます
• 先回りした起動と、依頼に応じた起動の両方を示します
• 同じ意図を異なる表現で示します
• commentary で理由を説明します
• エージェントを使用しない場合を明確にします

model（必須）

エージェントが使用するモデルです。

選択肢：

• inherit - 親と同じモデルを使用します（推奨）
• sonnet - Claude Sonnet（バランス型）
• opus - Claude Opus（最も高性能、高コスト）
• haiku - Claude Haiku（高速、低コスト）

推奨： 特定のモデル機能が必要なエージェントを除き、inherit を使用してください。

color（必須）

UI でエージェントを識別するための色です。

選択肢： blue、cyan、green、yellow、magenta、red

ガイドライン：

• 同じプラグイン内のエージェントには、異なる色を選びます
• 同じ種類のエージェントには、一貫した色を使用します
• Blue/cyan：分析、レビュー
• Green：成功を重視するタスク
• Yellow：注意、検証
• Red：重要、セキュリティ
• Magenta：クリエイティブ、生成

tools（任意）

エージェントが使用できるツールを制限します。

形式： ツール名の配列

tools: ["Read", "Write", "Grep", "Bash"]

デフォルト： 省略した場合、エージェントはすべてのツールを使用できます

ベストプラクティス： 必要最小限のツールに制限します（最小権限の原則）

一般的なツールセット：

• 読み取り専用の分析：["Read", "Grep", "Glob"]
• コード生成：["Read", "Write", "Grep"]
• テスト：["Read", "Bash", "Grep"]
• フルアクセス：フィールドを省略するか、["*"] を使用します

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

Markdown 本文がエージェントのシステムプロンプトになります。二人称で、エージェントに直接語りかけるように記述します。

構成

標準テンプレート：

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

ベストプラクティス

✅ 推奨事項：

• 二人称で記述します（「あなたは……です」「あなたは……します」）
• 責任範囲を具体的にします
• 手順を段階的に示します
• 出力形式を定義します
• 品質基準を含めます
• 例外的な状況にも対応します
• 10,000 文字未満に収めます

❌ 避けること：

• 一人称で記述すること（「私は……です」「私は……します」）
• 曖昧または汎用的な表現
• 手順を省くこと
• 出力形式を定義しないこと
• 品質に関する指針を省くこと
• エラーケースを無視すること

エージェントの作成

方法 1：AI 支援による生成

Claude Code から抽出した、次のプロンプトパターンを使用します。

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"

Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
   - Clear behavioral boundaries
   - Specific methodologies
   - Edge case handling
   - Output format
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3 <example> blocks showing when to use

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Examples: <example>...</example>",
  "systemPrompt": "You are..."
}

次に、フロントマターを付けてエージェントファイル形式に変換します。

完全なテンプレートについては、examples/agent-creation-prompt.md を参照してください。

方法 2：手動で作成

1. エージェント識別子を選びます（3～50 文字、小文字、ハイフン）
2. 例を含めて説明を記述します
3. モデルを選択します（通常は inherit）
4. 視覚的に識別できる色を選びます
5. ツールを定義します（アクセスを制限する場合）
6. 上記の構成に沿ってシステムプロンプトを記述します
7. agents/agent-name.md として保存します

検証ルール

識別子の検証

✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)

ルール：

• 3～50 文字
• 小文字、数字、ハイフンのみ
• 英数字で始まり、英数字で終わる必要があります
• アンダースコア、スペース、特殊文字は使用できません

説明の検証

長さ： 10～5,000 文字
必須項目： 起動条件と例
推奨： 2～4 個の例を含む 200～1,000 文字

システムプロンプトの検証

長さ： 20～10,000 文字
推奨： 500～3,000 文字
構成： 責任、プロセス、出力形式が明確であること

エージェントの整理

プラグインのエージェントディレクトリ

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

agents/ 内のすべての .md ファイルが自動的に検出されます。

名前空間

エージェントには自動的に名前空間が付与されます。

• 単一のプラグイン：agent-name
• サブディレクトリがある場合：plugin:subdir:agent-name

エージェントのテスト

起動のテスト

エージェントが正しく起動することを確認するため、テストシナリオを作成します。

1. 具体的な起動例を含むエージェントを作成します
2. テストでは、例にあるものと似た表現を使用します
3. Claude がエージェントを読み込むことを確認します
4. エージェントが期待する機能を提供することを確認します

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

システムプロンプトが完全であることを確認します。

1. エージェントに一般的なタスクを与えます
2. プロセスの手順に従うことを確認します
3. 出力形式が正しいことを確認します
4. プロンプトに記載されたエッジケースをテストします
5. 品質基準を満たしていることを確認します

クイックリファレンス

最小限のエージェント

---
name: simple-agent
description: Use this agent when... Examples: <example>...</example>
model: inherit
color: blue
---

You are an agent that [does X].

Process:
1. [Step 1]
2. [Step 2]

Output: [What to provide]

フロントマターフィールドの概要

フィールド	必須	形式	例
name	はい	小文字とハイフン	code-reviewer
description	はい	テキスト＋例	次の場合に使用します… …
model	はい	inherit/sonnet/opus/haiku	inherit
color	はい	色名	blue
tools	いいえ	ツール名の配列	["Read", "Grep"]

ベストプラクティス

推奨事項：

• ✅ 説明に具体的な例を 2～4 個含めます
• ✅ 起動条件を具体的に記述します
• ✅ 特別な必要がない限り、モデルには inherit を使用します
• ✅ 適切なツールを選択します（最小権限の原則）
• ✅ 明確で構造化されたシステムプロンプトを記述します
• ✅ エージェントの起動を十分にテストします

避けるべきこと：

• ❌ 例のない一般的な説明を使用する
• ❌ 起動条件を省略する
• ❌ すべてのエージェントに同じ色を指定する
• ❌ 不要なツールアクセスを許可する
• ❌ 曖昧なシステムプロンプトを記述する
• ❌ テストを省略する

追加リソース

リファレンスファイル

詳細なガイダンスについては、以下を参照してください。

• references/system-prompt-design.md - システムプロンプトの完全なパターン
• references/triggering-examples.md - 例の形式とベストプラクティス
• references/agent-creation-system-prompt.md - Claude Code の正確なプロンプト

サンプルファイル

examples/ にある動作するサンプル：

• agent-creation-prompt.md - AI 支援によるエージェント生成テンプレート
• complete-agent-examples.md - さまざまな用途に対応する完全なエージェントの例

ユーティリティスクリプト

script/ の開発ツール：

• validate-agent.sh - エージェントファイルの構造を検証します
• test-agent-trigger.sh - エージェントが正しく起動するかテストします

実装ワークフロー

プラグイン用のエージェントを作成するには：

1. エージェントの目的と起動条件を定義します
2. 作成方法（AI による支援または手動）を選択します
3. agents/agent-name.md ファイルを作成します
4. 必須フィールドをすべて含めてフロントマターを記述します
5. ベストプラクティスに従ってシステムプロンプトを記述します
6. 説明に起動例を2～4件含めます
7. scripts/validate-agent.sh で検証します
8. 実際のシナリオで起動をテストします
9. プラグインの README にエージェントを記載します

自律的な動作を実現するため、明確な起動条件と包括的なシステムプロンプトを重視してください。