What a subagent knows when it starts, and what comes back
Ask Claude a broad question about your codebase and it hands the search to Explore without being asked. Explore does the reading in its own context window. When it finishes, a summary lands in your chat, and the files it opened and the commands it ran stay behind.
A subagent can't see your conversation so far, the skills you've invoked or any file Claude has already read. It gets its own tool access and permissions, and a system prompt made of the agent's own prompt plus environment details Claude Code appends, not the Claude Code system prompt (Anthropic's subagent guide).
Your CLAUDE.md files do come along, with a snapshot of git status and the full text of any skill the agent preloads. A long CLAUDE.md therefore loads again, and takes up context again, in every custom subagent's window. Explore and Plan skip CLAUDE.md and the git snapshot.
Claude weighs your request against each description and the current context
A new context window opens with the agent's own prompt and tools
The subagent works in the background
You keep working meanwhile. If it needs a permission, the prompt appears in your main session and names the subagent asking.
Source: Claude Code docs: Create custom subagents (read November 3, 2026)
| Subagent | What Claude uses it for | Tools |
|---|---|---|
| Explore | Searching and analyzing a codebase without making changes | Read-only: Write and Edit are denied |
| Plan | Gathering context in plan mode before Claude presents a plan | Read-only: Write and Edit are denied |
| General-purpose | Tasks that need both exploration and changes, or several dependent steps | Every tool available to subagents |
Make one: a sample agent file
One file holds the whole definition. YAML at the top sets the name, the description and limits such as tools and model, and the Markdown below becomes the subagent's system prompt. Only name and description are required. The field reference lists the optional ones, from maxTurns and skills to memory and isolation.
Our sample, written for this post, checks links in a docs folder, the kind of simple job Anthropic suggests handing to Haiku. Its tools line lists only Read, Grep and Glob, so Claude Code itself stops the agent from editing a file. A "don't edit anything" line in the prompt would only be a request.
---
name: docs-link-checker
description: Checks relative links and anchors in Markdown files under docs/ and reports broken ones. Use proactively after editing files in docs/.
tools: Read, Grep, Glob
model: haiku
---
You check links in the Markdown files you are given, or in docs/ if none are named.
1. Find every relative link and every #anchor.
2. Confirm each target file exists and each anchor matches a heading in it.
3. Skip links that start with http:// or https://.
Reply with one line per broken link: file, line, target and the reason.
If every link resolves, reply "All links resolve" and nothing else.
nameis what Claude and hooks see. It can't contain a colon, and it doesn't have to match the file name.toolsis an allowlist. Leave it out and the subagent inherits every tool available to subagents.modelacceptssonnet,opus,haiku,fable, a full model ID, orinheritfor the main conversation's model.
- Make a
.claude/agents/folder in your project for an agent the team shares, or use~/.claude/agents/for one you want in every project. - Save the sample there as
docs-link-checker.md. - Ask for it by name, as in "Use the docs-link-checker subagent on docs/".
Where agent files live, and what to check when one misbehaves
If /agents prints a one-line reminder instead of opening a menu, nothing is broken. On current versions it tells you to ask Claude, or to edit .claude/agents/ and ~/.claude/agents/ directly. The interactive wizard belongs to v2.1.197 and earlier.
Asking Claude is the route the guide's own quickstart takes: describe the agent and where to save it, for example a read-only code improver in ~/.claude/agents/ that uses Sonnet. Then open the file and check that its frontmatter matches what you asked for, the model included.
Claude Code reads agent files from five places, and when two definitions share a name, the higher-priority location wins. Inside one .claude/agents/ folder and its subfolders there's no ranking: if two files declare the same name, Claude Code loads only one, in whatever order the filesystem returns them. Keep names unique.
A misspelled field fails quietly. Field names are camelCase, and Claude Code ignores a field it doesn't recognize without reporting an error. If maxTurns or permissionMode seems to do nothing, check its spelling first.
An agent that came in a plugin, the package that carries agents between teams along with skills, hooks and MCP servers, has one more trap. For security, a plugin's agents ignore the hooks, mcpServers and permissionMode fields, so a setting in one of those does nothing there.
A screenshot of X's own embed of the 2025 announcement, taken on 3 November 2026, in US Pacific time and without its video. Select it to open the post on X.
How Claude picks a subagent, and how you pick one yourself
Of the things Claude weighs before it delegates, the description is the only one you write in advance. Ending it with "Use proactively" and a situation, as the sample does, makes Claude more likely to reach for the agent unasked.
Keep each description short anyway. Once all your subagents' descriptions together pass 15,000 tokens, Claude Code warns at startup, though it still loads every one.
- Ask in plain words: "Use the test-runner subagent to fix failing tests". Claude typically delegates, but it's still Claude's call.
- Type
@and pick the subagent from the typeahead, the way you'd pick a file. That one runs for certain, though Claude still gets your full message and writes its task prompt. - Start the session with
claude --agent code-reviewer, and the main thread becomes that agent, with its tool limits and model. Settingagentin.claude/settings.jsonmakes it a project's default.
Subagent or skill, and when a subagent is worth it
A skill loads into your current conversation and adds to its context. It's reusable content, such as instructions or reference material.
A subagent's skills field preloads the full text of the skills it names, and a skill set to context: fork runs inside a subagent.
A subagent pays off on independent jobs that can run at the same time, and on long output that should stay out of your chat, such as a full test run. Review is another use, since an agent that didn't write the code brings none of your conversation's assumptions to it.
Each subagent sends its own requests, and they count toward the same usage limits as your main conversation, so tokens are the main cost. A fresh one must first gather context your conversation already had, which can make it slower than working in place. Nor is the answer smarter: by default it's the same model, or a smaller one, on the same task.
Once you keep spawning the same kind of worker with the same instructions, such as a link check after every docs edit, save it as an agent file like the sample.
| Main conversation | Subagent | |
|---|---|---|
| Needs frequent back-and-forth or iterative refinement | Yes | No |
| Phases share a lot of context, such as planning, building and testing | Yes | No |
| A quick, targeted change | Yes | No |
| Latency matters | Yes | No |
| Produces verbose output you don't need in your chat | No | Yes |
| Needs tool limits or permissions of its own | No | Yes |
| Self-contained work that can come back as a summary | No | Yes |
Source: Claude Code docs: Create custom subagents (read November 3, 2026)
Reference: where agent files load from, and the default limits
15,000
tokens of combined subagent descriptions before Claude Code warns at startup
Source: Claude Code docs: Create custom subagents (read November 3, 2026)
3
layers of subagents allowed below your main conversation, by default
Source: Claude Code docs: Create custom subagents (read November 3, 2026)
20
subagents running at once before a new one fails to start, by default
Source: Claude Code docs: Create custom subagents (read November 3, 2026)
| Location | Scope | Priority |
|---|---|---|
| Managed settings | Your organization | 1, highest |
The --agents flag, as JSON | The current session only, never saved to disk | 2 |
.claude/agents/ | The current project | 3 |
~/.claude/agents/ | All your projects | 4 |
A plugin's agents/ folder | Wherever the plugin is enabled | 5, lowest |
Every fact here comes from the Anthropic pages listed under Sources, read on November 2 and 3, 2026. It's a reading of the documentation, not hands-on testing, and Claude Code changes fields, defaults and commands between releases.
Frequently asked questions
Can a subagent start its own subagents?
Yes, down to three layers below your main conversation by default. At that depth Claude Code withholds the Agent tool from every subagent except a fork, so the deepest one does its job itself and returns one summary. Setting CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH changes the number of layers. Width has its own cap: while 20 subagents are running, a session fails to start a 21st.
Do I have to restart Claude Code after adding a subagent?
Usually not. Claude Code watches .claude/agents/ and ~/.claude/agents/, and the next delegation picks up a new or edited file within a few seconds. You do need a restart if the agents folder didn't exist when the session started, if the agent sits under a directory added with --add-dir, or if the session began with --disable-slash-commands.
What is the difference between a subagent and a fork?
A fork inherits the whole conversation so far, while a regular subagent starts fresh from its definition. A fork shares the main session's system prompt, tools and model and reuses its prompt cache. For work that needs the same context, that makes a fork cheaper than a fresh subagent. Type /subtask and the task to start one yourself. A fork can't start more forks.
How do I stop Claude from using a subagent?
Put it on the deny list in your permission settings as Agent(name), for example Agent(Explore). That works for built-in and custom subagents alike. Old Task(...) entries keep working too: Claude Code v2.1.63 renamed the Task tool to Agent and kept the old name as an alias.
Can a subagent remember things between sessions?
Yes, once you turn on persistent memory with one frontmatter line. Set memory: user and its notes go under ~/.claude/agent-memory/ for every project. With project they go in .claude/agent-memory/, where you can commit them, and local uses .claude/agent-memory-local/, outside version control. None of this touches your own auto memory, which a regular subagent doesn't load.
Which model does a subagent use if I leave model out?
Your main conversation's model, unless you've set the CLAUDE_CODE_SUBAGENT_MODEL environment variable. A model alias Claude passes for a single call beats both. To put one model on every subagent, also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, which needs Claude Code v2.1.257 or later.
Where can I get subagents someone else wrote?
In a plugin, which brings its agents along with skills, hooks and MCP servers, or in a Mindket kit, a zip of plain text files where nothing runs by itself. Read the frontmatter of any agent file you didn't write before you use it. Mindket's agents page lists a different kind: instructions for a browser agent, each shown in full so you can read what it does before you hand it over.
Sources
- Claude Code docs: Create custom subagents https://code.claude.com/docs/en/sub-agents
- Claude Code docs: Best practices https://code.claude.com/docs/en/best-practices
- Claude Code docs: Extend Claude Code https://code.claude.com/docs/en/features-overview
- Claude Code docs: Extend Claude with skills https://code.claude.com/docs/en/skills
- Claude Code docs: How Claude remembers your project https://code.claude.com/docs/en/memory