Subagents in Claude Code: A Practical Guide

Claude Code subagents are markdown files you drop in .claude/agents/ (or ~/.claude/agents/ for anything you want available across every project) that Claude can hand a scoped task to. Each one gets its own context window, its own system prompt, and its own tool access, separate from the conversation you're actually having. If you've been running Claude Code daily and haven't touched this yet, this is the guide to fix that.

What they are and why they matter

Think of your main Claude Code conversation as your desk. Every file you read, every grep result, every log dump you paste in sits on that desk and stays there for the rest of the session. A subagent is a separate room down the hall. You send it a task, it does the messy work, digging through logs, reading fifteen files, running a test suite, and it comes back with a summary. The mess stays in that room. Your desk stays clear.

That's the whole pitch, and it's a bigger deal than it sounds. Claude Code's context window is finite, and everything in it costs money and attention on every single turn. A search that touches forty files and comes back with pages of matches doesn't need to live in your main conversation forever. It needs to happen once, get distilled into "here's the answer," and then disappear. That's what a subagent does.

Claude Code ships with a few built-in subagents already: Explore (fast, read-only codebase search), Plan (research for plan mode), and general-purpose (a capable all-rounder for multi-step work that needs both digging and editing). You've almost certainly triggered these without naming them. When Claude says something like "let me search for that" and comes back a beat later with a clean answer instead of a wall of grep output, that's a subagent doing its job.

Custom subagents are where it gets useful for your own workflow. A subagent file looks like this:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Name and description are required. Everything else, including which tools it's allowed to touch and which model runs it, is optional and defaults sensibly. Claude matches your request against the description field to decide when to delegate, so a vague description gets skipped and a specific one gets used constantly.

The cost lever: lower-power subagents

Here's the part that actually moves your bill: the model field. You can pin a subagent to haiku, sonnet, opus, fable, a specific model ID, or leave it on inherit so it matches whatever you're running in the main conversation. That single field is the difference between every subagent call costing frontier-model prices and most of them costing a fraction of that.

Most of what you delegate to a subagent doesn't need your best model. Running a test suite and reporting only the failures, grepping a codebase for a pattern, applying a mechanical rename across a dozen files, none of that requires frontier-level judgment. It requires following instructions precisely, which cheaper models do fine. Save the expensive model for the calls that actually need reasoning: architecture decisions, ambiguous bug triage, anything where a wrong guess is expensive to unwind.

Simon Willison put this into a single line and it's been passed around widely since. In a July 3 post titled "Fable's judgement," he described telling Claude Code: "For all coding tasks use your judgement to decide an appropriate lower power model and run that in a subagent." The tip reportedly came out of a conversation with Anthropic's Claude Code team, and Willison's own report was straightforward: his usage budget stopped draining as fast, and he got more done in the same session, not less. The idea isn't "always use the cheapest model." It's "let the model that's directing the work decide when cheap is good enough," the same instinct behind a two-tier routing rule: expensive on purpose, cheap by default.

The practical version for your own .claude/agents/ or CLAUDE.md: tell Claude explicitly that mechanical, well-scoped, or parallelizable work (bulk edits, boilerplate, running and triaging tests, log or output cleanup) should go to a Haiku- or Sonnet-tier subagent, and that architecture calls, debugging judgment, and anything ambiguous stay on the model actually driving the session. Write it down once and it applies to every future task without you having to think about it again.

Ready-made subagents to steal

You don't have to write every subagent from scratch. davila7/claude_subagents is a small public repo built specifically as a playground for subagent patterns: a handful of working agent definitions (a dependency tracer, a UI auditor, a project structure checker, and a few others) meant to demonstrate clean context isolation, forked context, and nested subagent chains. It's a good place to copy a working file and adapt it rather than starting from a blank page.

If you want to go deeper on how Claude Code's orchestration actually works under the hood, not just how to use it, VILA-Lab/Dive-into-Claude-Code is a community teardown of the tool's internals: how the main loop, tool calls, and subagent delegation actually fit together. It's not required reading to use subagents well, but if you're the type who wants the mental model before the recipe, it's the best public resource for that.

For the fuller shortlist of tools worth installing alongside subagents, the pillar guide covers what else earns a place in your setup.

How to create your own

The fastest path is to just ask Claude Code to write the file for you. Describe the subagent you want and where to put it:

"Create a personal code-improver subagent in ~/.claude/agents/ that scans files and suggests improvements for readability and performance. Make it read-only and have it use Sonnet."

Claude writes the markdown file with a name, description, tool list, and model already filled in. Open it, confirm it matches what you asked for, and you're done. If you'd rather write it by hand, the frontmatter format above is the whole spec: name and description are required, tools restricts what it can touch, model sets its tier, and the body below the frontmatter is the system prompt.

Two placement rules matter. Project-level subagents (.claude/agents/) belong in version control so your whole team gets them; that's the right home for anything specific to one codebase. User-level subagents (~/.claude/agents/) are personal and follow you into every project on your machine, which is where general-purpose helpers like a code reviewer or a commit-message drafter belong.

Subagents vs skills

It's easy to conflate these because both live in your Claude Code setup and both make Claude better at a repeatable job, but they solve different problems. A skill is a markdown file that teaches Claude a workflow it runs in your main conversation, using your context, your history, your open thread. A subagent hands off to a separate context window entirely and comes back with only a summary.

Reach for a skill when you want a reusable procedure that benefits from seeing everything you've already discussed. Reach for a subagent when the task is going to generate a pile of output you don't want cluttering your main conversation, or when you want to enforce a hard limit on which tools a piece of work is allowed to touch. A subagent built for browser-driven QA work, for instance, is a natural candidate to restrict to browser and file tools only. If that's the kind of workflow you're setting up, the browser automation guide covers the tooling side of that in more detail.

The two aren't competing. A skill can tell Claude how to do something well; a subagent decides where that work happens and who pays for it.

The close

Subagents aren't a power-user feature you can skip. They're the difference between a Claude Code session that stays sharp for hours and one that bogs down under its own context by lunchtime. Start small: pick the one task you delegate to Claude most often that produces a wall of output you never actually read, and give it a subagent with a cheap model attached. That's the whole upgrade.