custom-agent-definitions

カスタムエージェントの定義

Claude Code でカスタムエージェントを定義、設定するための専門知識です。

完全な YAML の実例（独立した調査エージェント、読み取り専用の探索エージェント、包括的なセキュリティ監査担当、プラグインの構成、一般的なパターン）については、REFERENCE.md を参照してください。

このスキルを使う場面

次のような場合にこのスキルを使います…	次のような場合は agent-teams を使います…
.claude/agents/ に新しい .md エージェント定義ファイルを作成する	定義済みの複数のエージェントを起動し、チームとして連携させる
単一エージェントの model、allowed-tools、または context: fork を設定する	共有タスクリストを使うリーダー／チームメイト構成を設定する
読み取り専用や書き込み制限のある特化型エージェントのツールアクセスを制限する	worktree 間で並行作業の順序を決める（parallel-agent-dispatch を参照）
1 つのエージェントの動作を定義するシステムプロンプトを作成する	既存のエージェント定義のセキュリティを監査する（meta-audit を参照）

基本概念

カスタムエージェントを使うと、組み込みのエージェント（Explore、Plan、Bash など）以外の、特化したエージェントタイプを定義できます。それぞれに独自のモデル、ツール、コンテキスト設定を持たせられます。YAML フロントマターと Markdown のシステムプロンプトを使い、.claude/agents/ またはプラグインの agents/ ディレクトリで定義します。

---
name: my-custom-agent
description: What this agent does
model: sonnet
allowed-tools: Bash, Read, Grep, Glob
---

# Agent System Prompt

Instructions and context for the agent...

主なフィールド

コンテキストのフォーク

値	動作
fork	独立したコンテキストのコピーです。エージェントは親の履歴を参照できますが、変更が親に影響することはありません
（デフォルト）	エージェントは親とコンテキストを共有し、会話の状態を参照、変更できます

探索的な調査、並行調査、独立した実験には fork を使います。REFERENCE.md → 独立した調査エージェント を参照してください。

ツールアクセス（許可と禁止）

フィールド	目的	動作
allowed-tools	許可するツールのホワイトリスト	エージェントはこれらのツールのみを使用できます
disallowedTools	禁止するツールのブラックリスト	エージェントはこれら以外のすべてのツールを使用できます

読み取り専用エージェントの設定、危険な機能の制限、サンドボックス化には disallowedTools を使います。両方を組み合わせることもできます。明示的なホワイトリストに、安全のためのブラックリストを追加できます。REFERENCE.md → 読み取り専用の探索エージェント を参照してください。

委任用の agent フィールド

agent フィールドでは、Agent ツールを使って委任するときに使用するエージェントタイプを指定できます。これにより、コマンドやスキルで優先するエージェントタイプを指定できます。

agent: security-auditor

エージェント設定フィールドのリファレンス

フィールド	型	説明
name	string	エージェント識別子
description	string	エージェントの動作
model	string	使用するモデル（sonnet、opus）
context	string	コンテキストモード：fork またはデフォルト
permissionMode	string	default、acceptEdits、dontAsk、bypassPermissions、または plan
maxTurns	number	エージェントが停止するまでのエージェント実行ターンの最大数
background	bool	true に設定すると、常にバックグラウンドタスクとして実行します
memory	string	永続メモリのスコープ：user、project、または local
skills	list	起動時にエージェントのコンテキストへ事前読み込みするスキル名
mcpServers	list	エージェントが利用できる MCP サーバー名
tools	list	エージェントが使用できるツール（agents/ ディレクトリ内。スキルでは allowed-tools を使用）
disallowedTools	list	エージェントが使用できないツール
created / modified / reviewed	date	ライフサイクルの日付

ベストプラクティス

1. 最小権限の原則 — エージェントに必要なツールのみを許可します。

2. 分離には context: fork を使用する — 調査作業によってメインのコンテキストが汚染されないようにします。

3. 許可リストと拒否リストを併用する — 明示的な許可リストに、安全のための拒否リストを組み合わせます。

4. 説明を明確にする — エージェントの役割と境界を説明します。

5. モデルの選択 — 開発ワークフローには sonnet、深い推論や分析には opus を使用します。（リポジトリにおけるサブエージェントで Opus を使用する指針については、.claude/rules/agent-and-tool-selection.md を参照してください。）

6. 失敗は明確に報告する — 行き詰まったディスパッチ済みエージェントは、最終メッセージで必ずそのことを伝えてください。Terminal. ／ Done. ／ Stopped. のような一語だけの要約は使用しないでください。障害に遭遇した場合は、進行中の作業をコミットしてプッシュし、ドラフト PR を作成したうえで、何が原因で停止したのか、どのツールが拒否されたのかを正確に述べる必要があります。一語だけの断念はオーケストレーターにとって成功と区別できず、作業が気づかれないままクリーンアップされ、失われます（issue #1422）。各依頼文に含めるべきディスパッチプロンプトの形式については、parallel-agent-dispatch →「失敗を明確に伝える契約」を参照してください。

7. 読み取り専用の並列展開には、Skill を持たない agentType を優先する — ファイルを読み取り、構造化出力を返すだけのエージェントに Skill ツールを持たせてはいけません。Skill を持つエージェントは、最初のツール呼び出しの前に約 25k トークン分の skill_listing と deferred_tools_delta によるコンテキスト負担が生じるため、読み取り中心の並列展開ではサブエージェントのコンテキストウィンドウを超える可能性があります。代わりに、軽量な読み取り専用エージェント（例：agents-plugin:review）を使用してください。parallel-agent-dispatch →「読み取り専用の並列展開には Skill を持たない agentType を使用する」（issue #1549 ／ #1550）を参照してください。

各プラクティスの YAML の記述例は、REFERENCE.md → ベストプラクティスのスニペット にあります。

クイックリファレンス

コンテキストモード

モード	分離	用途
（デフォルト）	共有	通常のワークフロー
fork	分離	調査、実験

ツール制限のパターン

パターン	フィールド
許可リストのみ	allowed-tools: Tool1, Tool2
拒否リストのみ	disallowedTools: Tool1, Tool2
併用	両方のフィールドを指定

関連項目

• REFERENCE.md — YAML の詳細な記述例とスニペット
• agent-teams — 暗黙的なチームによるマルチエージェントの連携
• parallel-agent-dispatch — worktree の事前確認、スコープの予算、失敗を明確に伝える契約
• meta-audit — 既存のエージェント定義のセキュリティと完全性を監査
• .claude/rules/agent-development.md — エージェントのライフサイクルとフィールドの意味