create-agent

エージェントコマンドの作成

複雑な複数ステップのタスクを自律的に処理する Claude Code エージェントを作成します。このコマンドでは、Anthropic の公式ドキュメントと実績のあるパターンに基づく包括的なガイダンスを提供します。

ユーザー入力

Agent Name: $1
Description: $2

エージェントとは？

エージェントは、Task ツールを介して起動される自律型サブプロセスです。次のことができます。

• 複雑な複数ステップのタスクを自律的に処理する
• 独立したコンテキストウィンドウを持つ
• 結果を親会話に返す
• 特定の領域に特化できる

概念	エージェント	コマンド
起動方法	説明に基づいて Claude が判断	ユーザーが /name で呼び出す
目的	自律的な作業	ユーザーが開始するアクション
コンテキスト	分離されたサブプロセス	共有された会話
ファイル形式	agents/*.md	commands/*.md

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

エージェントでは、YAML フロントマターとMarkdown のシステムプロンプトを組み合わせた独自の形式を使用します。

---
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	helper	汎用的すぎる
test-generator	-agent-	ハイフンで始まり、ハイフンで終わる
api-docs-writer	my_agent	アンダースコアは使用不可
security-analyzer	ag	短すぎる（3 文字未満）
pr-quality-reviewer	MyAgent	大文字は使用不可

description（必須、重要）

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

要件：

• 長さ：10～5,000 文字（推奨：2～4 個の例を含む 200～1,000 文字）
• 必ず「Use this agent when...」で始めること
• 使用パターンを示す <example> ブロックを必ず含めること
• 各例には、コンテキスト、ユーザーリクエスト、アシスタントの応答、コメントを含めること

例のブロック形式：

<example>
Context: [Describe the situation - what led to this interaction]
user: "[Exact user message or request]"
assistant: "[How Claude should respond before triggering]"
<commentary>
[Explanation of why this agent should be triggered in this scenario]
</commentary>
assistant: "[How Claude triggers the agent - 'I'll use the [agent-name] agent...']"
</example>

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

• 具体例を 2～4 個含める
• 先回りして起動するケースと、要求に応じて起動するケースの両方を示す
• 同じ意図を異なる言い回しで表現する
• コメントで理由を説明する
• エージェントを使用しないケースを具体的に示す

model（必須）

値：inherit、sonnet、opus、haiku デフォルト：inherit（推奨）

値	用途	コスト
inherit	親会話のモデルを使用	デフォルト
haiku	高速で単純なタスク	最低
sonnet	バランスの取れた性能	中程度
opus	最大限の能力、複雑な推論	最高

推奨：上書きする具体的な理由がない限り、inherit を使用してください。

color（必須）

目的：UI でエージェントを見分けるための視覚的な識別表示

値：blue、cyan、green、yellow、magenta、red

ベストプラクティス：同じプラグイン内の各エージェントには異なる色を設定し、視覚的に区別できるようにします。

任意フィールド

tools（任意）

目的：利用可能なツールを制限する（最小権限の原則） 形式：ツール名の配列 デフォルト：すべてのツールが利用可能

# Common tool restrictions
tools: ["Read", "Grep", "Glob"]           # Read-only analysis
tools: ["Read", "Write", "Grep", "Glob"]  # Code modification
tools: ["Read", "Bash", "Grep"]           # System operations

セキュリティの原則：エージェントに必要なツールだけを許可してください。

起動パターン

パターン 1：明示的なリクエスト

ユーザーがエージェントの機能を直接依頼します。

<example>
Context: User wants code reviewed
user: "Can you review my code changes?"
assistant: "I'll use the code-reviewer agent to analyze the changes."
<commentary>
User explicitly requested code review, trigger the code-reviewer agent.
</commentary>
</example>

パターン 2：暗黙のニーズ

明示的な依頼はなく、コンテキストに基づいてエージェントが必要とされます。

<example>
Context: User mentions code is hard to understand
user: "This code is confusing and hard to follow"
assistant: "I can help improve the code clarity."
<commentary>
User indicates complexity issues. Trigger code-simplifier agent to refactor
for better readability.
</commentary>
assistant: "I'll use the code-simplifier agent to suggest improvements."
</example>

パターン 3：先回りした起動

関連する作業を完了した後、明示的な依頼がなくてもエージェントが起動します。

<example>
Context: User just implemented database queries
user: "I've added the user search functionality"
assistant: "Great! Let me review it for security."
<commentary>
Database code written. Proactively trigger security-analyzer to check
for SQL injection and other database security issues.
</commentary>
assistant: "I'll use the security-analyzer agent to check the database code."
</example>

パターン 4：ツール使用パターン

以前のツール使用状況に基づいてエージェントが起動します。

<example>
Context: User made multiple edits to test files
user: "I've updated all the tests"
assistant: "Great! Let me verify test quality."
<commentary>
Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer
to ensure tests follow best practices.
</commentary>
assistant: "I'll use the test-quality-analyzer agent to review the tests."
</example>

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

システムプロンプト（フロントマターの後に続く Markdown 本文）でエージェントの動作を定義します。実績のある次のテンプレートを使用してください。

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility - what the agent MUST do]
2. [Secondary responsibility]
3. [Additional responsibilities...]

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

**Quality Standards:**
- [Standard 1 - measurable criteria]
- [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]

**What NOT to Do:**
- [Anti-pattern 1]
- [Anti-pattern 2]

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

原則	良い例	悪い例
具体的にする	「クエリ文字列にSQLインジェクションがないか確認する」	「セキュリティ上の問題を探す」
例を含める	「形式：## Critical Issues\n- Issue 1」	「適切な形式を使う」
境界を定義する	「ファイルは変更せず、分析のみ行うこと」	境界が明示されていない
フォールバックを用意する	「不明な場合は、明確化を求める」	推測して進める
品質を確保する仕組み	「各指摘を証拠で検証する」	検証しない

検証要件

システムプロンプトは、次の要件を満たす必要があります。

• 長さ：20～10,000文字（理想：500～3,000文字）
• 適切な構成：責任、プロセス、出力形式を明確なセクションに分ける
• 具体性：曖昧な指針ではなく、実行可能な指示にする
• 完全性：エッジケースと品質基準に対応する

AI 支援によるエージェント生成

このプロンプトを使って、エージェント設定を自動生成します。

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..."
}

優れたエージェントを設計するプロセス

エージェントを作成するときは、次の6段階のプロセスに従います。

1. 中核となる意図を抽出する：基本的な目的、主な責任、成功基準を特定します
2. 専門家のペルソナを設計する：専門分野の知識を備えた魅力的な専門家像を作成します
3. 包括的な指示を設計する：行動上の境界、方法論、エッジケース、出力形式を定めます
4. パフォーマンスを最適化する：意思決定フレームワーク、品質管理、ワークフローパターン、フォールバック戦略を定めます
5. 識別子を作成する：簡潔で説明的な、ハイフンでつないだ2～4語の識別子にします
6. 例を生成する：コンテキスト、ユーザーとアシスタントの対話、コメントを含む起動シナリオを作成します

エージェントのデフォルト基準

フロントマタールール

• description：1文に収めます。説明は親コンテキストに読み込まれるため、すべてのトークンが重要です
• 説明に冗長な<example>ブロックを追加しないでください。コンテキストのトークンを浪費します

必須のエージェントセクション（順番どおり）

1. タイトル - # <Role Title>と、明確なアイデンティティを示す文
2. アイデンティティ - 品質への期待と動機（作業の質が低い場合の影響）
3. 目標 - 1段落で明確に示す目的
4. 入力 - エージェントが受け取るファイルやデータ
5. 重要：コンテキストを読み込む - 分析前に、関連するすべてのファイルを読むことを明示的に必須とする
6. プロセス／段階 - 適切な順序で進める、段階ごとのワークフロー

プロセス段階の順序（複数段階のエージェントでは重要）

WRONG: Decompose → Self-Critique → Produce → Solve
RIGHT: Decompose → Solve → Produce Full Solution → Self-Critique → Output

• 自己批評は必ず最後のステップにします
• まずすべてを作成し、その後に評価して選択します

意思決定テーブル

推論の列を意思決定の列より前に配置します。

WRONG: | Section | Include? | Reasoning |
RIGHT: | Section | Reasoning | Include? |

これにより、意思決定の前に理由を説明することをエージェントに促し、意思決定の質が向上します。

検証ルール

構造の検証

要素	ルール	有効	無効
名前	3～50文字、小文字、ハイフン	code-reviewer	Code_Reviewer
説明	10～5000文字、「Use this agent when」で始まる	Use this agent when reviewing code...	Reviews code
モデル	inherit、sonnet、opus、haikuのいずれか	inherit	gpt-4
色	blue、cyan、green、yellow、magenta、redのいずれか	blue	purple
システムプロンプト	20～10000文字	500文字以上のプロンプト	空の本文
例	<example>ブロックが1つ以上	例がある	例がない

検証スクリプト

# Validate agent structure
scripts/validate-agent.sh agents/your-agent.md

品質チェックリスト

デプロイ前に確認します。

• 名前が規則に従っている（小文字、ハイフン、3～50文字）
• 説明が「Use this agent when...」で始まっている
• 説明に<example>ブロックが2～4個含まれている
• 各例にコンテキスト、ユーザー、アシスタント、コメントが含まれている
• タスクの複雑さに適したモデルが選ばれている
• 関連するエージェント間で色が重複していない
• 必要なツールだけに制限されている（最小権限）
• システムプロンプトの構成が明確である
• 責任が具体的で実行可能である
• プロセスの手順が具体的である
• 出力形式が定義されている
• エッジケースに対応している

実運用の例

コード品質レビュアーエージェント

---
name: code-quality-reviewer
description: Use this agent when the user asks to review code changes, check code quality, or analyze modifications for bugs and improvements. Examples:

<example>
Context: User has completed implementing a feature
user: "I've finished the authentication module"
assistant: "Great! Let me review it for quality."
<commentary>
Code implementation complete. Proactively trigger code-quality-reviewer
to check for bugs, security issues, and best practices.
</commentary>
assistant: "I'll use the code-quality-reviewer agent to analyze the changes."
</example>

<example>
Context: User explicitly requests review
user: "Can you review PR #123 for code quality?"
assistant: "I'll use the code-quality-reviewer agent to analyze the PR."
<commentary>
PR review request triggers the code-quality-reviewer agent.
</commentary>
</example>

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

You are an expert code quality reviewer specializing in identifying bugs, security vulnerabilities, and improvement opportunities.

**Your Core Responsibilities:**
1. Analyze code changes for quality issues (readability, maintainability, performance)
2. Identify security vulnerabilities (injection, XSS, authentication issues)
3. Check adherence to project best practices and coding standards
4. Provide actionable, specific feedback with line numbers

**Review Process:**
1. **Initial scan**: Quick pass for obvious issues
2. **Deep analysis**: Line-by-line review of changed code
3. **Context evaluation**: Check impact on related code
4. **Best practices**: Compare against project and language standards
5. **Recommendations**: Prioritized list of improvements

**Output Format:**
For each file reviewed:

## Summary
[2-3 sentence overview]

## Critical Issues (must fix)
- [Issue with file:line reference and fix suggestion]

## Major Issues (should fix)
- [Issue with explanation]

## Minor Issues (nice to fix)
- [Suggestion]

## Positive Observations
- [What was done well]

## Overall Assessment
[Pass/Needs Work/Fail with reasoning]

**Quality Standards:**
- Every issue must have a specific location (file:line)
- Every issue must have a suggested fix
- Prioritize security over style issues
- Acknowledge good patterns, not just problems

テスト生成エージェント

---
name: test-generator
description: Use this agent when the user asks for test generation, needs test coverage, or has written new code requiring tests. Examples:

<example>
Context: User has written new functionality without tests
user: "I've implemented the payment processing module"
assistant: "Let me generate comprehensive tests for it."
<commentary>
New code written without tests. Trigger test-generator to create
unit tests, integration tests, and edge case coverage.
</commentary>
assistant: "I'll use the test-generator agent to create comprehensive tests."
</example>

<example>
Context: User explicitly requests tests
user: "Can you write tests for the utils folder?"
assistant: "I'll use the test-generator agent to create tests."
<commentary>
Explicit test generation request.
</commentary>
</example>

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

You are an expert test engineer specializing in creating comprehensive test suites.

**Your Core Responsibilities:**
1. Analyze code to understand behavior and dependencies
2. Generate unit tests for individual functions/methods
3. Create integration tests for module interactions
4. Design edge case and error condition tests
5. Follow project testing conventions and patterns

**Expertise Areas:**
- **Unit testing**: Individual function/method tests
- **Integration testing**: Module interaction tests
- **Edge cases**: Boundary conditions, error paths
- **Test organization**: Proper structure and naming
- **Mocking**: Appropriate use of mocks and stubs

**Process:**
1. Read target code and understand its behavior
2. Identify testable units and their dependencies
3. Design test cases covering:
   - Happy paths (expected behavior)
   - Edge cases (boundary conditions)
   - Error cases (invalid inputs, failures)
4. Generate tests following project patterns
5. Add comprehensive assertions

**Output Format:**
Complete test files with:
- Proper test suite structure (describe/it or test blocks)
- Setup/teardown if needed
- Descriptive test names explaining what's being tested
- Comprehensive assertions covering all behaviors
- Comments explaining complex test logic

**Quality Standards:**
- Each function should have at least 3 tests (happy, edge, error)
- Test names should describe the scenario being tested
- Mocks should be clearly documented
- No test interdependencies

エージェント作成プロセス

ステップ 1：要件を収集する

提供されていない場合は、ユーザーに確認します。

1. エージェント名：エージェントの名前は何にしますか？（kebab-case）
2. 目的：このエージェントはどのような問題を解決しますか？
3. 起動条件：Claude はどのようなときにこのエージェントを使用すべきですか？
4. 責任範囲：中心となるタスクは何ですか？
5. 必要なツール：読み取り専用ですか？ファイルを変更できますか？
6. モデル：最大限の能力が必要ですか（opus）、それともバランス重視ですか（sonnet/inherit）？

ステップ 2：エージェントファイルを作成する

# Create agents directory if needed
mkdir -p ${CLAUDE_PLUGIN_ROOT}/agents

# Create agent file
touch ${CLAUDE_PLUGIN_ROOT}/agents/<agent-name>.md

ステップ 3：フロントマターを記述する

次の内容を含むフロントマターを生成します。

• 一意で説明的な名前
• 起動条件と例を含む説明
• 適切なモデル設定
• 他と区別できる色
• 必要最小限のツール

ステップ 4：システムプロンプトを記述する

次のテンプレートに沿ってシステムプロンプトを作成します。

1. 専門分野を含む役割の説明
2. 中心となる責任（番号付きリスト）
3. 分析／作業プロセス（ステップごと）
4. 品質基準（測定可能な基準）
5. 出力形式（具体的な構成）
6. エッジケース（特別な状況への対処方法）

ステップ 5：検証する

検証を実行します。

scripts/validate-agent.sh agents/<agent-name>.md

確認項目：

• フロントマターが正しく解析される
• 必須フィールドがすべて含まれている
• 例が完全である
• システムプロンプトが包括的である

ステップ 6：起動条件をテストする

さまざまなシナリオでテストします。

1. 例に一致する明示的なリクエスト
2. エージェントが起動すべき暗黙のニーズ
3. エージェントが起動すべきでないシナリオ
4. エッジケースとバリエーション

ベストプラクティスのまとめ

推奨事項

• エージェントの説明には、具体的な例を 2～4 個含めます
• 具体的で曖昧さのない起動条件を記述します
• 特別な必要がない限り、モデル設定には「inherit」を使用します
• ツールには最小権限の原則を適用します
• 明確で構造化され、明示的な手順を含むシステムプロンプトを記述します
• デプロイ前にエージェントの起動条件を十分にテストします
• エージェントごとに異なる色を使用します
• 起動ロジックを説明するコメントを含めます

避けるべき事項

• 例を含まない一般的な説明
• 起動条件の省略
• 同じプラグイン内の複数のエージェントに同じ色を使うこと
• 不要なツールアクセスの許可
• 曖昧なシステムプロンプト
• テストフェーズの省略
• 名前にアンダースコアや大文字を使うこと
• エッジケースへの対処漏れ

ワークフローとの統合

エージェントはプラグインのワークフローに統合されます。

1. フェーズ 5：コンポーネントの実装では、agent-creator を使用してエージェントを生成します
2. 検証フェーズでは、validate-agent.sh スクリプトを使用します
3. テストフェーズでは、さまざまなシナリオで起動条件を確認します

包括的なプラグイン開発には、次を使用します。

• /plugin-dev:create-plugin：プラグインの完全なワークフロー
• このコマンド：個別のエージェントの作成／改善

エージェントを作成する

ユーザーの入力に基づいて、次を作成します。

1. ディレクトリー構造：${CLAUDE_PLUGIN_ROOT}/agents/
2. エージェントファイル：フロントマターとシステムプロンプトを含む完全な Markdown
3. 検証：検証スクリプトを実行
4. テストの提案：起動条件を確認するためのシナリオ

作成後、さまざまなシナリオでのエージェントの動作を確認するため、/customaize-agent:test-prompt コマンドでテストすることを提案します。