メインエージェントループに寄せる — スキル図とプロンプト設計の実践ガイド
はじめに
エージェントを作り始めると、チームごと・機能ごとに サブエージェント を増やし、上に オーケストレータ を載せる構成が自然に見えます。Anthropic の Applied AI チームが整理している通り、エンタープライズではその設計が コンテキストのロス、Frankenprompt、評価の分散、レイテンシ で痛くなる例が多いようです。
一方で、1 つのメインエージェントループ に寄せ、Skills で手順・判断を段階的に開示し、ツールで行動とガードレール を担う形は、同じタスクで品質が上がり、コスト・待ち時間が下がるケースも報告されています。
この記事では、原典の「いつサブエージェントを畳むか」を前提に、実装に入る前に描くスキル図 と プロンプト（system / skill / tool 説明）の設計 を、自分用のチェックリストとしてまとめます。
サブエージェントを残す条件（畳む前の判断）
原記事では、サブエージェントは依然有用で、次のようなときに残す、と書かれています。
- 1 ループの コンテキスト肥大 で、測定可能な性能劣化がある
- 並列 で、捨てられる fresh なコンテキストが必要
- ツール選択が破綻 する、または system prompt 内の 指示が衝突 する
逆に、意図分類 → 固定パイプライン → セグメント別ブランチ → マルチエージェント、という 「モデルがもうやってくれる仕事をハーネスが二重にやっている」 構造は、畳み候補になりやすいです。組織図そのままのエージェント分割（Conway の法則）も要注意、という話です。
設計の第一歩は「全部サブエージェントにする」ではなく、上記 3 条件に当てはまるか をメモすることです。
実装前に描く「スキル図」（アーキテクチャ図の中身）
ここで言うスキル図は、組織図ではなく 「1 ターンごとに何が見えるか」 の図です。Mermaid でもホワイトボードでも構いません。
レイヤー 1: メインループ（必ず 1 枚）
中心に次を固定します。
[ユーザー] ↔ [ハーネス: ターン上限・コスト・書き込みゲート]
↕
[1 モデル / 1 コンテキスト]
↕
[ツールバッチ並列実行 → 生結果を同じモデルへ]
↕
[回答 | ユーザーへの質問 | 次のツールバッチ]
原記事の要点: 計画を書くモデルと実行するモデルが同じ。オーケストレータと専門家が別コンテキストだと、途中で計画を変えにくい。
図に書く項目:
- ターン上限・コスト上限
- 並列ツール実行の有無
- 回答後の optional verifier / goal check
レイヤー 2: コンテキストの「常時 / 按需 / 禁止」
3 色または 3 列で分けます。
種類 | 中身の例 | 載せ方 |
|---|---|---|
常時（薄く） | 人格・安全・出力形式・エスカレーション | system prompt（短く） |
按需（Progressive disclosure） | ドメイン手順・社内ルール・チェックリスト | Skills（説明だけ先に、本文は読み込み時） |
按需（データ） | ポリシー全文、商品仕様、メトリクス定義 | KB 検索 / lookup ツール（コードで prompt に貼らない） |
行動・ガード | API 呼び出し、承認、バリデーション | Tools（固定スキーマ、権限チェックはツール内） |
スキル図では 「この Skill はどのユーザー意図のときにトリガーされるか」 を、各 Skill ボックスに 1 行の trigger 説明 で書きます。原記事どおり、Skill は「専門サブエージェントの prompt が持っていた 手順・ルール・判断」の置き場です。
レイヤー 3: ツール群（意図単位でグループ）
ツールは API 1 本 = ツール 1 個 にしない。原記事は 30〜50 定義を超えると tool choice が劣化 しやすい、としています。
図では:
- ユーザー意図ごとに 1 グループ（例: 注文確認、返金、在庫、社内検索）
- 各ツールに deferred loading / tool search 用の短い description
- 依存関係（Y は X の結果が必要）は Y ツール内でチェックし、モデルが読める拒否・指示を返す（別エージェントに渡さない）
移行中だけ サブエージェントを 1 ツールとして呼ぶ 箱を描いてよい。原記事は「会話の主導権を渡す full handoff は、ユーザーと直接やり取りが必要なときだけ」としています。
レイヤー 4: 畳む候補のマッピング（移行用）
既存構成がある場合、表を 1 枚足します。
旧サブエージェント | 連鎖・同一データ・同時呼び出し | 畳み方 |
|---|---|---|
A → B が多い | 密結合 | 1 Skill + 共有ツール にマージ候補 |
独立調査・検証のみ | コンテキスト分離が有効 | サブエージェント as tool または並列のまま |
権限だけ違う | ループ分割不要 | ツール内 PER_USER チェック |
「スキル図」は 最終形だけ ではなく、この 移行マップ も同じドキュメントに置くと、eval で 1 体ずつ畳めます。
プロンプト設計 — 何をどこに書くか
1. System prompt（中央チームが所有、短く）
原記事: 1 つの central team が E2E 品質と system prompt を所有し、ツールと eval を ship 前に vet する。
system に書くもの:
- 役割とトーン（一貫した on-brand）
- 出力の型（Markdown / JSON / 禁止事項）
- いつ Skill を読むか の原則（「手順が必要なら関連 Skill を読む」）
- いつツールを使うか の原則（「推測で数値を言わない」など）
- 予算・安全（PII、書き込み前の確認）
system に 書かない もの:
- ドメイン別の長い SOP（→ Skill）
- ポリシー全文（→ KB + 検索ツール）
- ルーティング用の「もし返金なら agent B」（→ Skill trigger + モデル判断、または eval で検証）
Claude Code では高度モデル向けに system を 80% 以上削り、Skills / ツールの段階開示に寄せた、という例も記事にあります。古いモデル向けの冗長ルール は /claude-api prompt-audit 的な見直し対象、という整理です。
2. Skill 1 本あたりのテンプレ
各 Skill（チーム DRI 所有）:
---
name: （動詞またはドメイン）
description: （いつ使うか — これが progressive disclosure のフック）
---
## いつ適用する
- トリガー条件（ユーザー発話・ツール結果・エラー種別）
## 手順
1. …
2. …
## 判断・例外
- エスカレーション条件
## 出力
- この Skill 適用後にユーザーへ返す形式
## 関連ツール
- 必須 / 任意のツール名（説明は tool 側）
## Eval（同梱）
- この Skill 単体の 3〜5 本 + E2E への影�ダウン
skill-creator / skill-doctor の思想: 重複 Skill の統合、未使用 Skill の削除。スキル図と ライブラリのコスト・使用頻度 を定期的に突き合わせます。
3. Tool description
- 意図ベースの名前と 1〜2 文の description（モデルが search できるキーワードを含める）
- 入力スキーマは固定。前提条件不足 は HTTP エラーではなく モデルが次の一手を選べる文言 で返す
- サブエージェント as tool にする場合は 共有 response schema を決め、メインループで 要約ではなく生に近い結果 + 検証可能なフィールド を返す（要約 handoff の劣化を減らす）
4. 計画は prompt ではなくコンテキスト内
原記事の single loop: 初回ターンで計画をコンテキストに書き、結果が返るたびに更新。以前の「ルールカタログから plan を書き換えるコードステップ」は不要になりやすい。計画用の Skill（/plan 相当）を optional で持つ、という図の書き方が実装と一致します。
Eval 駆動で 1 体ずつ畳む
設計図だけでは足りません。原記事の手順をそのまま運用に落とすと:
- 中央が E2E eval 10 本（golden）から開始。最終回答を rubric で採点。
- オーケストレータ時代は routing accuracy、畳んだ後は 正しい Skill / ツールが載ったか を追う。
- サブエージェントを 1 体 Skill + tools に fold → with / without を比較。スコアだけでなく flip したタスク を見る（記事の例: 配送日を専門家に聞かず自己回答してプロセスが壊れた）。
- 本番で 連鎖する agent チェーンごとに eval タスク + 禁止ルールごとに 1 タスク + 各タスク複数回実行（非決定性）。
スキル図の各矢印（「A の後 B」）に eval ID を紐付ける と、畳み漏れが減ります。
複数チームで 1 エージェントを育てる
原記事の分担:
所有 | 内容 |
|---|---|
中央（小さく） | system prompt、E2E eval、ship 前 review |
ドメインチーム | Skills + 小さな skill eval + MCP tools |
全員 | Knowledge は 検索ツール or Skill 内 reference、prompt へのベタ貼り禁止 |
スキル図の 凡例 に「Owner: Team X」を書いておくと、Frankenprompt（全員が system に 1 文追加）を防ぎやすいです。
まとめ — 設計時の 3 問
実装に入る前に、図とプロンプトの両方に効く問いです。
- この仕事は、別コンテキストが本当に必要か？（並列・検証・ measurable bloat 以外は Skill + tool 候補）
- 手順は Skill、事実は KB、行動は tool、人格と枠だけ system か？
- 10 本の E2E eval で、畳んだときに壊れる連鎖はどれか？
モデルはループ内で扱える仕事が増え続けるので、アーキテクチャより「測って 1 つずつ変え、残すものだけ残す」 が原記事の結論に近いです。スキル図とプロンプト分割は、その 変更の単位 を可視化するための道具、と捉えると運用しやすいです。
おわりに
Anthropic の記事は、サブエージェントを Skills と tools に畳むタイミング と single agent loop の形 を整理したものです。自分の開発では、それを 4 レイヤーのスキル図（ループ / コンテキスト開示 / ツール群 / 移行マップ）と system・Skill・tool の責務分離 に落とすと、プロンプトが読みやすく、チーム追加も eval 付きでできます。
原典: Building agents: When to fold subagents into your main agent loop（Claude by Anthropic）
Discussion
No comments yet