Claude Codeのサブエージェントは薄いラッパーに保つ

サブエージェントとスキルを両方使い始めると、すぐに「これはどっちに書くんだろう」「スキルだけで完結できるならエージェント要らないのでは」という迷いに当たります。自分も一度サブエージェントを全廃して、数日後に薄いラッパーとして書き戻しました。揺れた末に「処理はスキル側、サブエージェントは薄いラッパー」に落ち着いた理由を、典型的に出る反論ごと書いておきます。

処理はスキルに集約しサブエージェントを薄く保つ

結論はシンプルで、サブエージェントとスキルを併用するなら、処理は全部スキル側に書き、サブエージェントは「対応するスキルを呼ぶだけの薄いラッパー」に保つのがいいです。理由は2つあります。

1つ目は、サブエージェント側でスキルを呼ぶことで、親の会話とは別のコンテキストでスキルを動かせる点です。スキルを直接呼ぶと、そのスキルが読み込んだガイドや中間生成物が親の会話に残り、続けて別のスキルを呼んだときに前のコンテキストが混ざります。サブエージェントは別コンテキストで動いて結果だけ親に返すので、長い手順を含むスキルほど、サブエージェント経由で呼ぶ価値が出ます。

2つ目は、両方に処理を書くと一次情報が2か所に増え、片方を更新するともう片方が必ず古びる点です。サブエージェント本文(=system prompt)と SKILL.md の両方に同じ手順が書けてしまう以上、書き手は「どちらが正本か」を毎回判断することになります。スキル側だけに寄せれば、更新時に見る場所は1か所で済みます。

「スキルだけで」「サブエージェント本文に直書きで」への答え

ここまで読むと当然「じゃあスキルだけでよくない?」「逆にサブエージェント本文に全部書けば?」という反論が出ます。両方とも自分が一度通った道なので、それぞれにどう答えるかを書いておきます。

スキルだけで完結させると親の会話にコンテキストが残る

/<skill-name> で直接スキルを呼べる以上、サブエージェントを噛ませず「スキルだけで運用すればいいのでは」と考えるのは自然です。実際、軽い処理ならそれで足ります。

ただし、たとえばレビュー用スキルはガイド一式を読み込んでから記事と突き合わせます。これを親で直接呼ぶと、ガイドの内容や中間メモが親の会話履歴に積み上がり、続けて執筆用の別スキルを呼んだときに「前のレビューの文脈」が残った状態で動くことになります。サブエージェント経由なら別コンテキストで動くので、親に返ってくるのは「結果報告」だけです。

公式ドキュメントもサブエージェントの利点として「コンテキストを別管理にできる」点を挙げており^[1]、長い手順や大きな読み込みを伴うスキルは、サブエージェントで包んでおくと連続実行に強くなります。

サブエージェント本文に直書きするとスキル側のメリットを失う

逆に「だったらスキル側を捨てて、サブエージェント本文に手順を全部書けばいい」という発想も出ます。公式サンプルの code-reviewer のような形で、フロントマターの後ろに system prompt として手順を直書きする設計です^[1:1]。

直書きには3つの不利益があります。1つ目は /<skill-name> でコマンドとして直接呼べなくなることです。スキルを切っておけば、サブエージェント経由でも、ユーザーが直接 /<skill-name> と打ってもいい二段構えになります。2つ目はスキルの組み合わせが効かなくなることです。複数のスキルをオーケストレーター側のスキルから順に呼ぶ運用にしておくと、後から並び替えたり差し替えたりが軽いですが、サブエージェント本文に処理が埋まっているとこの組み替えができません。3つ目は Progressive Disclosure が効かなくなることです。SKILL.md は呼ばれたときだけ読まれる構造になっていて、本体を短くして詳細を reference.md などに切り出せます^[2]。サブエージェント本文は呼び出し時に常時読まれるので、長文を書くと毎回 token cost を払うことになります。

スキルに寄せる選択は「コマンドとして再利用できる」「他スキルと組み合わせられる」「本体を短く保てる」の3つを同時に取りに行く判断です。

1スキル1エージェント30行以内に着地した運用

ローカルルール agent-format.md には「1サブエージェント = 1スキル」「本体30行以内」と書いてあります。実測すると現状は次の通りです。

7ファイルすべてが21〜23行に収まり、上限30行に対しても余裕があります。

reviewer.md の中身は呼ぶスキル名と入出力だけ

たとえば reviewer.md のフロントマター以下は、対応するスキル名・入力・親に返すものを記すだけで、レビューの手順は一切登場しません。

`/review-post` スキルを実行する。

## 入力
親から `permalink`(レビュー対象記事のファイル名)を受け取る。

## 処理
`/review-post` スキル(`.claude/skills/review-post/SKILL.md`)の手順に従って動く。