Five ways a subagent file is skipped, and every frontmatter field

You put a file in .claude/agents/ and the subagent is never used.

Most often the file was never loaded at all — and the awkward part is that nothing appears in the session to say so.

Five ways a file is skipped silently

Any of these in the frontmatter and the file is not treated as a subagent.

Condition	What happens
No `name`	Treated as documentation — a note kept beside your agents
The opening `---` is not the first line	Read as having no frontmatter, so documentation again
A `name` starting with `-` or containing `:`	The whole file is skipped. The reason goes to the debug log
A `name` but no `description`	Skipped. Reason in the debug log
YAML that does not parse	Nothing is read, the file is skipped, parse error in the debug log

What they share is that the session says nothing. To see the reason you need --debug.

: is unavailable because it is reserved for plugin-scoped identifiers such as my-plugin:reviewer.

Plugin subagents are the exception: one with no name, or with frontmatter that does not parse, still loads — under its filename.

Checking before a session

Frontmatter that fails to parse can be found with claude plugin validate.

claude plugin validate .claude/agents
claude plugin validate ~/.claude/agents

It looks only at the directory you name, and it does not flag a file whose frontmatter parses but has no name.

Every frontmatter field

Only name and description are required.

Field	What it decides
`name`	The identifier: lowercase and hyphens. It need not match the filename. Hooks receive it as `agent_type`
`description`	When Claude should delegate here. This is what the delegation decision reads
`tools`	Which tools it may use. Omit it and it inherits everything available to subagents
`disallowedTools`	Tools removed from the inherited or specified list
`model`	`sonnet` / `opus` / `haiku` / `fable` / a full model ID / `inherit`
`permissionMode`	`default` / `acceptEdits` / `auto` / `dontAsk` / `bypassPermissions` / `plan` / `manual`
`maxTurns`	Where to stop. Output cut short is marked as partial and can be resumed
`skills`	Skills preloaded at startup — the full content, not just the description
`mcpServers`	MCP servers available to it, by name or defined inline
`hooks`	Lifecycle hooks scoped to this subagent alone
`memory`	`user` / `project` / `local`. Learning that survives the session
`background`	`true` keeps it in the background even when Claude asks for the foreground
`effort`	`low` / `medium` / `high` / `xhigh` / `max`. Which levels exist depends on the model
`isolation`	`worktree` runs it inside its own copy of the repository
`color`	Display colour in the task list. Eight choices
`initialPrompt`	Submitted as the first user turn when this runs as the main session agent (`--agent`)
`experimental`	Map of experimental options. `cacheTtl` goes in here

One thing to watch in `tools`

If no entry in the list resolves to a tool, the subagent usually fails to launch, with an error naming the entries.

Listing Skill to preload skills is the wrong field — use skills.

`cacheTtl` belongs inside `experimental`

At the top level it does nothing. This is the easy one to get wrong.

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

Only 5m and 1h are read; any other value is ignored. 1h is also ignored while your subscription is using usage credits. And the field is read only from subagent files.

Fields ignored for plugin subagents

permissionMode, mcpServers and hooks are ignored when the subagent comes from a plugin.

When a change does not take effect

~/.claude/agents/ and .claude/agents/ are watched, so an edit applies to the next delegation within a few seconds. No restart.

Three cases still need one.

The first agent file in a scope, when the agents directory itself is new — the watcher only covers directories that existed when the session started
.claude/agents/ inside a directory added with --add-dir or /add-dir, which is not watched at all
A session started with --disable-slash-commands, which watches neither

Checking it

All five conditions are mechanically detectable, and so are duplicate names — which of the two loads is decided by an undocumented filesystem read order.

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

Every finding cites its source. A rule that cannot be cited is not written.

The sets of valid values for fields like model and color are deliberately not checked: a checker holding a snapshot would warn on every value added after it.

Source

https://code.claude.com/docs/en/sub-agents

Based on a snapshot taken 2026-09-04.

The workflow itself is available

Quartet, the four-persona version, is published free under MIT. Quintet adds a UI Designer persona, review criteria, a per-Issue parallel execution script, and a 10-chapter guide.

See the free version Product page