Claude Code subagent missing from the list or never called
When a subagent in .claude/agents is not listed or never delegated to, check the file location, frontmatter, debug log and restart conditions in this order.
If Claude says it has no subagent by the name you just created, the file was most likely skipped silently. The results below come from eight deliberately broken files and one valid file, tried on Claude Code 2.1.302.
[1] List the subagent names Claude can see.
$ claude -p "List the name of every subagent type available to your Agent/Task tool, one per line, nothing else." --max-turns 2badyamlbrokenyamlclaudeExploregeneral-purposegood-reviewerPlanstatusline-setup[2] If you meant to check with /agents, look at the version first. Per the official docs, v2.1.197 and earlier open a wizard that lists and creates subagents; later versions print a notice only. This is claude -p "/agents" on 2.1.302.
$ claude -p "/agents"The /agents wizard has been removed. Ask Claude to create or update subagents for you (e.g. "create a code-reviewer subagent that ...").The notice goes on to tell you to edit .claude/agents/ or ~/.claude/agents/ directly. Use the question in step 1 or the debug log in step 3 to see the list.
[3] The reason a file was dropped is in the debug log. Nothing appears in the session itself.
$ claude -p "hi" --max-turns 1 --debug-file /tmp/agents.log$ grep -E "Agent file|agents/" /tmp/agents.log# output trimmed to the relevant lines[DEBUG] Failed to stat directory /home/user/.claude/agents: ENOENT: no such file or directory, stat '/home/user/.claude/agents'[DEBUG] Agent file /srv/app/.claude/agents/nodesc.md is missing required 'description' in frontmatter[WARN] Agent file /srv/app/.claude/agents/typo.md has a frontmatter key Claude Code does not recognize or apply: "descripton" (did you mean "description"?)[ERROR] YAML frontmatter in /srv/app/.claude/agents/rb.md failed to parse and was ignored: YAML Parse error: Unexpected EOFThe first line only says ~/.claude/agents does not exist. The three below it are skipped files.
[4] Fix the frontmatter. name and description are the only required fields. Results per test file:
| File content | Listed | Log |
|---|---|---|
valid name and description | yes | none |
no name | no | nothing logged |
blank first line, --- on line 2 | no | nothing logged |
name but no description | no | missing required 'description' |
descripton typo | no | WARN with "did you mean" |
| unclosed quote · tab indentation | no | ERROR · YAML Parse error |
The docs say a file without name is treated as documentation kept beside your agents; so is a file whose opening --- is not on line 1. That is why the log stays quiet. For these two, the log gives no hint, so check the top three lines of the file by eye.
---name: code-reviewerdescription: Reviews a diff for bugs. Use after code changes.---You are a code reviewer. Report only problems you can point to in the diff.[5] Check the location. Locations and priority from the docs:
| Location | Scope | Priority |
|---|---|---|
| Managed settings | Organization-wide | 1 (highest) |
--agents CLI flag | Current session | 2 |
.claude/agents/ | Current project | 3 |
~/.claude/agents/ | All your projects | 4 |
Plugin's agents/ directory | Where the plugin is enabled | 5 (lowest) |
Folders are read recursively, including subfolders. For the project scope, Claude Code walks up from the working directory and scans every .claude/agents/ on the way to the repository root. Running from proj/sub/deep still listed the agents in proj/.claude/agents/ (the test folder was not a git repository). An .claude/agents/ placed only in a subfolder is visible when you run from that folder; this was not tested.
[6] When two definitions share a name, the higher priority wins. Defining good-reviewer again with --agents and asking for its description returned the flag's text, not the file's.
$ claude -p "Quote verbatim the description of the subagent type good-reviewer from your Agent/Task tool, nothing else." --max-turns 2 --agents '{"good-reviewer":{"description":"FROM-FLAG override","prompt":"x"}}'FROM-FLAG overrideProject versus personal folder (3 versus 4) was not tested, to avoid touching the personal folder on this machine; follow the table. Within one folder, the docs say which file is used is not defined (filesystem read order).
[7] If you created the file after the session started, check whether a restart is needed. Per the docs, Claude Code watches .claude/agents/ and ~/.claude/agents/ and picks up changes within a few seconds. Restart in these three cases:
- You created the first file in an
agentsfolder that did not exist when the session started. - You added or edited
.claude/agents/inside a folder added with--add-diror/add-dir. - The session was started with
--disable-slash-commands.
[8] If the agent is listed but never chosen automatically, the problem is description. Claude decides delegation from it, so state when to use it ("Use after code changes"). If that is not enough, name the agent in your request.
Skills use a different folder and different rules; see Claude Code skill not showing up or never used.