create-agent

エージェント作成

構造の整った Claude Code エージェントを生成します。YAML フロントマターを含む Markdown ファイルで、複雑な複数ステップの作業を、コンテキストウィンドウを分離した自律型サブプロセスに委任します。

生成する前に、エージェントとスキルの違いを把握してください。

• エージェントは分離されたコンテキストで実行され、二人称のシステムプロンプト（「あなたは……です」）を使用し、簡潔な > 折りたたみスカラー形式の説明（50～70 トークン、<example> ブロックなし）を記述し、Agent ツールを通じて起動されます。
• スキルは現在の会話にインラインで挿入され、Claude が実行する命令形の本文指示を使用し、トリガーフレーズに対する説明のマッチングを通じて呼び出されます。

フェーズ 0：要件の把握

$ARGUMENTS を解析して手掛かりを得ます。次の情報を集めます。

アイデンティティ：

1. 分野と目的 — このエージェントはどのような問題を解決しますか？
2. 専門家としてのペルソナ — どのような専門家として振る舞うべきですか？

起動条件： 3. トリガー条件 — Claude はいつこのエージェントに処理を委任すべきですか？どのようなユーザーメッセージで起動しますか？ 4. プロアクティブかリアクティブか — イベント発生後（例：コードの記述後）に自動実行すべきですか？それとも明示的なリクエストがある場合のみ実行しますか？

機能： 5. ツールへのアクセス — 実際に必要なツールは何ですか？最小権限の原則に従います。分析エージェントに Write は必要ありません。 6. メモリ — このエージェントはセッションをまたいで学習すべきですか？（例：コードベースのパターン、繰り返し発生する問題、アーキテクチャ上の決定を蓄積する。）必要な場合はスコープを選択します。project（推奨のデフォルト。VCS 経由で共有可能）、user（プロジェクト間でグローバルに共有）、local（プロジェクト固有で、VCS には含まれない）。 7. MCP サーバー — 親セッションにない外部ツール（ブラウザー、データベース、API）が必要ですか？

実行： 8. セッションモード — Claude が委任するサブエージェントとして実行しますか？それともメインセッションのエージェント（claude --agent <name>）として実行しますか？セッションエージェントには、より広いツールへのアクセスと、より自己完結したプロンプトが必要です。また、起動を開始するために initialPrompt を使用する場合があります。 9. バックグラウンド実行 — ユーザーが作業を続ける間、並行して実行すべきですか？バックグラウンドエージェントは、事前承認されていない権限を自動的に拒否し、確認の質問をすることができません。 10. コンテキストの分離 — 大量の出力を生成したり、ファイルを変更したりしますか？ワークツリーで実行すべきですか（isolation: worktree）？ 11. 作業量 — 深い推論（high／max）が必要ですか？それとも高速な分類タスク（low）ですか？

$ARGUMENTS が空、または情報が不足している場合は、AskUserQuestion を使用して、作業を進める前に分野、トリガー条件、プロアクティブな実行意図を確認します。これらが確定したら、フェーズ 1 に進みます。

フェーズ 1：生成

全体を通じて、システムプロンプトの本文では二人称を使用し、外延的な推論より内包的な推論を優先し、フロントマターは必要最小限にします。

ステップ 1 — 識別子を選ぶ

命名規則（validate_agent.py で検証されます）：

• 3～50 文字で、小文字、数字、ハイフンのみを使用します
• 英数字で始まり、英数字で終わる必要があります
• 汎用的な語句は避けます：helper、assistant、agent

適切な例：code-reviewer、test-generator、api-docs-writer 不適切な例：ag（短すぎる）、-start（先頭がハイフン）、my_agent（アンダースコア）

Step 2 — フロントマターを記述する

${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md を読み、フィールドの一覧、色の意味、モデルの選択肢、ツール選択のフレームワーク、実行モディファイアの詳細を確認してください。

必須: name、description 必ず設定: model: inherit（特定のモデル機能が必要な場合を除く）、color（UI 上の視覚的な識別子）

tools の設定ルール: エージェントは自律的に動作するため、必要最小限に制限してください。過剰な権限を与えると、人間が介入して検出することができません。分析には ["Read", "Grep", "Glob"] を指定します。生成には Write を追加します。Bash はシェルの実行が不可欠な場合に限り、デフォルトでは追加しないでください。サブエージェントをオーケストレーションするセッションモードのエージェントでは、起動できるエージェントを限定するために Agent(type1, type2) を使用してください。

該当する場合は Phase 0 に基づいて設定:

• memory — セッションをまたぐ学習が必要と判断した場合。本文にメモリのメンテナンス手順を追加します
• effort — タスクにデフォルト以外の思考の深さが必要な場合
• initialPrompt — 自動的に開始するセッションエージェントの場合
• background: true — 並行実行が必要と判断した場合
• mcpServers — 外部ツールが必要と判断した場合

Step 3 — 説明を記述する

説明フィールドは毎回のセッションでコンテキストに読み込まれます。トークン予算を意識し、適切に振り分けるために必要な最小限の内容にしてください。

> の折りたたみスカラーを使い、以下を含めます。

• 「次のトリガー条件に該当する場合に、このエージェントを使用してください。」
• 該当する場合は積極的な利用を促すヒント（例: 「次の後に積極的に使用することを推奨します……」）
• 対象範囲の境界（例: 「X には使用せず、Y-agent を使用してください。」）
• 目標: 50～70 トークン。<example> ブロックは振り分けの精度を高めず、コンテキストを浪費するため含めないでください。

Step 4 — システムプロンプトを記述する

マークダウン本文（--- の後）がエージェントのシステムプロンプトになります。エージェントに直接語りかける二人称で、全文を記述してください。これはスキルとの重要な執筆上の違いです。エージェントにはペルソナとプロセスが必要であり、Claude が従うための指示ではありません。

標準的な構成:

You are [role] specializing in [domain].

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

**Process:**
1. [Step — imperative]
2. [Next step]

**Quality Standards:**
- [Standard]

**Output Format:**
[Structure and content of what to return]

**Edge Cases:**
- [Situation]: [How to handle]

システムプロンプトの設定ルール:

• 最初にペルソナを定義します。専門家としてのアイデンティティが以降のすべての判断に影響するため、最初の文で確立してください
• プロセスの手順によって、複雑なタスクでの場当たり的な対応を防ぎます。各手順を明確な判断の境界として示してください
• 出力形式は必須です。呼び出し元が結果を予測可能な構造で処理できる必要があります
• システムプロンプトでエッジケースを定義してください。実行時に判明するエラーは、再試行のコストにつながります

memory を設定する場合: エージェントがナレッジベースを維持するためのセクションを含めます。 「コードパス、パターン、重要なアーキテクチャ上の決定を見つけたら、エージェントのメモリを更新してください。作業を開始する前に、メモリを参照してください。」これにより、セッションをまたいだ学習が可能になります。

3,000 語以内にしてください。詳細なドメインリファレンスはシステムプロンプトに直接埋め込まず、skills: フロントマターフィールドで事前読み込みする references/ に配置してください。

積極的なトリガーパターンを示す完全な実用例については、${CLAUDE_PLUGIN_ROOT}/skills/create-agent/examples/proactive-code-reviewer.md を参照してください。

Step 5 — スクリプト化の可能性を確認する

${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/script-patterns.md を読み、エージェントのシステムプロンプトの各手順に、次の5つのシグナルパターンを適用してください。

シグナル	質問	該当する場合 →
繰り返し生成	いずれかの手順で、呼び出しごとに同じ構造を生成しますか？	scripts/ にパラメーター化したスクリプトを作成
ツール選択が不明確	いずれかの手順で、壊れやすい順序でツールを組み合わせていますか？	手順をスクリプト化
厳密な契約	この手順の --help テキストを今すぐ書けますか？	CLI の候補
二重用途の可能性	ユーザーがこの手順を単独でターミナルから実行しますか？	適切な CLI として設計
一貫性が重要	同じ入力に対して、常に同一の出力を生成する必要がありますか？	スクリプト化 — LLM による生成は決して使用しない

ステップ 6 — 委任先を確認する

確定する前に、既存のエージェントとスキルを確認します。

Glob: .claude/agents/*.md, ~/.claude/agents/*.md (project + global agents)
Glob: .claude/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md (project + global skills)

• この分野を担当する既存のエージェントはありますか？ そのエージェントを拡張するか、新しいエージェントのスコープを絞ります
• ドメイン知識を補うため、skills: フロントマターを使って事前に読み込むスキルやリファレンスファイルはありますか？
• このエージェントがサブタスクを委任すべきコマンドや MCP はありますか？

常に完全修飾名を使用してください。

• Agent: subagent_type=plugin-dev:agent-creator（「agent-creator」だけではなく）
• Skill: claude-skills:create-skill（「create-skill」だけではなく）

ステップ 7 — 検証する

新しいエージェントファイルを作成する場合：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/validate_agent.py <agent-file> --output json

終了コード 0 = フェーズ 2 に進みます。終了コード 1 = errors 配列を解析します。各エントリには field、message、severity があります。ディスクに書き込む前に、すべての critical および major 項目を解決してください。

フェーズ 2：作成する

出力先

スコープ	場所
ユーザーエージェント（グローバル）	~/.claude/agents/<name>.md
プロジェクトエージェント	.claude/agents/<name>.md
プラグインエージェント	<plugin-root>/agents/<name>.md

agents/ 内のエージェントは自動検出されるため、登録は不要です。プラグインエージェントには、自動的に plugin-name:agent-name という名前空間が付与されます。

エージェントファイルを初期化する（任意のひな形）

ゼロから作成する場合：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/init_agent.py <name> --path <agents-dir>

終了コード 0 = プレースホルダー付きでファイルが作成されます。内容の入力に進みます。 終了コード 1 = 名前が競合しています。ユーザーに名前の変更を依頼するか、上書きを確認してください。

選択内容を説明する

生成したエージェントを、簡潔な理由とともに提示します。

• 設定した内容とその理由 — 「このエージェントは複数ファイルにまたがる複雑な推論を行うため、model: sonnet に設定しました」
• 除外した内容とその理由 — 「Git の状態管理が不要なため、isolation は設定していません」
• 選択したツールとその理由 — 各ツールについて明確に理由を説明します。理由のないツールアクセスは設計上の問題です

書き込みと確認

書き込む前に：

Writing to: [path]
This will [create new / overwrite existing] file.
Proceed?

作成後

以下を要約します。

• 名前とファイルパス
• 起動する条件（主なトリガー条件）
• 付与したツールとその理由
• 推奨するテストシナリオ

フェーズ 3 に進みます。

フェーズ 3：評価する

評価項目	基準
明確さ（0～10）	システムプロンプトに曖昧さがなく、目的とペルソナが明確
トリガーの精度（0～10）	説明と例が、意図したトリガー範囲をカバーし、それを超えていない
効率性（0～10）	システムプロンプトのトークン効率 — 1 トークンあたりのガイダンスを最大化
完全性（0～10）	ドメイン要件をカバーし、出力形式を定義し、エッジケースに対応している
安全性（0～10）	ツールが必要最小限に制限され、無制限の権限付与がない

目標：9.0/10.0。 下回る場合は、最も弱い評価項目に対処して一度だけ改善し、その後に提示します。

スコアが 9.0 以上になるか、1 回の改善を実施した時点で、フェーズ 3 は完了です。エージェントのファイルパス、主なトリガー条件、付与したツールとその理由を提示します。

検証チェックリスト

構成：

• ファイルは agents/ ディレクトリ内の <name>.md である
• name と description を含む有効な YAML フロントマターがある
• Markdown 本文があり、内容が十分にある

説明の品質：

• 「Use this agent when...」で始まる
• 簡潔な > スカラーで、50～70 トークン。<example> ブロックは含めない
• 対象範囲の境界（対象外の用途）を網羅している
• エージェントがイベント後に起動すべき場合は、先回りして起動するヒントが含まれている

システムプロンプトの品質：

• 二人称で書かれている（「You are...」「You will...」）
• 最初の文に、ペルソナ／役割を明確に示す記述がある
• プロセスの手順が番号付きで、命令形になっている
• 出力形式が定義されている
• エッジケースに対処している
• 3,000 語未満で、ドメインの詳細は references/ に委ねている

フロントマター：

• 特定のモデルが必要な場合を除き、model: inherit を設定している
• 意味に沿った color を設定している
• tools を必要最小限に制限している
• セッションをまたいだ学習が必要な場合は memory を設定し、本文にメンテナンス手順を記載している
• デフォルト以外の思考深度が必要な場合は effort を設定している
• セッションモードのエージェントが自動起動する場合は initialPrompt を設定している
• 並行実行が必要な場合は background: true を設定している
• マージ前にレビューが必要なファイルをエージェントが変更する場合は isolation: worktree を設定している
• TODO のプレースホルダーが残っていない

エラー処理

問題	対応
ドメインが不明確	「このエージェントにとって成功とはどのような状態ですか？」と尋ねる
対象範囲が広すぎる	起動条件が重複しない、対象を絞ったエージェントに 2～3 分割する
既存のエージェントと競合する	重複を指摘し、起動条件の範囲を絞るか既存のエージェントを拡張する
起動条件が曖昧	このエージェントを起動すべき具体的なユーザーメッセージを 3 つ尋ねる