Agent Teamsでサブエージェント定義をteammateに流用する

Agent Teamsでサブエージェント定義を流用するとは

.claude/agents/に置いたサブエージェント定義は、単一セッション内の委任だけでなくAgent Teamsのteammateとしても起動できます。役割を1回定義すれば、通常のサブエージェント呼び出しと、teammateとしての起動の両方で同じ定義を使い回せます。

teammateをスポーンするプロンプトでエージェントタイプ名を指定するだけで済み、定義ファイル自体に手を加える必要はありません。ただし、定義に書いたすべてのフィールドがteammateに適用されるわけではありません。tools・model・本文(body)は引き継がれますが、skillsは引き継がれず、mcpServersは表示モードによって適用されるかどうかが変わります。定義を書くときにこの区別を知らないと、「teammateに渡したのにSkillが読み込まれない」「plan modeを指定したのに確認プロンプトが出る」といった食い違いに遭遇します。

エージェントタイプ名を指定するだけでteammateが起動する

やり方はシンプルです。まず通常のサブエージェントと同じ形式で定義ファイルを.claude/agents/に置きます。

---
name: security-reviewer
description: 認証・認可まわりの差分を優先して確認するレビュー担当
tools: Read, Grep, Bash
model: sonnet
---
 
あなたはセキュリティレビュー専任のエージェントです。認証・認可に関わる差分を優先して確認し、
権限チェックの抜けや秘密情報のハードコードがないかを重点的に見てください。

この定義は、通常のサブエージェントとしてClaudeが自動委任するのにも使えますし、Agent Teamsが有効な状態でteammateとして名指しでスポーンするのにも使えます。teammateとして起動したいときは、スポーンを依頼するプロンプトでエージェントタイプ名を伝えるだけです。

security-reviewerエージェントタイプを使って、認証モジュールの監査を担当する
teammateを立ち上げて

定義ファイルを新しく書き直す必要はありません。既存の.claude/agents/security-reviewer.mdをそのまま名指しすれば、Claude Codeが定義を読み込み、teammateに適用できる部分だけを反映します。

teammateに引き継がれる項目と引き継がれない項目

公式ドキュメントが明記しているのは、tools・model・本文(body)・skills・mcpServersの5つのフィールドだけです。このうち実際に適用されるのは3つで、残り2つは適用されません。

skillsが引き継がれないのは見落としやすい点です。あるSkillの存在を前提に書いた役割定義を、そのままteammateとして使い回すケースを考えます。通常のサブエージェントとして呼べばskillsフィールドの指定どおりSkillが事前ロードされますが、同じ定義をteammateとして起動すると、そのSkillはロードされません。必要なSkillがプロジェクト側の設定にも置かれているかを、teammateへの転用前に確認する必要があります。

hooks・disallowedTools・maxTurns・memory・effort・isolationのような、サブエージェント定義に書けるその他のfrontmatterフィールドについて、公式ページはteammateへの適用有無を明記していません。動作を前提にした運用を組む前に、実機で確認するのが安全です。

モデル選択でも定義のmodelフィールドが使われる

teammateのモデルは、次の優先順位で決まります。

1. スポーンプロンプト側でそのteammate向けに名指ししたモデル
2. サブエージェント定義から起動したteammateの場合、その定義のmodelフィールド(inheritならリードのモデルを選ぶ)
3. CLAUDE_CODE_SUBAGENT_MODEL環境変数(inherit以外に設定している場合)
4. リードの現在のモデル

つまり、定義のmodel: sonnetは、スポーンプロンプトでモデルを指定しなかったteammateにそのまま適用されます。チーム全体を1つのモデルに強制するCLAUDE_CODE_SUBAGENT_MODEL_FORCEを設定している場合は、この優先順位そのものが変わり、定義のmodelフィールドは無視されます。この環境変数の詳細はCLAUDE_CODE_SUBAGENT_MODELの記事にまとめています。

定義のmodelフィールドで選ばれた値も、組織のavailableModels許可リストによる審査を素通りするわけではありません。opusのようなファミリーエイリアスが許可リストで塞がれている場合、Anthropic APIとClaude Platform on AWSではリストが許すそのファミリーの最新バージョンに自動で置き換わります。プロバイダー固有のモデルIDを使う環境ではこの置き換えが働かないため、他の許可外の値と同じ扱いになり、teammateはリードのモデルにフォールバックします。定義ファイルを複数の組織・環境で使い回す場合、このフォールバック先まで意識しておくと、想定と違うモデルでteammateが動いていたという事態を避けられます。

in-processとsplit-paneで適用範囲が変わる

Agent Teamsのteammateは、in-process表示かsplit-pane表示かを選べます。この表示モードの違いが、定義のうち何が効くかを左右します。

split-paneのteammateは、本文とmcpServersの両方で定義の内容が主導権を持ちます。一方in-processのteammateは、本文が既定の指示への追記にとどまり、mcpServersは定義を無視してプロジェクト設定を使います。同じ定義ファイルでも、どちらの表示モードで起動するかによって、実際に走るteammateの中身は変わります。

表示モードに関わらず共通する前提もあります。teammateはCLAUDE.md・MCPサーバー・Skillsという通常セッションと同じプロジェクトコンテキストを読み込み、そこにリードからのスポーンプロンプトが加わります。ただしリード自身のそれまでの会話履歴は引き継がれません。定義ファイルの本文がteammateに渡すのは役割の指示だけで、リードがそれまでに積み上げた文脈は別途スポーンプロンプトで伝える必要があります。

permissionModeは定義に書いても効かない

サブエージェント定義にはpermissionModeフィールドがあり、通常のサブエージェントとして呼び出す分にはdefault・acceptEdits・planなどを個体ごとに固定できます。ところがteammateにはこの起動時指定に相当する仕組みがありません。定義をteammateの役割として流用してもpermissionModeは適用対象に含まれず、teammateは常にリードのモードから出発します。

背景には、teammateがそもそもリードの権限設定を丸ごと引き継ぐ、という仕組みがあります。リードが--dangerously-skip-permissionsで動いていれば、teammateも全員その設定を引き継ぎます。定義ファイル側のpermissionModeのような個体別の指定は、この一括継承の仕組みに割り込めません。

この挙動と、read-onlyなレビュー役をteammateとして徹底したい場合の回避策は、Agent Teams権限モデルの記事で扱っています。個体差を出したいなら通常のサブエージェント、チーム全体で確認方針を揃えたいならAgent Teams、という向き不向きがここに現れます。

どのスコープの定義が使えるか

公式が名指ししているのは、プロジェクトスコープ(.claude/agents/)・ユーザースコープ(~/.claude/agents/)・プラグイン・CLI定義(--agentsフラグ)の4つです。組織全体に配布するmanaged settings経由のサブエージェントは、この列挙に含まれていません。

managed subagentsが優先順位でプロジェクト・ユーザー定義より上位に来ることは、通常のサブエージェント委任では明記されています。teammateとしての流用についてだけ、この5番目のスコープが列挙から外れているのは、単なる書き漏らしなのか意図的な線引きなのかが本文からは読み取れません。組織で配布した役割定義をteammateとして使う予定があるなら、事前に検証しておくのが安全です。

built-in subagentの扱いも整理しておく価値があります。チーム構成のメタデータ(~/.claude/teams/{team-name}/config.json)には、各メンバーが起動時に名指しされたエージェントタイプを記録するmembers配列があり、ここには「built-inのタイプ」か「サブエージェント定義」のどちらかが入ると説明されています。Explore・Planのような組み込みタイプ自体をteammateとして起動できることを示す記述ですが、その場合にどのフィールドが適用されるかは、カスタム定義を使う場合と同じ列挙(tools・model・body・skills・mcpServers)に従うとみるのが自然です。

まとめ

Agent Teamsは、.claude/agents/のプロジェクト・ユーザー・プラグイン・CLI定義をteammateの役割としてそのまま使い回せます。スポーンプロンプトでエージェントタイプ名を伝えるだけで、定義ファイル側に手を加える必要はありません。ただし引き継がれるのはtools・model・本文の3項目にとどまり、skillsは常に無視され、mcpServersはsplit-paneのteammateにしか適用されません。permissionModeもteammateには効かず、常にリードのモードから出発します。既存のレビュー役やテスト実行役の定義をチーム運用に転用する前に、この対応表で「何が引き継がれ、何が引き継がれないか」を確認しておくと、想定外の挙動に振り回されずに済みます。