Delegate work to Claude Code subagents

Long Claude Code sessions have a weak spot: everything Claude reads ends up in the same conversation. Ask it to search a big codebase and your session fills with file contents you'll never look at again.

A subagent fixes that. It's a helper that gets its own fresh context window, does a job, and hands back only a summary. Your main conversation stays clean, and you can give each helper its own instructions, tools and model.

This recipe builds a read-only code reviewer. It assumes Claude Code is installed and that you've seen skills, since the file format is similar.

What a subagent is (and isn't)

• It has its own context. The subagent starts fresh, works through its task, and returns a result to the main conversation.
• It has its own instructions. The body of its file becomes its system prompt, so it can be a specialist.
• It can have different tools. You can limit it to read-only tools so it can't change anything.
• It isn't a separate chat you talk to. Claude delegates a task and gets a summary back. For a job where you want a back-and-forth, stay in the main conversation.

Claude Code also ships with built-in subagents, which it uses on its own. Per Anthropic's docs these include Explore (fast searching of a codebase), Plan (research while planning) and general-purpose (for tasks that need both exploring and changing files). You don't have to set anything up to benefit from them. Custom subagents are for jobs you repeat.

Step 1: Choose where it lives

A subagent is a Markdown file with settings at the top. Where you put it decides who can use it:

If two subagents share a name, the more specific location wins, with organisation-managed definitions taking precedence over project and user ones.

Create the folder in a project:

mkdir -p .claude/agents

Step 2: Write the file

Create .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for bugs, risky changes and unclear logic. Use proactively after code changes, or when the user asks for a review.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a careful senior code reviewer.

When invoked:

1. Run `git diff` to see what changed. If there is no diff, ask which files to review.
2. Read the changed files and the code around them.
3. Report findings in three groups: Must fix, Should fix, Nice to have.

For each finding give the file and line, what is wrong, and a concrete fix.
Skip style nitpicks that a formatter would handle.
You are read-only. Never edit files; describe the change instead.

The fields:

• name (required): a short identifier in lowercase with hyphens.
• description (required): what the subagent does and when to use it. Claude reads this to decide whether to delegate, so it carries a lot of weight. Wording like "use proactively after code changes" nudges Claude to call it without being asked.
• tools (optional): which tools it may use, as a comma-separated list. If you leave the field out, the subagent inherits the tools available to it. Listing only read-oriented tools (Read, Grep, Glob) plus Bash for git diff is a sensible reviewer setup. Bash can still run commands, so if you want a strictly read-only reviewer, drop it and paste the diff into your request instead.
• model (optional): an alias such as sonnet, opus or haiku, a full model ID, or inherit to use your session's model. A cheaper, faster model is a good fit for search-heavy helpers.
• Everything below the second --- is the subagent's system prompt: its job description, in plain English.

Anthropic's subagents docs list further optional fields, including permissionMode, maxTurns, skills, mcpServers, hooks, memory and isolation. You can ignore them until you need them, and Claude Code ignores a field it doesn't recognise rather than failing.

Step 3: Make it available

Claude Code detects changes to agent files within a few seconds, so an edit usually takes effect on the next delegation without a restart. The exception is a brand-new agents folder that didn't exist when the session started. If your subagent doesn't appear, restart Claude Code.

You can also type /agents. How that command behaves depends on your Claude Code version: older versions open an interactive manager for creating and editing subagents, while newer ones point you to ask Claude or edit the agent folders directly. Either way, the files themselves are the source of truth, so the steps above work in every version.

Step 4: Use it

There are three ways to invoke a subagent.

Let Claude decide. Make a request that matches the description:

I've just changed the checkout code. Can you review it?

Claude sees the match with code-reviewer, delegates, and shows you the summary.

Name it in your prompt. For example, "Use the code-reviewer subagent to look at my latest changes." Claude still chooses whether to delegate, but naming it makes that very likely.

@-mention it. Type @ and pick the subagent from the menu (or type @agent-code-reviewer by hand). This makes that subagent run for the task, though Claude still writes the instructions it passes along.

Try it on a real change. Stage or edit a file, then ask for a review and watch the main conversation: you should see a short delegated task and a tidy report, not a pile of file contents.

Step 5: Add a second subagent for exploring

A different job suits a different shape. Here's a helper whose only purpose is answering "where does X happen?" without flooding your session:

---
name: code-explorer
description: Finds where something is implemented and explains how it works. Use when the user asks where a feature lives or how a piece of code flows.
tools: Read, Grep, Glob
model: haiku
---

You answer questions about how this codebase works.

Search with Grep and Glob, then read only the files you need.
Reply with: the files involved (with paths), a short plain-English explanation of the flow, and anything surprising.
Keep the reply under 200 words. Do not edit anything.

Note the tool list is strictly read-only and the model is a small, fast one. Because the subagent returns a short summary, you pay for the exploring once and carry only the conclusion forward. (Claude Code's built-in Explore subagent already covers a lot of this ground, so only write your own if you want custom behaviour.)

Step 6: When to use a subagent

Good fits:

• Noisy research. Searching, reading logs, scanning many files.
• Independent review. A fresh context isn't biased by the reasoning that produced the code.
• Restricted work. A helper that must never edit files or run commands.
• Cost control. Routing simple tasks to a smaller model.

Poor fits:

• Small, quick changes. The overhead of delegating outweighs the gain.
• Work that needs your input midway. The subagent returns a summary, not a conversation.
• Tightly coupled steps. If step two needs everything step one learned, keep them in one context.

Step 7: Share it with your team

Because project subagents are plain files, commit .claude/agents/code-reviewer.md and your teammates get the same reviewer. Keep personal experiments in ~/.claude/agents/ instead. A short note in CLAUDE.md listing the project's subagents (and when to use them) helps Claude and humans alike.

Troubleshooting

Claude never delegates. The description is probably too vague. Describe both the task and the trigger ("Use after code changes"), and use the words you naturally type.

The subagent isn't listed. Check the file is in .claude/agents/ or ~/.claude/agents/, ends in .md, and has valid frontmatter with both name and description. Restart if the folder is new.

It edited a file when it shouldn't have. Remove write-capable tools from its tools line, and tell it so in the body. Tool limits are enforced by Claude Code; instructions are only requests.

Results are shallow. A very small model may struggle with subtle review work. Try model: sonnet or inherit.

The name is rejected. Names shouldn't contain colons, which are reserved for plugin-provided agents.

Safety notes

A subagent with Bash can run commands, so give it the narrowest tool list that does the job. Read an agent file from someone else before using it, exactly as you would a script. For automatic checks that must run every time, a hook is more dependable than hoping Claude delegates.

Recap

1. Create .claude/agents/<name>.md (or ~/.claude/agents/ for all projects).
2. Add frontmatter with name, a clear description, and optionally tools and model.
3. Write the system prompt in the body.
4. Invoke it by matching its description, naming it, or typing @agent-<name>.
5. Use subagents for noisy, independent or restricted work; keep tightly linked steps in the main conversation.