Claude Code Subagents: .claude/agents files that keep the main chat clean

A subagent does one kind of job in its own window and returns a summary. Use one when a search, a test run, or a file-by-file review would bury the conversation you still need. This lab writes five agents you can commit. Session commands and flags are in the Claude Code cheat sheet.

What a subagent is

Each custom subagent is a Markdown file. The front matter sets the name Claude delegates to, the tools it may call, and the model it runs on. The body replaces the normal Claude Code system prompt for that agent. It still receives basic environment details such as the working directory.

The parent session sees a short tool row, the agent name, and the final result. Intermediate reads stay in the subagent transcript under the project session files in ~/.claude. That split is the reason to create an agent you would otherwise re-prompt every day.

Built-in agents already exist. Explore searches the tree without editing. Plan gathers context while the main session is in plan mode. You do not need to redefine them. A project or user agent whose name is Explore overrides the built-in one.

Subagents are one form of agentic work: a model, a tool list, and a stop condition. They are not MCP servers. MCP exposes external tools. A subagent is another Claude session with a narrower prompt.

File format

Only name and description are required. Unrecognized keys are ignored. name is at most 256 characters and cannot contain :, because colon names are reserved for plugins. The file name does not have to match name, but matching it keeps the folder readable.

Other supported fields you will actually use:

isolation: worktree branches from the repository’s default branch, not from your current HEAD. The worktree is removed when the agent makes no changes. Leave it off when the agent must see the branch you have checked out.

A cd inside the agent does not stick between shell calls, and it does not change the main session’s directory.

Where the file lives

Project agents are discovered by walking upward from the working directory to the repo root. If two of those folders define the same name, the one closer to the working directory wins. Claude Code also scans subfolders, so .claude/agents/review/security.md is a valid layout. Commit project agents. Keep personal experiments in ~/.claude/agents/.

Claude Code watches ~/.claude/agents/ and the project .claude/agents/. Edits show up within a few seconds. Three cases still need a restart: the agents directory was created after the session started, the file is inside a directory you added with --add-dir, or the session was started with --disable-slash-commands.

/agents in current versions prints a reminder to edit these files. On Claude Code v2.1.197 and earlier it opened a manager UI. Background agents already running are listed with /tasks, which the cheat sheet includes.

Check front matter with claude plugin validate .claude/agents. That check needs Claude Code v2.1.233 or later. It reports files that do not parse. It does not complain about a missing name if the YAML itself parses.

When Claude delegates

Claude compares your request, the agent description, and the current context. A description that says when to run is more useful than a description that only says what the agent is. The docs call out the phrase “use proactively” as a way to encourage delegation. Keep descriptions short. If the combined descriptions of your custom agents pass 15,000 tokens, Claude Code warns at startup and still loads every agent. Move long instructions into the body, which loads only when that agent runs.

Delegation is a choice. A vague description loses to Explore or to the main session doing the work itself.

Explicit invocation has three levels:

The mention syntax that shows agents in the typeahead looks like this:

@"code-reviewer (agent)" look at the auth changes

You can also type @agent-code-reviewer without the picker. While you type that form, the menu shows files. The mention still resolves when you send it. Your sentence goes to the parent. The parent writes the task prompt the subagent actually receives.

A plugin agent appears as a scoped name, for example @agent-my-plugin:code-reviewer. If the plugin file sits in a subfolder, the scope includes that folder: my-plugin:review:security.

--agent persists when you resume the session. If the agent file is gone at resume time, the session continues with the default tools and shows a warning.

One-off agents can be passed as JSON. This form is for a single launch, not for a file you commit:

claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'

In print mode on v2.1.281 or later, --agents may point at a JSON file. An interactive session refuses a file path there.

Five agents

Tool names below are the ones the subagent reference uses: Read, Grep, Glob, Edit, Write, and Bash. Listing tools is what keeps a reviewer from editing. An omitted tools field inherits the full subagent set.

Code reviewer

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews local diffs for correctness bugs and missing tests. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a code reviewer for this repository.

Run git status and git diff. Read only the files that diff touches, plus tests next to them.
Report findings as blocking, should-fix, or note.
Each finding needs a file path and the failure mode.
Skip style nits that a formatter would fix.
Do not edit files and do not commit.

Bash is on this agent so it can run git diff. It can also run other shell commands, so the prompt has to forbid edits and commits. If you need a hard stop, drop Bash and accept that the parent must paste the diff into the delegation prompt.

Test writer

.claude/agents/test-writer.md

---
name: test-writer
description: Adds or updates tests for code that just changed. Use when the user asks for tests or a change has no coverage.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
---

You write tests that match this repo's existing runner and layout.

Read the changed code and one nearby test file before you add anything.
Cover the behavior that regressed or that the change claims to add.
Do not change production code except to expose a test hook the project already uses.
Run the narrowest test command that executes the new test.
If it fails, fix the test. If production code is wrong, stop and report that instead of rewriting it.

Security auditor

.claude/agents/security-auditor.md

---
name: security-auditor
description: Read-only pass over auth, secrets, and risky shell or SQL. Use proactively before a security-sensitive change merges.
tools: Read, Grep, Glob
model: sonnet
---

You audit this repository for security issues a reviewer can verify from the code.

Look for secrets in the tree, auth checks that trust the client, command injection, and queries built with string concatenation.
Cite the file and the pattern. Say how it could be hit.
Do not modify files. Do not run exploits. Do not request credentials.
If you are unsure, label the item as needs-human and quote the line.

No Bash and no write tools. The agent cannot “just curl production” to check an idea.

Doc writer

.claude/agents/doc-writer.md

---
name: doc-writer
description: Updates README or docs so they match the code. Use when behavior changed and the docs were not part of the edit.
tools: Read, Grep, Glob, Edit, Write
model: haiku
---

You update documentation to match the code.

Read the implementation first. Edit the existing doc page that already describes the feature.
Describe behavior a caller can observe. Do not invent flags or paths.
If the code is ambiguous, write the question at the top of your summary and skip the doc edit.

model: haiku keeps a wording pass on the smaller alias. The parent can stay on Sonnet. See the cost section below.

Debugger

.claude/agents/debugger.md

---
name: debugger
description: Finds why a failing test or command fails. Use when the user pastes a stack trace or says a check is red.
tools: Read, Grep, Glob, Bash, Edit, Write
model: inherit
maxTurns: 12
---

You debug one failure.

Reproduce it with the command in the task before you edit.
Change the smallest surface that explains the failure.
Re-run that command. If it still fails, report what you tried and stop.
Do not clean up unrelated files.

model: inherit follows the session model. maxTurns: 12 stops a debugger that is looping. The result comes back marked partial, and you can ask Claude to resume that same agent rather than start a new one.

Pitfalls

The agent does not see your chat. A non-fork subagent starts clean. It does not get your history, skills you already ran, or files the parent already opened. It does get its own system prompt, the delegation message, CLAUDE.md from the levels the parent loaded (unless omitClaudeMd is set), a git status snapshot when you are in a git repo, and any skills named in skills. Explore and Plan skip the CLAUDE.md load and the git snapshot.

Put facts the agent must not miss into the sentence you send, or into its Markdown body. “Use the debugger on the failure we discussed” is a weak delegation. “Use the debugger on npm test -- auth.test.ts. The assertion is expected 401.” is a complete one.

A fork, which you can start with /subtask, inherits the parent conversation instead. That is the tool when restating the background would cost more than sharing it. Forks are a different feature from the five files above.

You pay for the second model. The subagent’s requests count toward the same usage limits as the main session. Descriptions of every custom agent are also loaded into the parent, up to the 15,000-token warning. A haiku doc writer is cheaper than inheriting Opus for a wording pass. A subagent’s context window is the window of its own model, so a smaller model is a smaller window too.

There is a concurrency cap. Once 20 subagents are running, another spawn from the Agent tool fails with a concurrent-limit error until one finishes. That cap needs Claude Code v2.1.217 or later, and sessions with ultracode on are exempt. Raising it is CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. You rarely want a higher cap on a laptop.

Worktrees are not your branch. isolation: worktree starts from the default branch. An agent asked to review uncommitted work on a feature branch will not see that work if you turn isolation on.

Resume is explicit. Each delegation starts a new instance. When the agent finishes, the parent receives an agent id and can resume it, keeping that agent’s transcript. Explore and Plan do not return an id. Ask the parent to continue the code-reviewer, or start a fresh one if the first pass was enough.

Hooks inside the agent are not session hooks. Front matter hooks run while that agent runs. A Stop hook written there fires as SubagentStop. Project hooks in settings.json also run for tools the agent calls, with agent_id and agent_type on the input. The hooks guide shows the settings file. Plugin agents ignore hooks, mcpServers, and permissionMode in their own front matter.

A repeated checklist that should stay in the main chat is a slash command, not an agent. An agent is for the noisy middle of a task.

FAQ

What is a Claude Code subagent?

A subagent is a separate assistant with its own context window, system prompt, tool list, and model. Claude delegates a side task to it and brings back a summary, so search dumps and log files stay out of the main conversation. Each subagent call is its own model request and counts toward the same usage limits as the main chat.

How do I add a custom subagent?

Create a Markdown file in .claude/agents/ for one repo, or in ~/.claude/agents/ for every project on your machine. Front matter needs name and description. tools and model are optional. The Markdown body is the system prompt. If the agents directory did not exist when the session started, restart Claude Code once so the new folder is picked up.

How do I force Claude to use one subagent?

Type @ and choose the agent from the typeahead, or write @agent-code-reviewer in the prompt. That mention guarantees that agent runs for the task. Naming it in a sentence, such as “use the code-reviewer subagent”, asks Claude to delegate and still leaves the choice open. claude --agent code-reviewer makes that agent the whole session.

Why did my subagent ignore the conversation?

A normal subagent starts from a fresh context. It does not see your chat history, skills you already invoked, or files the main session already read. Claude writes a delegation message, and the subagent works from that plus its own prompt and the CLAUDE.md files it is allowed to load. A fork is the exception: it inherits the parent conversation.

Do subagents cost extra?

They send their own requests on the model you assigned, and those requests count toward the same plan limits or API usage as the main session. A haiku reviewer spends less than an opus one. The description fields of your custom subagents also sit in the parent context, and Claude Code warns at startup when those descriptions together pass 15,000 tokens.