Claude Code subagents
Build a Claude Code subagent file with valid frontmatter: tools, model, permissionMode, hooks, memory. Every field explained from the official docs.
Locations and precedence
| Location | Scope | Priority |
|---|---|---|
Managed .claude/agents/ | Organization | 1 (highest) |
--agents CLI flag | Session | 2 |
Project .claude/agents/ | Project | 3 |
~/.claude/agents/ | User | 4 |
Plugin agents/ | Plugin | 5 |
Required fields
name and description are required. Field names are camelCase and must match exactly; unknown fields are silently ignored.
Common mistakes
- Frontmatter must start on line 1 with
--- - Names must not contain
:or start with- - Filename does not need to match
name - New
agentsdirectories may need a restart
FAQ
- Where do subagent files go?
- Project agents live in .claude/agents/ (walked up to the repo root). User agents live in ~/.claude/agents/. Managed and plugin locations also exist with higher or lower precedence per the official docs.
- Why is my subagent not loading?
- Common causes include invalid YAML frontmatter, a missing closing --- line, a name that contains : or starts with -, or a file outside the scanned agents directories. New agents directories may require a restart.
- Which model does a subagent use?
- Set model in frontmatter to sonnet, opus, haiku, fable, a full model ID, or inherit. If omitted, resolution follows the order in the Claude Code docs (agent file, then settings, then defaults).
- Can a subagent spawn subagents?
- Yes, if the Agent tool is available to subagents and not removed via tools or disallowedTools. The docs rename Task to Agent in v2.1.63.
- Subagents vs skills?
- Subagents are separate agent contexts with their own prompt and optional tool restrictions. Skills are reusable instruction bundles that can be preloaded via the skills field. They solve different problems.