guide12 min read2mo ago

Claude Code Subagents in 2026: The Config Reference

Eighteen frontmatter fields, five locations, and the failure modes nobody documents: how Claude Code actually loads a .claude/agents file, which fields it consults, and the five ways it skips yours without saying a word.

Claude Code Subagents in 2026: The Config Reference
claude codeclaude code subagentssubagents.claude/agentsagent configurationclaude code agents

Key Takeaways
  • Five frontmatter problems make Claude Code skip your agent file without reporting it in the session. A missing description and an opening --- that is not line 1 are two of them.
  • disallowedTools resolves before tools, and an entry with a specifier such as Bash(git push *) removes the whole Bash tool, not the matching commands.
  • A subagent can never ask you anything. AskUserQuestion, EndConversation, EnterPlanMode, ScheduleWakeup and Workflow are removed from every subagent, so "check with me if unsure" in the prompt body is decoration.
  • Conversation history does not reach a subagent. Neither does your output style, your auto memory, or the parent's context window size.
  • Eighteen frontmatter fields, five load locations, and name is the identity: nested folders under .claude/agents/ change nothing except which definition wins.

18 fields · 5 locations · 5 silent-skip conditions · every value quoted from the reference

You wrote a subagent file, restarted Claude Code, asked for exactly the job it was built for, and got the main agent doing the work itself. No error, no warning, nothing in /agents. The usual next move is to rewrite the description until something happens.

That is often the wrong layer. Claude Code skips a malformed agent file without reporting it in the session at all, and there are five ways to trip that, one of which is putting a comment above the opening ---. A file that is never loaded and a file whose description is too vague look identical from the prompt.

So this is the reference for how Claude Code subagents are actually loaded and resolved: the five locations and which one wins, all eighteen frontmatter fields, the tool resolution order, what reaches the subagent's context and what never does, and the places where a field you wrote in good faith is accepted and then ignored.

Every field name, default, version number and precedence claim below is checked against Anthropic's subagent and settings references rather than other write-ups, which matters here because the popular guides were written in May 2026 and the field list has grown since.

One bright violet node on an off-white field branching out along thin connector lines into five smaller violet nodes of the same colour
Five load locations, eighteen fields, and five ways the file you wrote is never read.

Where Claude Code Looks for Agent Files

Table of the five locations Claude Code loads agent files from, highest priority first: managed settings deployed by an admin organization-wide, the agents CLI flag for the current session only passed as JSON at launch, the project .claude/agents directory, the user level home .claude/agents directory for all your projects, and lowest a plugin agents directory where the plugin is enabled
Project agents are found by walking up from your working directory. The closest definition wins.

A subagent is a Markdown file: YAML frontmatter for configuration, and the body becomes the system prompt. That part every guide gets right. The part that decides whose file wins is the load order.

PriorityLocationScopeCreated by
------------
1 (highest)Managed settingsOrganization-wideDeployed by an admin
2--agents CLI flagCurrent session onlyJSON passed at launch, never written to disk
3.claude/agents/Current projectYou, or /agents
4~/.claude/agents/All your projectsYou, or /agents
5 (lowest)A plugin's agents/ directoryWhere the plugin is enabledInstalled with the plugin

Three details in that table are worth more than the table. Project agents are found by walking up from your current working directory, so a subagent defined in a monorepo package beats the same name defined at the repo root when you are working inside that package. Directories are scanned recursively, and subdirectory structure does not affect identity: name is the only identifier, so filing agents under .claude/agents/backend/ organises you and changes nothing about resolution. And plugin agents carry scoped identifiers, plugin-name:agent-name, which is why your own agent names cannot contain a colon.

If two files in nested directories declare the same name, the one closest to your working directory is the definition you get. That is a feature when you meant it and a long debugging session when you did not.

The Full Frontmatter Reference

The Claude Code documentation page titled Create custom subagents, with a contents list covering supported frontmatter fields, choosing a model, restricting which subagents can be spawned, preloading skills into subagents and defining hooks for subagents
The reference every field name, default and version number on this page is quoted from.

Only name and description are required. The other sixteen fields are where the behaviour lives, and most published guides document between six and thirteen of them.

FieldRequiredValuesWhat it does
------------
nameYeslowercase letters and hyphensIdentity. Also the agent_type hooks match on. Cannot contain :
descriptionYesstringWhen Claude should delegate here. This is the delegation trigger
toolsNocomma list or arrayAllowlist. Inherits everything available if omitted
disallowedToolsNocomma list or arrayDenylist, applied before tools
modelNosonnet, opus, haiku, fable, a full model ID, or inheritModel for this subagent
permissionModeNodefault, acceptEdits, auto, dontAsk, bypassPermissions, plan, manualPermission behaviour. Ignored for plugin subagents
maxTurnsNointegerStops after N agentic turns and marks the run partial
skillsNoarray of stringsPreloads full skill content at startup
mcpServersNoarray or objectMCP servers for this subagent. Ignored for plugin subagents
hooksNoobjectPreToolUse, PostToolUse, Stop. Ignored for plugin subagents
memoryNouser, project, localPersistent memory scope across sessions
backgroundNobooleanKeeps the subagent backgrounded even when Claude wants it in front
omitClaudeMdNobooleanSkips user, project and local CLAUDE.md. Needs v2.1.271+
effortNolow, medium, high, xhigh, maxEffort override. Inherits the session's level if omitted
isolationNoworktreeRuns in a temporary git worktree
colorNored, blue, green, yellow, purple, orange, pink, cyanDisplay colour only
initialPromptNostringAuto-submitted first turn when the agent runs as the main session
experimentalNoobjectcacheTtl of 5m or 1h

A minimal file that does something useful:

---
name: migration-checker
description: Checks database migrations for destructive statements. Use proactively before any migration is applied.
tools: Read, Grep, Glob
model: haiku
memory: project
---

You review migration files. Flag DROP, TRUNCATE and NOT NULL additions on
populated tables. Quote the file and line. Do not edit anything.

Note what is not in that file: a permission rule. Subagent tool scoping and Claude Code's permission rules are separate systems, and tools is the one that decides which tools the subagent can see at all.

Five Ways a Subagent File Is Skipped in Silence

Table of five frontmatter conditions that make Claude Code skip an agent file without saying so: no name field, an opening three-dash line that is not the first line of the file, a name starting with a hyphen or containing a colon, a name present with the description missing, and YAML that does not parse. Four of the five write to the debug log and none of them appear in the session
A licence header above the frontmatter is enough. Run claude plugin validate after every edit.

This is the section the other guides do not have, and it explains most "my subagent is ignored" reports. Claude Code skips a file in a project, user or managed agents directory when the frontmatter has any of these problems, and it does not tell you in the session.

ConditionWhat Claude Code doesWhat you see
---------
No name fieldTreats the file as documentation kept beside your agentsNothing. The file is prose as far as the loader is concerned
Opening --- is not the first lineReads the file as having no frontmatter, treats it as documentationNothing. A licence header or a blank line is enough to do this
name starts with - or contains :Skips the file, writes an error to the debug logNothing in the session
name present, description missingSkips the file, writes the reason to the debug logNothing in the session
YAML does not parseReads no fields, skips the file, logs the parse errorNothing in the session

Four of those five write something to the debug log, which is not the session output, so the only difference between them from the prompt is none at all. Since v2.1.233 there is a direct check:

claude plugin validate .claude/agents

Run it after every edit to an agent file. It takes a second and it is the only thing standing between a typo'd name and an afternoon of rewriting a description that was fine.

The same command is worth putting in a PreToolUse or commit hook if your team keeps project agents in version control, which our hooks guide has the scaffolding for.

Tools: What tools and disallowedTools Resolve To

Table of what a subagent actually gets for six tool configurations: neither field gives every inherited tool minus the always-removed set, an allowlist of Read Grep and Glob gives those three only, a denylist of Write and Edit gives everything else, a denylist entry carrying a specifier for one Bash command removes Bash entirely, an Agent allowlist naming two workers gives Read plus the ability to spawn only those two, and an MCP wildcard in the denylist removes every MCP tool
The denylist resolves first, and a specifier takes the whole tool rather than the matching command.

If you set neither field, the subagent inherits every built-in and MCP tool from the main conversation, minus a fixed set that is never available to any subagent. If you set both, the order is not the one most people assume.

disallowedTools is applied first, then tools is resolved against what is left. So a tools allowlist cannot re-admit something the denylist removed, in the same way an allow rule cannot carve an exception out of a deny rule in the permission system.

The specifier behaviour is the trap. A disallowedTools entry written as Bash(git push *) removes the whole Bash tool from the subagent, not just matching commands. If you wanted the subagent to run builds but not push, the denylist is the wrong instrument; scope tools to what it may call, or put the restriction in a PreToolUse hook.

You writeWhat the subagent gets
------
Neither fieldEvery inherited tool, minus the always-removed set below
tools: Read, Grep, GlobThose three, nothing else
disallowedTools: Write, EditEverything inherited except those two
disallowedTools: Bash(git push *)No Bash at all
tools: Agent(worker, researcher), ReadRead, plus the ability to spawn only those two subagents
disallowedTools: mcp__*Every MCP tool removed. mcp__* is valid in the denylist only

Now the fixed set. These are removed from every subagent regardless of what you write: AskUserQuestion, EndConversation, EnterPlanMode, ExitPlanMode (unless permissionMode: plan), ScheduleWakeup, TaskOutput, WaitForMcpServers, Workflow, and Agent once the depth limit is reached.

The first one has a consequence worth stating plainly: a subagent cannot ask you a question. A prompt body that says "check with the user before making assumptions" produces a subagent that makes assumptions, because the tool that would ask does not exist in its context. Put decisions the user must make in the parent conversation, and give the subagent work it can finish alone.

Background subagents are narrower still. They keep Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage and Artifact, plus all MCP tools. Anything else in your tools list is dropped for that run. Since background is the default in fork mode in interactive sessions, a subagent can quietly lose a tool you scoped it to depending on how it was started.

What Reaches the Subagent, and What Never Does

Two-column table of what loads into a subagent at startup against what never does. It gets its own system prompt and environment details, the task message, the whole CLAUDE.md hierarchy, a git status snapshot from when the parent session started, the full content of named skills and a roster of sibling agent names. It does not get the conversation history, your output style settings, auto memory, or the parent's context window size
The delegation prompt is the only channel. A decision made ten turns ago has to be restated in it.

A subagent is a fresh context, which is the entire point, and also the thing that makes delegation results feel oddly amnesiac when you were expecting continuity.

Loads at startupDoes not load
------
Its own system prompt (the file body) plus environment detailsThe conversation history
The task message Claude wrote when delegatingYour output style settings
The whole CLAUDE.md hierarchy, unless omitClaudeMd: trueAuto memory, unless the subagent has its own memory field
A git status snapshot from when the parent session startedThe parent's context window size. It uses its own model's window
Full content of any skills named in skillsAnything you said before the delegation that Claude did not restate
A roster of sibling agent names, on v2.1.206+

Two practical consequences. First, the delegation prompt is the only channel: if the subagent needs a decision you made ten turns ago, the parent has to write it into the task message. Second, that git status snapshot is from the parent's start, so a long session hands subagents a stale view of the working tree.

Persistent memory is the escape hatch when a subagent should learn across sessions. Set memory: project and it gets a directory under .claude/agent-memory//, the first 200 lines or 25KB of its MEMORY.md load automatically, and Read, Write and Edit are enabled for it whatever else you scoped. user scope writes to ~/.claude/agent-memory/, and local keeps it out of version control.

Model, Effort and the Resolution Order

The Claude Code documentation page titled Settings files and precedence, explaining that Claude Code reads settings from JSON files and that the file it reads a setting from decides who the setting applies to
The settings reference, where the subagent model environment variables are documented.

Four things can set a subagent's model, and the first match wins.

OrderSourceBeats
---------
1The model parameter passed to the Agent tool at invocationEverything
2The subagent file's model frontmatter field3 and 4
3CLAUDE_CODE_SUBAGENT_MODEL environment variable4
4The main conversation's modelNothing

model: inherit is the explicit way to say "whatever the parent is using". To force every subagent onto one model regardless of what their files say, set CLAUDE_CODE_SUBAGENT_MODEL and CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 together in your settings env block. That is the setting for a team that wants the cost floor rather than the per-agent choice.

Two inheritance details that are easy to get wrong: since v2.1.198 subagents inherit the main conversation's extended thinking setting, and forks skip model selection entirely and run on the parent's model. The effort field is separate from the model and inherits the session's level when omitted, so a haiku agent at max effort and an opus agent at low are both configurations you can write and probably do not want.

Delegation: description Is the Field Doing the Work

Automatic delegation matches your task against each subagent's description. Everything else in the file is what happens after the match, so a precise description is worth more than a long prompt body.

Three things make it fire reliably. Name the trigger condition rather than the capability ("use after any change to files under migrations/" beats "database expert"). Include "use proactively" if you want Claude to reach for it unprompted. And keep it short, because the combined descriptions of your non-built-in subagents have a 15,000-token budget, past which Claude Code warns at startup with the total. Twenty agents with a paragraph each is how teams get there.

When you want certainty rather than matching, skip delegation:

InvocationBehaviour
------
"Use the test-runner subagent to fix failing tests"Claude decides whether to delegate
@agent-test-runnerGuarantees that subagent runs
claude --agent code-reviewerThat agent is the session
"agent": "code-reviewer" in .claude/settings.jsonSame, as a project default
claude --agents '{...}' with JSONSession-only agents, never written to disk

The --agents JSON form accepts the same fields as the frontmatter, with the system prompt under a prompt key. It is the right tool for CI, where you want an agent definition that ships with the pipeline rather than the repo, and it pairs with the Claude Agent SDK for programmatic runs.

Limits, Depth, and When Delegation Costs More Than It Saves

Two numbers bound how far this scales, and both are environment variables rather than settings fields.

LimitDefaultChange with
---------
Subagent nesting depth below the main conversation3 layersCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (set 1 to disable nesting)
Concurrent subagents in a session20CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS

Hitting the concurrency ceiling fails the spawn with Concurrent subagent limit reached, which is at least a visible error. Hitting the depth limit is quieter: the Agent tool is simply removed from the subagent's tool set, so it does the work itself instead of delegating, and the only symptom is a slower, longer turn.

The judgement call underneath all of this has not changed since the agent teams guide, and Anthropic's own Claude Code best practices frames it the same way: each delegation pays a fresh system prompt, a fresh CLAUDE.md load and a task message before it does anything useful. That is worth it for a search across many files whose answer is a paragraph, or for work you want isolated in a worktree. It is a loss for a two-file edit you could have made directly. Scoped tools and a small model cut the per-delegation cost; they do not make an unnecessary delegation free.

Start from an agent file that already loads
The fastest way past the five silent-skip conditions is to copy a file that parses. Skiln indexes installable Claude agents, skills, commands and MCP servers with their real install paths and the tools each one expects. Browse agents · Browse skills · Generate a config
Disclosure: Skiln publishes this article and runs the directory it links to.

If you want the curated end of that rather than the whole index, our nine subagents worth installing is the shortlist, and each entry there is a file you can drop into .claude/agents/ and validate with the command above.

Every field name, default, limit and version number above comes from Anthropic's custom subagents reference and the settings files and precedence page, with the hook event names from the hooks guide. Where another write-up disagrees with a value here, check the date on it: most of the ranking guides predate half the fields in the table above.

Frequently Asked Questions

Why is my subagent being ignored with no error message?▾
Most often the file is not being loaded at all. Claude Code skips an agent file without reporting it in the session when it has no name field, when the opening --- is not the first line, when the name starts with a hyphen or contains a colon, when there is a name but no description, or when the YAML does not parse. Run claude plugin validate .claude/agents to see which one it is.
Where do I put a subagent file, and which location wins?▾
Project agents go in .claude/agents/ and personal ones in ~/.claude/agents/. Precedence runs managed settings, then the --agents CLI flag, then project, then user, then plugin agents. Project agents are found by walking up from your working directory, so when two nested directories define the same name, the definition closest to where you are working is the one used.
What is the difference between tools and disallowedTools?▾
tools is an allowlist and disallowedTools is a denylist, and the denylist is applied first, with tools then resolved against what remains. A denylist entry with a specifier, such as Bash(git push *), removes the whole Bash tool from the subagent rather than only the matching commands, so use tools scoping or a PreToolUse hook when you want partial access.
Can a subagent ask me a question before it decides something?▾
No. AskUserQuestion is removed from every subagent, along with EndConversation, EnterPlanMode, ScheduleWakeup, TaskOutput, WaitForMcpServers and Workflow. Writing 'ask the user if unsure' into the prompt body changes nothing, because the tool that would ask is not in the subagent's context. Keep decisions that need you in the parent conversation.
Does a subagent see the conversation so far?▾
No. A non-fork subagent starts with its own system prompt, the task message Claude wrote when delegating, the CLAUDE.md hierarchy, a git status snapshot from the parent session's start, and any preloaded skills. Conversation history, output style settings and auto memory do not reach it, so anything it needs must be in the delegation prompt.
How do I force every subagent onto a cheaper model?▾
Set CLAUDE_CODE_SUBAGENT_MODEL to the model alias you want and CLAUDE_CODE_SUBAGENT_MODEL_FORCE to 1 in your settings env block. Without the force flag the environment variable sits below each agent file's own model field in the resolution order, which runs invocation parameter, then frontmatter, then environment variable, then the main conversation's model.
How many subagents can run at once, and how deep can they nest?▾
Twenty concurrent subagents by default, after which a spawn fails with 'Concurrent subagent limit reached', and three layers of nesting below the main conversation. Change them with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS and CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. At the depth limit the Agent tool is simply removed, so the subagent does the work itself instead of failing.

Stay in the Loop

Join 1,000+ developers. Get the best new Skills & MCPs weekly.

No spam. Unsubscribe anytime.