← All posts
·4 min read

Claude Code Subagents: What They Are and How to Use Them

The first time I watched Claude Code spin up a second agent to review my code while the main one kept working, it clicked. That's a subagent. Here's what they are and how I use them.

What a subagent actually is

A subagent is a specialized AI agent that Claude Code can delegate a task to. The main agent hands off a job, the subagent does it, and the result comes back.

The key detail: each subagent runs with its own context window. It doesn't share the main conversation. It gets the task you describe, works in isolation, and returns a summary. The main agent never has to load all the noise the subagent waded through.

Subagents live as markdown files. Project-level ones go in .claude/agents/, and global ones you want everywhere go in ~/.claude/agents/. Each file has frontmatter that defines the agent and a system prompt in the body that tells it how to behave.

Why they're useful

Three reasons I keep coming back to.

  • Isolated context — A subagent that reads twenty files to answer one question returns just the answer. None of those twenty files pollute your main context. Your main agent stays focused and cheap.
  • Specialization — You can write a tight system prompt for one job. A code reviewer that only hunts for bugs is better at hunting for bugs than a general assistant juggling five things.
  • Parallelism — The main agent can fan out several subagents at once. Three explorers searching three corners of a codebase finish in the time one would take.
That isolation point is the one people underrate. Context is the scarcest resource in a long session. Subagents are how you spend it carefully.

How to create one

A subagent is just a markdown file with frontmatter and a body. Here's a real code-reviewer I keep in .claude/agents/code-reviewer.md.

---
name: code-reviewer
description: Reviews a diff for correctness bugs, edge cases, and security issues. Use after writing or changing code.
tools: Read, Grep, Bash
model: sonnet



You are a focused code reviewer. Given a diff or a set of changed files,
review only for real problems:


  • Correctness bugs and broken edge cases
    • 

  • Security issues (injection, auth gaps, leaked secrets)
    • 

  • Obvious performance traps
    • 


Do not comment on style or formatting. For each finding, give the file,
the line, why it's a problem, and a concrete fix. If you find nothing,
say so plainly. Keep the report short.

The frontmatter fields:

  • name — the identifier the main agent uses to call it.
  • description — when to use this agent. Claude reads this to decide whether to delegate, so make it specific.
  • tools — optional. Which tools the subagent can use. Omit it to inherit everything; narrow it to keep the agent on rails.
  • model — optional. Pin a cheaper or stronger model per agent.
The body is the system prompt. Treat it like instructions to a specialist who knows nothing about your project except what you tell them right here.

Drop the file in, and Claude Code picks it up. You can ask it to use the agent by name, or let it delegate on its own when the task matches the description.

When to use a subagent vs the main agent

Not everything needs a subagent. The main agent is the right tool when the work is small, conversational, or when you need the full context of what you've been doing.

Reach for a subagent when:

  • The task is self-contained and you only care about the result, not the steps.
  • It involves reading a lot to produce a little, like searching a codebase to answer one question.
  • You want to run several things in parallel.
  • You want a consistent specialist you'll reuse, like a test-writer or a doc-checker.
If the answer fits in a sentence and you already know the file, just do it inline. Delegation has overhead. Use it when the isolation actually pays for itself.

A couple of practical examples

A few subagents earn their keep on almost every project.

  • An explorer — Point it at a question like "where does auth happen in this repo" and it returns a map without flooding your context with file dumps.
  • A test-writer — Hand it a module and a description, and it writes a focused test file with a narrow toolset so it can't wander off.
  • A reviewer — The one above. Run it after every meaningful change as a second pair of eyes.
Subagents pair well with the other building blocks. They sit alongside Claude Code skills for packaged know-how and slash commands for repeatable workflows. Together they turn Claude Code from a chat box into something closer to a team. If you want a head start, there are plenty of ready-made subagents worth borrowing.

Don't write them all from scratch

You don't have to build every subagent by hand. I put the ones I trust into AgentsCamp (agentscamp.com), a directory of vetted Claude Code agents, skills, and slash commands. Grab one with npx agentscamp add agents/ and you're running with a battle-tested specialist in seconds. Start there, then tweak the system prompt to fit your project.

← All posts