SamuelChien/mega-skills-collection

Claude Codeプラグインのためのエージェント開発

概要

エージェントは、複雑でマルチステップなタスクを自律的に処理するサブプロセスです。エージェントの構造、トリガー条件、システムプロンプトの設計を理解することで、強力な自律機能を作成できます。

主要な概念:

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

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

完全なフォーマット

---
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. トリガー条件 (「Use this agent when...」)
2. 使用例を示す複数の <example> ブロック
3. 各例におけるContext、user request、assistant response
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

ガイドライン:

• 同じプラグイン内の異なるエージェントには異なる色を選択する
• 類似したエージェントタイプには一貫した色を使用する
• 青/シアン: 分析、レビュー
• 緑: 成功指向のタスク
• 黄: 注意、検証
• 赤: クリティカル、セキュリティ
• マゼンタ: クリエイティブ、生成

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]

ベストプラクティス

✅ 推奨事項:

• 二人称で記述する (「You are...」、「You will...」)
• 責任について具体的に記述する
• ステップバイステップのプロセスを提供する
• 出力フォーマットを定義する
• 品質基準を含める
• エッジケースに対処する
• 10,000文字未満に抑える

❌ 避けるべきこと:

• 一人称で記述する (「I am...」、「I will...」)
• 曖昧または汎用的にする
• プロセスステップを省略する
• 出力フォーマットを未定義のままにする
• 品質ガイダンスをスキップする
• エラーケースを無視する

エージェントの作成

方法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. 例を含むdescriptionを記述する
3. モデルを選択する (通常は inherit)
4. 視覚的識別のための色を選択する
5. ツールを定義する (アクセスを制限する場合)
6. 上記の構造でシステムプロンプトを記述する
7. agents/agent-name.md として保存する

バリデーションルール

識別子のバリデーション

✅ 有効: code-reviewer, test-gen, api-analyzer-v2
❌ 無効: ag (短すぎる), -start (ハイフンで開始), my_agent (アンダースコア)

ルール:

• 3〜50文字
• 小文字、数字、ハイフンのみ
• 英数字で開始および終了する必要がある
• アンダースコア、スペース、特殊文字は不可

descriptionのバリデーション

長さ: 10〜5,000文字 必須項目: トリガー条件と例 最適: 200〜1,000文字、2〜4つの例

システムプロンプトのバリデーション

長さ: 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	はい	テキスト + 例	Use when... ...
model	はい	inherit/sonnet/opus/haiku	inherit
color	はい	色名	blue
tools	いいえ	ツール名の配列	["Read", "Grep"]

ベストプラクティス

推奨事項:

• ✅ descriptionに2〜4つの具体的な例を含める
• ✅ 具体的なトリガー条件を記述する
• ✅ 特別な必要性がない限り、modelには inherit を使用する
• ✅ 適切なツールを選択する (最小権限)
• ✅ 明確で構造化されたシステムプロンプトを記述する
• ✅ エージェントのトリガーを徹底的にテストする

避けるべきこと:

• ❌ 例のない汎用的なdescriptionを使用する
• ❌ トリガー条件を省略する
• ❌ すべてのエージェントに同じ色を設定する
• ❌ 不要なツールアクセスを許可する
• ❌ あいまいなシステムプロンプトを記述する
• ❌ テストをスキップする

追加リソース

リファレンスファイル

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

• 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 - さまざまなユースケース向けの完全なエージェント例

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

scripts/ にある開発ツール:

• validate-agent.sh - エージェントファイル構造のバリデーション
• test-agent-trigger.sh - エージェントが正しくトリガーされるかテスト

実装ワークフロー

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

1. エージェントの目的とトリガー条件を定義する
2. 作成方法を選択する (AIアシストまたは手動)
3. agents/agent-name.md ファイルを作成する
4. 必要なすべてのフィールドを含むフロントマターを記述する
5. ベストプラクティスに従ってシステムプロンプトを記述する
6. descriptionに2〜4つのトリガー例を含める
7. scripts/validate-agent.sh でバリデーションする
8. 実際のシナリオでトリガーをテストする
9. プラグインのREADMEにエージェントを文書化する

自律動作のための明確なトリガー条件と包括的なシステムプロンプトに焦点を当ててください。