サブエージェントのファイルが読み込まれない5つの条件と、frontmatter の全項目
.claude/agents/ にファイルを置いたのに、そのサブエージェントが呼ばれない。
いちばん多いのは、ファイルが読み込まれてすらいないケースです。 そして厄介なことに、セッションには何も出ません。
黙って飛ばされる5つの条件
frontmatter に次のどれかがあると、そのファイルはサブエージェントとして扱われません。
| 条件 | 何が起きるか |
|---|---|
name が無い |
ドキュメントとして扱われる。 エージェントの横に置いたメモと同じ |
開きの --- が1行目でない |
frontmatter が無いものとして読まれ、やはりドキュメント扱い |
name が - で始まる／: を含む |
ファイルごとスキップ。 理由はデバッグログにだけ出る |
name はあるが description が無い |
スキップ。 理由はデバッグログ |
| YAML として壊れている | 何も読まれずスキップ。パースエラーはデバッグログ |
共通しているのは「セッション側には出ない」こと。 理由を見るには --debug が要ります。
: が使えないのは、プラグイン用の識別子（my-plugin:reviewer）に予約されているためです。
なおプラグインのサブエージェントは例外で、name が無くても
YAML が壊れていても、ファイル名で読み込まれます。
先に確かめる
パースできない frontmatter は claude plugin validate で見つけられます。
claude plugin validate .claude/agents
claude plugin validate ~/.claude/agents
ただし指定したディレクトリしか見ません。そして
「パースはできるが name が無い」ファイルは出ません。
frontmatter に書ける項目
必須は name と description の2つだけです。
| 項目 | 何を決めるか |
|---|---|
name |
識別子。小文字とハイフン。ファイル名と一致していなくてよい。hook には agent_type として渡る |
description |
どういうときに任せるか。Claude はこれを見て委譲を判断する |
tools |
使えるツール。省くと、サブエージェントが使える全部を継承 |
disallowedTools |
継承／指定した一覧から取り除くツール |
model |
sonnet / opus / haiku / fable / 完全なモデル ID / inherit |
permissionMode |
default / acceptEdits / auto / dontAsk / bypassPermissions / plan / manual |
maxTurns |
何ターンで打ち切るか。打ち切られた出力は部分的と印がつく |
skills |
起動時に読み込ませる Skill。説明だけでなく本文ごと入る |
mcpServers |
使える MCP サーバ。名前の参照でも、その場での定義でもよい |
hooks |
このサブエージェントにだけ効く hook |
memory |
user / project / local。セッションをまたいだ記憶 |
background |
true で常に背景実行 |
effort |
low / medium / high / xhigh / max。使える段階はモデル次第 |
isolation |
worktree で、リポジトリの複製の中で動く |
color |
一覧での表示色。8色 |
initialPrompt |
--agent で主セッションとして動かすとき、最初のユーザー発話として自動で入る |
experimental |
実験的な設定のマップ。cacheTtl はここに書く |
tools を書くときの注意
一覧のどれもツールに解決できないと、起動そのものに失敗します（該当の項目名を挙げたエラーが出る）。
Skill を先読みさせたいときに Skill を並べるのは誤りで、skills を使います。
cacheTtl は experimental の中
上の階層に書いても効きません。 よく間違える場所です。
---
name: repo-auditor
description: 大きなリポジトリを調べて報告する
experimental:
cacheTtl: 1h
---
5m か 1h だけが読まれ、それ以外の値は無視されます。
サブスクリプションがクレジットを消費している間は 1h も無視されます。
そしてこの項目はサブエージェントのファイルからしか読まれません。
プラグインのサブエージェントでは効かない項目
permissionMode / mcpServers / hooks の3つは、
プラグインのサブエージェントでは無視されます。
変更が反映されないとき
~/.claude/agents/ と .claude/agents/ は監視されているので、
書き換えれば数秒で次の委譲から効きます。再起動は要りません。
要る場合が3つあります。
- そのスコープで最初の1個目を作ったとき（監視はセッション開始時に存在した
ディレクトリだけが対象なので、
agentsディレクトリごと新設した場合） --add-dir//add-dirで足したディレクトリの中の.claude/agents/（そもそも監視されていない）--disable-slash-commandsで始めたセッション（一切監視しない）
検査する
上の5条件は機械で見つけられます。名前の重複も出ます （どちらが読まれるかはファイルシステムの読み出し順で決まり、文書化されていません）。
npx @quintetkit/ccheck
error .claude/agents/a.md:2
`name: bad:name` is not loaded. A name containing `:` or starting with `-` is invalid.
why: https://code.claude.com/docs/en/sub-agents
指摘には必ず出典が付きます。 根拠を示せないものはルールにしていません。
model や color のような値の一覧は検査していません。
新しい値が増えるたびに誤検出するからです。
出典
https://code.claude.com/docs/en/sub-agents
2026-09-04 に取得したスナップショットを元にしています。