Claude Code subagents: writing .claude/agents files and when they pay off
Defining Claude Code subagents: the Markdown file in .claude/agents, the tools and model fields, how description drives delegation, and examples for research, review and tests.
Contents
Ask Claude to survey a whole codebase and every file it reads stays in the context window, degrading the work that follows. Ask for a review and a long list of review criteria gets mixed into the task you were actually doing.
Subagents solve both. A subagent is a Claude with its own context and its own instructions, which the main Claude calls when it needs one. This article covers how to write the definition file and where it actually pays off.
KEY POINT
What you will learn
- The definition file format for
.claude/agents/ - The
toolsandmodelfields, and howdescriptioncontrols automatic delegation - Worked examples for research, test runs and documentation
How subagents work
The main Claude breaks a task up and delegates part of it. The subagent works in its own context and returns only a summary.
| Main | Subagent | |
|---|---|---|
| Context | The whole conversation | The delegated instructions plus what it reads |
| System prompt | Claude Code's own, plus CLAUDE.md | The body of the definition file |
| Tools | All of them, subject to permissions | Can be narrowed with tools |
| Model | The session's setting | Can be pinned with model |
The /agents command lists what you have defined and can create a new one interactively.
The definition file
Project agents go in .claude/agents/<name>.md; personal ones in ~/.claude/agents/<name>.md.
---
name: code-reviewer
description: Reviews code changes. Use when the user asks for a review, or when an implementation is finished and there is a diff to look at.
tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
model: claude-opus-5
---
You are this project's senior reviewer. Get the changes with `git diff` and review them on these points.
1. Conformance to the conventions in CLAUDE.md
2. Possible bugs: boundary values, null handling, exceptions
3. Security: input validation, secrets, injection
4. Whether tests exist and whether they are adequate
Group your output into critical, suggested and minor, and always cite the file and line number.
Do not change code; return findings only.| Key | Meaning |
|---|---|
name | The agent's name, lowercase with hyphens |
description | When to use it. Be concrete: this is what automatic delegation reads |
tools | The tools it may use. Omit to inherit the main session's |
model | The model to use. Omit to inherit the session's |
用語解説
Writing a good description: phrasing it as a condition ("use when …") makes automatic delegation predictable. Conversely, writing "only when the user explicitly asks" keeps it from being called on its own.
Example 1: a read-only research agent
---
name: explorer
description: Investigates the codebase. Use for questions like "where is X implemented" or "find every caller of Y". Does not modify files.
tools: Read, Grep, Glob
model: claude-sonnet-5
---
For the question asked, list the relevant files and locations as file:line,
then summarize the flow in ten lines or fewer. Mark anything inferred as an inference.Granting only read tools means it cannot change anything by mistake, and the lighter model keeps the cost down. The many files it reads stay in the subagent's context and only the summary comes back — see Managing context in Claude Code.
Example 2: a test runner
---
name: test-runner
description: Runs tests and analyses the results. Use to verify an implementation, or to investigate why tests fail.
tools: Read, Bash(npm test:*), Bash(npx vitest:*), Grep
---
Run the tests you are asked to run and report in this shape:
- The command you ran
- Pass and fail counts
- For each failure: the test name, a summary of the error, and a likely cause as file:line
Do not modify test code or the implementation.Example 3: a documentation updater
---
name: doc-writer
description: Updates README and the docs/ tree to match an implementation change. Use after the implementation is finished.
tools: Read, Edit, Write, Grep, Glob
model: claude-sonnet-5
---
Work out what changed with `git diff` and update the affected documentation.
Do not change code. Finish by listing the files you updated.Calling one
- Automatically: the main Claude delegates when the situation matches the
description. - Explicitly: "use the code-reviewer agent on the current diff".
- From a slash command: putting "use the code-reviewer subagent" in a custom command's body combines the two.
Where they fit, and where they don't
| Good fit | Poor fit |
|---|---|
| Broad research where you only want the conclusion | Small edits that depend on the conversation's context |
| Reviews with a fixed set of criteria | Work where you decide direction by discussing it |
| Independently verifiable work: tests, lint | Steps tightly coupled to what came before and after |
A subagent doesn't know your conversation
An instruction like "do it the way we just discussed" never reaches a subagent. The main Claude has to pass everything it needs at delegation time, so it helps to write "when delegating, always name the target files and the goal" into the definition file itself.
Subagents can run in parallel. Avoid any design where several of them edit the same file at once; for large parallel work spanning files, separate git worktrees are the safer structure.
Summary
- Write
name,description,toolsandmodelplus a body in.claude/agents/<name>.md - A concrete "use when …" in
descriptionis what makes automatic delegation reliable - Match the configuration to the role: read-only tools and a light model for research, a stronger model for review
- A subagent cannot see the main conversation, so everything it needs must be passed at delegation
FAQ
- Can a subagent see the main conversation?
- No. A subagent runs in its own context with only the instructions handed to it and whatever it reads itself. It returns a summary to the main conversation.
- When does a subagent get called?
- Claude decides based on the conditions you write in description. You can also name one explicitly in your prompt.
- Can I pin a model per subagent?
- Yes, with the model field in frontmatter. Using a cheaper model for research and a stronger one for judgement work keeps costs down.
Primary sources
This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.