「担当を自分で作りたいのですが、ファイルに何を書けばよいのか分かりません。/agents から作るのですか」
「description を書いたのに、担当がなかなか使われません。本体はどこを見て、任せるかどうかを決めているのですか」
第2回で、組み込みの担当と、担当を使う・使わないの判断、置き場所を見ました。この回からは、自分の担当を定義する番です。担当は、.claude/agents/ に置く Markdown のファイル1つが1人です。ファイルの形は単純ですが、書き方の1行1行に意味があり、特に description が、担当が使われるかどうかを左右します。
第3回では、ファイルの形、作り方(Claude に頼むか、ファイルを書くか)、フィールドの一覧、description の書き方を扱います。
ファイルの形
担当の定義は、.claude/agents/ の Markdown 1つが1人の担当です。ファイルは次の形です。
- 2つの部分:先頭の
---で挟んだ frontmatter(設定)と、その下の本文(担当のシステムプロンプト) - 本文が担当への指示:本文が担当のシステムプロンプトになり、Claude Code の既定のシステムプロンプトは入らない(ほかに渡るものは第1回の「担当に渡るもの・渡らないもの」)
- 必須は2つ:
nameとdescription(いつ任せるか)。modelなどは任意(下の「フィールドの一覧」)
筆者が練習用に使う調査担当の例です。
---
name: infra-researcher
description: roles や inventory を読み取り専用で調べ、見つけたファイルと要点だけを返す。調べものを任せるときに使う。
tools: Read, Grep, Glob
model: haiku
effort: medium
---
あなたは調査担当です。ファイルは変更しません。
返す形:
1. 結論(1〜3行)
2. 根拠(ファイル:行)
3. 分からなかったこと(なければ「なし」)
4. 遭遇した障害(なければ「なし」)
name:担当の名前。infra-researcherのように書く。担当は、このnameだけで呼び分けられるdescription:いつ任せるか。本体が、この文を見て任せるかを決める(後の節)tools:使える道具。ここでは読み取りだけ(Read・Grep・Glob)に絞っている(第4回の「tools で「できること」を絞る」で扱います)model・effort:担当のモデルと考える量。別名で書く(第5回の「model に書ける値」、第6回の「effort も担当ごとに」で扱います)- 本文:担当への指示。役割(調査担当)、してはいけないこと(ファイルは変更しない)、返す形を書く(第4回の「返す形と、障害の報告」で扱います)
説明のため、description を短くした例です。筆者の担当の定義の全文は、第11回の「準備プロンプト」に載せます。3役の一覧は、第9回の「3役のひな形(筆者の例)」で扱います。Web も調べさせるなら、tools に WebFetch・WebSearch を足します。出典は https://code.claude.com/docs/ja/sub-agents です。
公式の文書には、次の決まりもあります。
nameは、公式の説明では、一意の識別子で256文字以内。code-reviewer・reviewer-v2のような形です。ファイル名と一致しなくてもよいnameに:は使えません。:は、プラグインの担当の名前(my-plugin:reviewer)のために予約されています

作り方:Claude に頼むか、ファイルを書く
担当の作り方は、2つです。
- 頼む:「
.claude/agents/に、読み取り専用で Haiku の調査担当を作って」のように、置き場所・役割・道具・モデルを言うと、Claude が定義を書く(公式) - 手で書く:上の形のファイルを
.claude/agents/に置く。どちらでも、できたら定義を読み、tools・modelが頼んだとおりかを確かめてから使う
/agents は案内だけ
公式の文書では、Claude Code v2.1.198 以降、/agents は「Claude に頼むか、ファイルを直接編集する」という案内を表示するだけです。担当を作る対話式のウィザード(Running と Library のタブ)は、v2.1.197 以前の動きです。公式の commands の一覧も、/agents を、Claude に担当の作成・管理を頼むか .claude/agents/・~/.claude/agents/ を直接編集するよう促す案内として載せています。
- Academy のレッスン2は、その以前の画面の説明です。
/agentsを開いて「Create new agent」を選び、次の順に進みます- スコープを選ぶ:プロジェクトレベル(現在のプロジェクトでのみ使える)か、ユーザーレベル(マシン上のすべてのプロジェクトで共有する)
- 作成方法を選ぶ:Claude に生成させる(レッスンは、これを推奨しています)か、手で書く
- ツールを選ぶ:カテゴリは、読み取り専用ツール・編集ツール・実行ツール・MCPツール・その他のツール
- モデルを選ぶ:Haiku(高速で軽量なタスクに最適)・Sonnet(速度と深さのバランス)・Opus(複雑な分析に最適)・Inherit(メインの会話で動いているモデルをそのまま使う)
- 色を選ぶ
- 事前課題でレッスン2を任意にした理由も、これです(第1回の「あわせて読みたい公式の教材」)。Academy のページには版の記載が無く、今の
/agentsと画面が合いません - Code タブの
/agentsで何が出るかは、筆者は確かめていません
書き込みの確認
.claude/ の下(.claude/agents/ も)は保護されたパスで、自動では承認されません。公式の文書は、「手動」と「編集を受け入れる」では確認が出る、と書いています(権限モードの表で、default と acceptEdits は「Prompted」)。保護されたディレクトリの例外の一覧(.claude/worktrees/、セッションのプランのファイルなど)に、.claude/agents/ は入っていません。
確認の画面には、公式の文書によると、セッションの間だけ .claude フォルダーの編集を許す選択肢(「Yes, and allow Claude to edit files in this project’s .claude folder for this session」)が出ることがあります。Code タブで、確認の画面にどんな選択肢が出るかは、筆者は確かめていません。迷ったら、内容を見てその1回だけ許可して進めます。
筆者が CLI の Claude Code 2.1.302 で、非対話の claude -p で担当の定義3つの作成を頼んだときは、3つのファイルの書き込みがどれも承認待ちになり、Claude は「許可してもらえれば続ける」と止まりました。-p には確認の画面が無いので、「承認が要る」として止まります。筆者は、プロンプトに書かれた中身のままファイルを置き、git commit しました。保護されたパスの考え方は、連載「Claude Code実践入門」第5回「6つの権限モード」にもあります。
出典は、公式の sub-agents のページ(Quickstart)、公式の permission-modes のページ(https://code.claude.com/docs/ja/permission-modes)、Academy のレッスン2です。
フィールドの一覧
frontmatter に書けるフィールドの主なものは、次のとおりです。
| フィールド | 意味 | メモ |
|---|---|---|
name・description | 必須。名前と、いつ任せるか | 全担当に書く(次の節) |
tools・disallowedTools | 使える道具・外す道具 | 役割で絞る(第4回の「tools で「できること」を絞る」) |
model・effort | 担当のモデルと考える量 | 別名で書く(第5回の「model に書ける値」、第6回の「effort も担当ごとに」) |
skills | 起動時に全文を読み込むスキル | ansible-verify(第7回の「スキルと担当の組み合わせ方2つ」) |
maxTurns・color | 最大ターン数・表示の色 | 必要なら足す |
permissionMode・isolation・memory・omitClaudeMd・background・hooks | 権限のモード・作業ツリーの分離・記憶・CLAUDE.md なし・常に裏・フック | 必要になったら公式を見る。hooks は連載「Claude Codeフック入門」 |
- フィールド名は camelCase で、綴りを間違えるとエラーなしで無視されます。 公式は、
maxTurns・disallowedToolsのように複数の語は camelCase で、表のとおりに書くこと、知らないフィールドは報告せずに無視することを書いています。読み込まれた担当の綴りの間違いは、claude --debugで見つけられます(Claude Code v2.1.296 以降。デバッグのログに、認識されないフィールド名が出ます) permissionModeは、本体が「自動」「編集を受け入れる」のとき無視されます。 公式は、本体が「権限をバイパス」のときも同じと書きます。本体のモードで担当も動き、担当のpermissionModeは使われませんmcpServersと、Academy レッスン2のツールのカテゴリ「MCPツール」は、この連載では扱いません- 公式の表には、このほかに
autoCompactWindow・initialPrompt・experimentalなどのフィールドもあります。この連載では使いません - プラグインの担当は、
hooks・mcpServers・permissionModeが無視されます(第2回の「担当の置き場所と優先順位」)
出典は https://code.claude.com/docs/ja/sub-agents です。
description は「いつ任せるか」と「何を渡すか」
本体は、全担当の名前と description を見て、任せるかを決めます。公式の文書は、「Claude は各担当の description を使って、いつタスクを任せるかを決める。担当を作るときは、明確な description を書いて、Claude がいつ使うかを分かるようにする」と書いています。任せるときの依頼文も、description を手がかりに書かれます。

- 依頼文を具体的にする:「レビューするファイルを正確に渡すこと」「引用できる出典を返すこと」のように、渡すものと返すものを書く(Academy レッスン3)。description は、担当がいつ動くかを決めるだけでなく、担当に何をするよう指示するかも形作る、とレッスン3は説明します。上の例の「roles や inventory を読み取り専用で調べ、見つけたファイルと要点だけを返す」は、何を調べ、何を返すかを書いています
- 自分から任せてほしいとき:公式の例は「Use proactively after code changes.」(description の例:
Expert code reviewer. Use proactively after code changes.)。Academy のレッスン2は、依頼しなくても任せてほしいときは、description に「proactively」という語を含めるよう書いています。日本語の description で効くかは、筆者は Code タブでは確かめていません - 短く、1行で:description は文脈の場所を取ります。公式は「短く保つ」ように書き、組み込みを除く全担当の description の合計が15,000トークンを超えると、起動時に警告が出ます(名前と description を数えます。警告が出ても、担当はすべて読み込まれます)。「1行でなければならない」は Academy の記述(改行が要る場合は
\nを使う)で、公式に同じ記述は見つかっていません(公式の例は1行です) - 名前を言わない依頼:筆者の記録では、同じ依頼でも、選ばれる担当が変わりました。「roles/ntp の tasks はどこで定義されている?」と、担当の名前を言わずに頼むと、CLI の Claude Code 2.1.289(2026年10月17日)では、自作の担当ではなく組み込みの Explore が選ばれました(description に同じ言い回しがあっても、です)。CLI の 2.1.302(2026年10月18日、
claude -p)では、自作の infra-researcher が選ばれました(どちらの版でも、担当の description には「どこで定義されている?」という言い回しが入っていたので、選ばれた理由は断定できません。全文は第11回の「準備プロンプト」)。名前を言わない依頼では、どの担当が選ばれるかは決まりません - 確実に使うなら:担当の名前を言う、または
@で選ぶ(呼び方は、第7回の「担当の呼び方3つ」で扱います) - description が無い定義は、読み込まれません。 筆者の CLI 2.1.289 では、description の無い定義は担当の一覧に出ず、エラーも出ませんでした。公式の文書も、
nameはあるがdescriptionが無いファイルは読み飛ばし、理由はデバッグのログに書く、と説明します。nameが無いファイルは、担当ではなく「担当の隣に置いた文書」として扱われます(第4回の「反映のタイミングと、読み込まれないとき」で扱います)
冒頭の2つ目の相談が、これです。本体は description を手がかりに任せるかを決めるので、「いつ使うか」「何を渡し、何を返すか」を書きます。 確実に使いたいときは、名前を言います。
出典は、Academy のレッスン2・3(https://academy.claude.com/ja/courses/introduction-to-subagents/designing-effective-subagents)と、公式の sub-agents のページです。
考えてみよう
- 自分の作業から、担当にしたい作業を1つ選び、
nameとdescriptionを書いてみてください。description に、いつ使うかと、何を渡し、何を返すかが入っていますか - 上の調査担当の本文には、「返す形」と「遭遇した障害」の欄があります。自分の担当には、どんな返す形が要りますか。(ヒント:本体が次に何をするかを考えます)
.claude/agents/に自作の担当を置くとき、確認の画面に出るのはどんな選択肢でしたか。その1回だけ許すか、セッションの間.claudeの編集を許すか、どちらにするか理由を言えますか
ヒント:1は「description は『いつ任せるか』と『何を渡すか』」、2は「ファイルの形」(返す形は、第4回の「返す形と、障害の報告」で詳しく)、3は「書き込みの確認」の節を見直してください。
まとめ
- 担当の定義は、
.claude/agents/の Markdown 1つ。frontmatter(設定)と本文(担当のシステムプロンプト)の2つの部分。必須はnameとdescription - 作り方は、Claude に頼むかファイルを手で書くか。どちらでも、できたら
tools・modelが頼んだとおりかを確かめる。/agentsは v2.1.198 以降、案内を表示するだけ .claude/の下は保護されたパス。「手動」「編集を受け入れる」では確認が出る。確認の画面には、セッションの間だけ許す選択肢が出ることがある(公式)- フィールド名は camelCase で、綴りを間違えるとエラーなしで無視される。
--debugで見つけられる(v2.1.296 以降) - 本体は description を見て任せるかを決める。いつ使うか・何を渡し何を返すかを書く。合計が15,000トークンを超えると警告。名前を言わない依頼では、選ばれる担当が決まらないので、確実に使うなら名前を言う
次回は、tools で担当ができることを絞る方法、返す形と障害の報告、定義の反映のタイミングと、読み込まれないときを扱います。
連載「Claude Codeサブエージェント入門」全13回
全回の目次と、読む順番・目的別の読み方は、Claude Codeサブエージェント入門の入口のページにまとめています。
- サブエージェントとは
- 組み込みの担当と使い分け
- 担当を定義する(この記事)
- toolsと返す形
- 担当のモデルの決まり方
- 役割とモデル・effort
- スキルから担当を呼ぶ
- 順に使う・前と裏
- ログの要約とレビューの担当
- 費用を測って小さく使う
- 演習(前編):準備
- 演習(中編):読み込む・呼ぶ・モデルを見る
- 演習(後編):レビュー・スキル・費用


コメント