paths: plugins//agents/**/.md, .claude/agents/**/*.md
サブエージェント
Markdown + YAML Frontmatter形式で記述します。
ファイル配置
エージェント定義ファイルは以下のパスに配置します:
plugins/*/agents/**/*.md- プラグイン内のエージェント.claude/agents/**/*.md- プロジェクト固有のエージェント~/.claude/agents/**/*.md- ユーザー固有のエージェント（全プロジェクトで利用可能）
注意（v2.1.39以降）:
.claude/agents/ディレクトリ内には、エージェント定義以外のMarkdownファイル（README.mdなど）も配置できます- エージェント定義として認識されるのは、frontmatterに
nameフィールドを持つMarkdownファイルのみです - ドキュメント用のMarkdownファイルには警告は表示されません
形式
---
name: agent-name
description: エージェントの説明。いつ使うべきかを明確に記述。
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: default
skills: skill-name
---
エージェントのシステムプロンプト
Frontmatterオプション
| フィールド | 必須 | 説明 |
|---|---|---|
name | Yes | 識別子（小文字・ハイフンのみ） |
description | Yes | 目的と使用タイミングを説明 |
tools | No | アクセス可能なツール（カンマ/YAML形式）。省略時は全ツール継承。--print モードでも尊重される（v2.1.119以降） |
disallowedTools | No | 使用禁止ツール（カンマ/YAML形式）。--print モードでも尊重される（v2.1.119以降） |
model | No | sonnet, opus, haiku, inherit、またはフルモデルID（例: claude-opus-4-5, claude-sonnet-4-6）。省略時はinherit（親スレッドのモデルを継承）。Agent ツール呼び出し時に model パラメータで上書き可能（v2.1.72以降、per-invocation オーバーライド参照）。フルモデルIDは v2.1.74 以降で対応（--model と同じ値が使用可能） |
permissionMode | No | default, acceptEdits, bypassPermissions, plan, dontAsk。組み込みエージェントを --agent <name> で起動した場合にも適用される（v2.1.119以降） |
skills | No | 自動ロードするスキル名（カンマ/YAML形式）。プラグインスキルは完全修飾名（plugin-name:skill-name）で指定 |
hooks | No | フック定義（hooks.md参照） |
memory | No | 永続的メモリのスコープ：user, project, local（v2.1.33以降） |
effort | No | 思考努力レベル：low, medium, high, xhigh, max（maxはOpus 4.6のみ。xhighはOpus 4.7のみで他モデルではhighにフォールバック）（v2.1.78以降、xhighはv2.1.111以降） |
initialPrompt | No | エージェント起動時に自動送信される最初のプロンプト（v2.1.83以降） |
maxTurns | No | エージェントの最大ターン数。省略時は制限なし |
mcpServers | No | エージェントが利用可能なMCPサーバーを制限（カンマ/YAML形式） |
isolation | No | 実行分離モード：worktree（v2.1.50以降） |
background | No | バックグラウンドタスクとして常に実行：true/false（v2.1.49以降） |
description のベストプラクティス
- いつ使うべきかを明確に記述
- 具体的なキーワードを含める（自動委譲の判断に使用）
良い例:
description: コードレビュー専門家。品質・セキュリティ・保守性を確認。コード変更後に積極的に使用。
悪い例:
description: コードレビュー # 曖昧で自動委譲されにくい
tools のガイドライン
- 省略時: 親スレッドの全ツールを継承（MCPツール含む）
- 指定時: 指定したツールのみアクセス可能
- 最小限のツールを付与することを推奨（セキュリティ向上）
カンマ区切り形式:
tools: Read, Grep, Glob, Bash(git:*)
YAML形式のリスト:
tools:
- Read
- Grep
- Glob
- Bash(git:*)
注意 (v2.1.20以降): Bash(*)はBashと同等に扱われます。すべてのBashコマンドへのアクセスを許可する場合は、どちらの記法でも同じ意味になります。セキュリティ上の理由から、可能な限り具体的なパターンを指定することを推奨します。
注意 (v2.1.117以降 - macOS/Linux ネイティブビルド): macOS および Linux のネイティブビルドでは、Glob と Grep ツールが廃止され、Bash ツール経由で提供される組み込みの bfs および ugrep コマンドに置き換えられました。Windows および npm インストールビルドは変更ありません。
tools: Globやtools: Grepを指定した場合、ネイティブビルドではこれらのツールが利用できません- クロスプラットフォームで動作するプラグインを作成する場合は、
Glob/Grepの代わりにBashツールを使用することを推奨します
サブエージェントの制限（v2.1.33以降）
Task(agent_type) 構文を使用して、起動可能なサブエージェントを制限できます。
カンマ区切り形式:
tools: Read, Grep, Task(code-reviewer), Task(test-runner)
YAML形式のリスト:
tools:
- Read
- Grep
- Task(code-reviewer)
- Task(test-runner)
この設定により、エージェントは code-reviewer と test-runner という名前のサブエージェントのみを起動できます。他のサブエージェントを起動しようとすると、権限エラーが発生します。
使用例:
---
name: restricted-reviewer
description: 特定のサブエージェントのみ起動可能なレビューエージェント
tools:
- Read
- Grep
- Task(security-checker)
- Task(style-checker)
---
コードレビューを実行し、必要に応じて security-checker または style-checker のみを起動します。
セキュリティのベストプラクティス:
- エージェントが必要とするサブエージェントのみを明示的に許可
Taskを無制限に許可すると、任意のサブエージェントを起動できてしまうため注意- ワークフロー全体のツール使用を制御する場合に有効
パーミッション優先順位（v2.1.27以降）:
content-level（具体的パターン）のask設定は、tool-level（ツール全体）のallow設定より優先されます。
{
"allow": ["Bash"],
"ask": ["Bash(rm *)"]
}
上記の設定では:
Bashツール全体は許可（allow）されていますがrmコマンドは確認プロンプトが表示されます（askが優先）
この仕組みにより、ツール全体を許可しつつ、危険な操作のみ個別に制限できます。
memory（v2.1.33以降）
エージェントに永続的なメモリを付与し、セッション間で情報を保持できます。
---
name: stateful-agent
description: 状態を保持するエージェント
memory: project
---
スコープの種類
| スコープ | 説明 | 保存範囲 | 使用例 |
|---|---|---|---|
user | ユーザー全体で共有 | すべてのプロジェクト | ユーザー設定、学習した好み |
project | プロジェクト内で共有 | 現在のプロジェクト | プロジェクト固有の知識、パターン |
local | プロジェクト内ローカル | .claude/agent-memory-local/<name>/に永続保存（gitignore推奨） | プロジェクト固有だがgit管理しない個人メモ |
使用例
プロジェクト固有の知識を保持:
---
name: architecture-expert
description: プロジェクトのアーキテクチャ知識を保持する専門家
memory: project
tools:
- Read
- Grep
---
プロジェクトのアーキテクチャ設計を理解し、過去の決定事項を記憶します。
ユーザー設定を保持:
---
name: personal-assistant
description: ユーザーの好みを学習するアシスタント
memory: user
---
ユーザーのコーディングスタイルや好みを学習し、すべてのプロジェクトで活用します。
ベストプラクティス
- userスコープ: 個人的な設定や好みの保存に使用
- projectスコープ: プロジェクト固有のパターンや決定事項の記録に使用
- localスコープ: プロジェクト固有だがgit管理しない個人メモの保存に使用
- メモリには必要最小限の情報のみを保存（パフォーマンスへの影響を考慮）
skills の完全修飾名（v2.1.47以降）
プラグインエージェントでスキルを参照する場合は、ベア名（例: my-skill）ではなく、完全修飾プラグイン名（例: my-plugin:my-skill）を使用してください。
理由: ベア名での参照は黙って失敗することがありましたが、v2.1.47以降ではこの仕様が正しく動作するようになっています。確実にスキルをロードするために、完全修飾名の使用を推奨します。
推奨（完全修飾名）:
---
name: my-agent
description: プラグインスキルを使用するエージェント
skills:
- my-plugin:my-skill # 完全修飾名（推奨）
- other-plugin:other-skill
---
非推奨（ベア名）:
---
name: my-agent
description: プラグインスキルを使用するエージェント
skills:
- my-skill # ベア名（ロードに失敗する可能性あり）
---
注意: 同一プラグイン内のスキルであってもプラグイン名を明示することを推奨します。
isolation（v2.1.50以降）
エージェントを隔離されたgit worktreeで実行するよう宣言的に設定できます。
---
name: isolated-agent
description: 隔離されたworktreeで実行するエージェント
isolation: worktree
---
隔離されたgit worktreeで作業するエージェントのシステムプロンプト
isolation: worktree
エージェントが起動すると、自動的に新しいgit worktreeが作成され、その中でエージェントが実行されます。エージェント終了後はworktreeが削除されます。
特徴:
- メインブランチへの影響を受けずに独立した作業が可能
- 並列エージェント実行時の競合を防止
WorktreeCreate/WorktreeRemoveフックで作成・削除時の処理をカスタマイズ可能
使用例:
---
name: safe-refactoring-agent
description: 安全なリファクタリング専門エージェント。コードの大規模変更時に使用。
isolation: worktree
tools:
- Read
- Edit
- Bash(git:*)
---
隔離されたworktreeでコードのリファクタリングを安全に実施します。
EnterWorktree / ExitWorktree ツール（v2.1.72以降）:
worktreeセッションを手動で制御するためのツールが利用可能です:
EnterWorktree: worktreeセッションを開始し、隔離された作業環境に入るExitWorktree:EnterWorktreeで開始したworktreeセッションを終了し、元の作業環境に戻る
isolation: worktree を使用したエージェントでは、worktreeの作成・終了は自動的に管理されます。手動で EnterWorktree / ExitWorktree を使用するケースは、エージェント定義外でworktreeセッションを制御する場合に有用です。
関連:
- CLIフラグ
--worktree/-wでも同様の動作が可能（v2.1.49以降） WorktreeCreate/WorktreeRemoveフックとの組み合わせで、セットアップ・クリーンアップ処理を自動化できます（hooks.md参照）
background（v2.1.49以降）
background: true を指定することで、エージェントが常にバックグラウンドタスクとして実行されます。
---
name: background-agent
description: バックグラウンドで動作するエージェント
background: true
---
バックグラウンドで非同期処理を実行します。
ユースケース:
- 長時間かかる処理を非同期で実行する
- メインの会話フローをブロックせずにタスクを実行する
- 監視・ログ収集などの常駐型タスク
hooks
エージェント実行時のフックを定義。詳細はhooks.mdを参照:
---
name: code-reviewer
description: コードレビュー専門家
hooks:
PreToolUse:
- matcher: "Edit|Write"
hooks:
- type: command
command: "${CLAUDE_PLUGIN_ROOT}/scripts/check-style.sh"
Stop:
- hooks:
- type: prompt
prompt: "レビュー結果を要約"
---
model per-invocation オーバーライド（v2.1.72以降）
Agent ツールを呼び出す際に、エージェント定義の model フィールドで設定したデフォルトモデルを、呼び出しごとに上書きできます。
使用例:
エージェント定義でデフォルトモデルを sonnet に設定していても、特定の呼び出しのみ opus を使用したい場合:
# エージェント定義（agents/code-reviewer.md）
---
name: code-reviewer
description: コードレビュー専門家
model: sonnet
---
このエージェントを呼び出す際に、特定の呼び出しのみモデルを変更できます。
優先順位:
- Agent ツール呼び出し時の
modelパラメータ（最優先） - エージェント定義 frontmatter の
modelフィールド inherit（親スレッドのモデルを継承）
この機能により、通常は軽量なモデルを使いながら、複雑なタスクのみ高性能なモデルに切り替えるといったコスト最適化が可能です。
CLIコマンド
claude agents（v2.1.50以降）
設定済みのエージェント一覧を確認するコマンド:
claude agents
プラグイン開発時に定義したエージェントが正しく認識されているかを確認できます。