A subagent is a separate Claude with its own context window and its own instructions. The point is isolation: a search that reads forty files fills the subagent’s window, and only the summary comes back to yours. It also lets you send cheap work to a cheaper model.
1. Delegate the wide work
Use subagents to find every place we call the old fetchUser API.
What it does: hands the sprawling search to a separate context, so your main conversation gets the answer without the forty files it took to find it.
2. Write your own
Create .claude/agents/<name>.md for the project, or ~/.claude/agents/ for every project.
Note: as of v2.1.198, /agents no longer opens an interactive wizard — write the file, or
ask Claude to write it for you.
---
name: test-writer
description: Writes focused unit tests for a given file
tools: Read, Write, Bash
model: sonnet
---
You write minimal, behavior-focused unit tests. Match the project's existing test style.
Run the tests and confirm they pass before finishing.
What it does: defines a subagent. name and description are required — the description is
what Claude reads when deciding to delegate, so write it as a trigger, not a title. tools
narrows the inherited set; model takes sonnet, opus, haiku, fable, or a full ID.
Claude Code watches these directories and picks up changes within seconds, so no restart in most cases.
3. Invoke it
@"test-writer (agent)" write tests for src/lib/parse.ts
What it does: guarantees that subagent runs, rather than hoping Claude picks it. Naming it in
plain prose (“use the test-writer subagent”) also works. To run a whole session as one:
claude --agent test-writer.
Verify it worked
Run /context after a delegated search. If your main window barely grew, the isolation worked;
if it ballooned, the work happened inline and you got none of the benefit — which is the whole
reason to use a subagent rather than just asking.
Use them for broad searches, parallel independent tasks and focused reviews. Avoid them for tightly coupled steps that need shared state: a subagent starts blank, so everything it needs has to be in the task you hand it. Because each one runs its own context, they are also a real cost lever in both directions — see managing context for the rest of that picture.
Source: Claude Code subagents.