新しいエージェントを作成する

焦点を絞った目的、キュレートされたツール、割り当てられたスキル、エージェントテンプレートとレジストリ規則に従った完全なドキュメントを持つClaude Codeサブエージェントのペルソナを定義する。

使用タイミング

• まだカバーされていないドメインの新しい専門エージェントをライブラリに追加する場合
• 繰り返されるワークフローまたはプロンプトパターンを再利用可能なエージェントペルソナに変換する場合
• キュレートされたスキルと制約されたツールを持つドメイン固有のアシスタントを作成する場合
• 過度に広いエージェントを焦点を絞った単一責任エージェントに分割する場合
• マルチエージェントチームを構成する前に新しいチームメンバーを設計する場合

入力

• 必須: エージェント名（小文字ケバブケース、例: data-engineer）
• 必須: エージェントの主要目的の一行説明
• 必須: エージェントが解決する問題を説明する目的ステートメント
• 任意: モデルの選択（デフォルト: sonnet; 代替: opus、haiku）
• 任意: 優先度レベル（デフォルト: normal; 代替: high、low）
• 任意: skills/_registry.yml から割り当てるスキルのリスト
• 任意: エージェントが必要とするMCPサーバー（例: r-mcptools、hf-mcp-server）

手順

ステップ1: エージェントペルソナを設計する

エージェントに明確で焦点を絞ったアイデンティティを選ぶ:

• 名前: 小文字ケバブケース、役割の説明的なもの。名詞またはドメイン修飾子で始める: security-analyst、r-developer、tour-planner。helper や assistant などの一般的な名前を避ける。
• 目的: このエージェントが解決する特定の問題を説明する一段落。問う: 「このエージェントは既存のエージェントがカバーしていない何をするか?」
• コミュニケーションスタイル: ドメインを考慮する。技術的なエージェントは正確で引用が豊富であるべき。クリエイティブなエージェントはより探索的になれる。コンプライアンスエージェントは正式で監査指向であるべき。

進める前に、既存の53エージェントとの重複を確認する:

grep -i "description:" agents/_registry.yml | grep -i "<your-domain-keywords>"

期待結果： 既存のエージェントが同じニッチをカバーしていない。既存のエージェントが部分的に重複している場合、新しいエージェントを作成する代わりにそのエージェントを拡張することを検討する。

失敗時： 重大な重複を持つエージェントが存在する場合、そのエージェントのスキルリストを拡張するか、新しいエージェントのスコープを既存のエージェントと補完するように絞り込む。

ステップ2: ツールを選択する

エージェントが必要とする最小限のツールセットを選ぶ。最小権限の原則が適用される:

ツールセット	使用タイミング	エージェント例
[Read, Grep, Glob]	読み取り専用の分析、レビュー、監査	code-reviewer, security-analyst, auditor
[Read, Grep, Glob, WebFetch]	分析プラス外部検索	senior-researcher
[Read, Write, Edit, Bash, Grep, Glob]	完全な開発 — コードの作成/変更	r-developer, web-developer, devops-engineer
[Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch]	開発プラス外部調査	polymath, shapeshifter

コードのみを分析するエージェントには Bash を含めない。外部リソースを検索する必要が本当にある場合を除いて WebFetch や WebSearch を含めない。

期待結果： ツールリストにエージェントの主要なワークフローで実際に使用するツールのみが含まれている。

失敗時： エージェントの機能リストを確認する — 機能がツールを必要としない場合、そのツールを削除する。

ステップ3: モデルを選択する

タスクの複雑さに基づいてモデルを選択する:

• sonnet （デフォルト）: ほとんどのエージェント。推論と速度の良いバランス。開発、レビュー、分析、標準的なワークフローに使用。
• opus: 複雑な推論、マルチステップ計画、微妙な判断。シニアレベルのエージェント、アーキテクチャの決定、深いドメイン専門知識を必要とするタスクに使用。
• haiku: シンプルで高速な応答。単純な検索、フォーマット、またはテンプレート入力を行うエージェントに使用。

期待結果： モデルがエージェントの主要なユースケースの認知的要求に一致する。

失敗時： 疑わしい場合は sonnet を使用する。テストで推論品質が不十分であることが明らかになった場合のみ opus にアップグレードする。

ステップ4: スキルを割り当てる

スキルレジストリを参照し、エージェントのドメインに関連するスキルを選択する:

# ドメインのすべてのスキルを一覧表示する
grep -A3 "domain-name:" skills/_registry.yml

# キーワードでスキルを検索する
grep -i "keyword" skills/_registry.yml

フロントマターのスキルリストを構築する:

skills:
  - skill-id-one
  - skill-id-two
  - skill-id-three

重要: すべてのエージェントはレジストリレベルの default_skills フィールドからデフォルトスキル（meditate、heal）を自動的に継承する。これらをエージェントのフロントマターに一覧する必要はない。ただし、それがエージェントの方法論の核心である場合を除く（例: mystic エージェントは瞑想の促進が主な目的であるため meditate を一覧する）。

期待結果： スキルリストに skills/_registry.yml に存在する3〜15のスキルIDが含まれている。

失敗時： 各スキルIDが存在することを確認する: grep "id: skill-name" skills/_registry.yml。一致しないものは削除する。

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

テンプレートをコピーしてフロントマターを入力する:

cp agents/_template.md agents/<agent-name>.md

YAMLフロントマターを入力する:

---
name: agent-name
description: One to two sentences describing primary capability and domain
tools: [Read, Write, Edit, Bash, Grep, Glob]
model: sonnet
version: "1.0.0"
author: Philipp Thoss
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags: [domain, specialty, relevant-keywords]
priority: normal
max_context_tokens: 200000
skills:
  - assigned-skill-one
  - assigned-skill-two
# Note: All agents inherit default skills (meditate, heal) from the registry.
# Only list them here if they are core to this agent's methodology.
# mcp_servers: []  # Uncomment and populate if MCP servers are needed
---

期待結果： YAMLフロントマターがエラーなく解析される。必須フィールド（name、description、tools、model、version、author）がすべて存在する。

失敗時： YAML構文を検証する。一般的な問題: バージョン文字列のクォーテーション欠落、不正なインデント、ツールリストの閉じていない括弧。

ステップ6: 目的と機能を作成する

テンプレートのプレースホルダーセクションを置き換える:

目的: このエージェントが解決する特定の問題と提供する価値を説明する一段落。具体的にする — ドメイン、ワークフロー、結果を名前を挙げる。

機能: 太字のリードインを持つ箇条書きリスト。エージェントに多くの機能がある場合はカテゴリでグループ化する:

## Capabilities

- **Primary Capability**: What the agent does best
- **Secondary Capability**: Additional functionality
- **Tool Integration**: How it leverages its tools

利用可能なスキル: 割り当てた各スキルを簡単な説明で一覧する。スキルIDのまま（スラッシュコマンド名）を使用する:

## Available Skills

- `skill-id` - Brief description of what the skill does

期待結果： 目的が具体的で（「開発を助ける」ではない）、機能が具体的で検証可能で、スキルリストがフロントマターと一致する。

失敗時： 目的が曖昧に感じられる場合、「このエージェントに何を依頼するか?」と答える。その答えを目的として使用する。

ステップ7: 使用シナリオと例を作成する

エージェントのスポーンの仕方を示す2〜3の使用シナリオを提供する:

### Scenario 1: Primary Use Case
Brief description of the main scenario.

> "Use the agent-name agent to [specific task]."

### Scenario 2: Alternative Use Case
Description of another common use case.

> "Spawn the agent-name to [different task]."

ユーザーリクエストと期待されるエージェントの動作を示す1〜2の具体的な例を追加する:

### Example 1: Basic Usage
**User**: [Specific request]
**Agent**: [Expected response pattern and actions taken]

期待結果： シナリオが現実的で、例が実際の価値を示し、呼び出しパターンがClaude Codeの規則と一致する。

失敗時： 例を精神的にテストする — エージェントは割り当てられたツールとスキルでリクエストを実際に実行できるか?

ステップ8: 制限事項と「参照」を作成する

制限事項: 3〜5の正直な制約。エージェントができないこと、使用すべきでないこと、または貧しい結果を生む場所:

## Limitations

- Cannot execute code in language X (no runtime available)
- Not suitable for tasks requiring Y — use Z agent instead
- Requires MCP server ABC to be running for full functionality

参照: 補完的なエージェント、関連するガイド、関連するチームへのクロスリファレンス:

## See Also

- [complementary-agent](complementary-agent.md) - handles the X side of this workflow
- [relevant-guide](../guides/guide-name.md) - background knowledge for this domain
- [relevant-team](../teams/team-name.md) - team that includes this agent

期待結果： 制限事項が正直で具体的。「参照」が存在するファイルを参照している。

失敗時： 参照されているファイルが存在することを確認する: ls agents/complementary-agent.md。

ステップ9: レジストリに追加する

agents/_registry.yml を編集し、アルファベット順の位置に新しいエージェントエントリを追加する:

  - id: agent-name
    path: agents/agent-name.md
    description: Same one-line description from frontmatter
    tags: [domain, specialty]
    priority: normal
    tools: [Read, Write, Edit, Bash, Grep, Glob]
    skills:
      - skill-id-one
      - skill-id-two

ファイルの先頭の total_agents カウントをインクリメントする。

期待結果： レジストリエントリがエージェントファイルのフロントマターと一致する。total_agents が実際のエージェントエントリ数と等しい。

失敗時： grep -c "^ - id:" agents/_registry.yml でエントリをカウントし、total_agents と一致することを確認する。

ステップ10: 発見を確認する

Claude Codeは .claude/agents/ ディレクトリからエージェントを発見する。このリポジトリでは、そのディレクトリが agents/ へのシンリンクだ:

# シンリンクが存在し解決されることを確認する
ls -la .claude/agents/
readlink -f .claude/agents/<agent-name>.md

.claude/agents/ シンリンクが無傷であれば、追加のアクションは必要ない — 新しいエージェントファイルは自動的に発見可能だ。

READMEオートメーションを実行してエージェントREADMEを更新する:

npm run update-readmes

期待結果： .claude/agents/<agent-name>.md が新しいエージェントファイルに解決される。agents/README.md に新しいエージェントが含まれている。

失敗時： シンリンクが壊れている場合、再作成する: ln -sf ../agents .claude/agents。npm run update-readmes が失敗する場合、scripts/generate-readmes.js が存在し js-yaml がインストールされていることを確認する。

ステップ11: 翻訳ファイルを生成する

すべてのエージェントに必須。 このステップは、この手順に従う人間の著者とAIエージェントの両方に適用される。スキップしない — 欠落した翻訳は古いバックログとして蓄積される。

新しいエージェントをコミットした直後に、サポートされている4つのロケールすべての翻訳ファイルを生成する:

for locale in de zh-CN ja es; do
  npm run translate:scaffold -- agents <agent-name> "$locale"
done

その後、各ファイル内の生成されたプロセを翻訳する（コードブロックとIDは英語のまま）。最後にステータスファイルを再生成する:

npm run translation:status

期待結果： i18n/{de,zh-CN,ja,es}/agents/<agent-name>.md に4つのファイルが作成され、すべての source_commit が現在のHEADと一致する。npm run validate:translations は新しいエージェントに対して0件の古さ警告を示す。

失敗時： 足場作りが失敗した場合、エージェントが agents/_registry.yml に存在するか確認する。ステータスファイルが更新されない場合、npm run translation:status を明示的に実行する — CIでは自動的にトリガーされない。

バリデーション

• エージェントファイルが agents/<agent-name>.md に存在する
• YAMLフロントマターがエラーなく解析される
• 必須フィールドすべてが存在する: name、description、tools、model、version、author
• name フィールドがファイル名（.md 除く）と一致する
• すべてのセクションが存在する: 目的、機能、利用可能なスキル、使用シナリオ、例、制限事項、参照
• フロントマターのスキルが skills/_registry.yml に存在する
• デフォルトスキル（meditate、heal）はエージェントの方法論の核心でない限り一覧されていない
• ツールリストが最小権限原則に従っている
• エージェントが agents/_registry.yml に正しいパスと一致するメタデータで一覧されている
• レジストリの total_agents カウントが更新されている
• .claude/agents/ シンリンクが新しいエージェントファイルに解決される
• 既存のエージェントとの重大な重複がない

よくある落とし穴

• ツールの過剰プロビジョニング: エージェントが読んで分析するだけの場合に Bash、Write、または WebFetch を含める。これは最小権限に違反し、意図しない副作用につながる可能性がある。最小限のセットから始め、機能がツールを必要とする場合にのみツールを追加する。
• スキル割り当ての欠落または誤り: レジストリに存在しないスキルIDを一覧するか、スキルを割り当てることを完全に忘れる。常に grep "id: skill-name" skills/_registry.yml で各スキルIDを確認してから追加する。
• デフォルトスキルの不必要な一覧: レジストリからすでに継承されている場合に meditate や heal をエージェントフロントマターに追加する。方法論の核心である場合（例: mystic、alchemist、gardener、shaman）にのみ一覧する。
• 既存エージェントとのスコープの重複: 既存の53エージェントのいずれかによって既にカバーされている機能を複製する新しいエージェントを作成する。常にレジストリを先に検索し、代わりに既存エージェントのスキルを拡張することを検討する。
• 曖昧な目的と機能: 「開発を助ける」ではなく「完全な構造、文書化、CI/CD設定でRパッケージを足場する」と書く。具体性こそがエージェントを有用で発見可能にする。

関連スキル

• create-skill - エージェントファイルの代わりにSKILL.mdファイルを作成するための並行手順
• create-team - 複数のエージェントを調整されたチームに構成する（予定）
• commit-changes - 新しいエージェントファイルとレジストリ更新をコミットする