My main Claude Code session used to spend half its context window on grep output I never read twice.
Then I moved search, docs lookup, and code review into subagents. The noise now stays in someone else’s context window and my main thread only sees the summary. Sessions last longer before compaction, and the expensive model stops doing cheap work.
Here’s the setup I run: four agent files, two skills, everything backgrounded by default. Ten minutes to copy.
Why Subagents Beat One Big Session
A subagent is a separate agent with its own context window, its own system prompt, its own tool list, and optionally its own model. It does a task, returns a summary, and disappears. Nothing it read along the way lands in your conversation.
That buys two things. Context stays clean, and you get model routing: I don’t need a flagship model to run ripgrep across a repo.
I built the same pattern in OpenCode a while back. Claude Code’s version is simpler because the config is just markdown files on disk.
The Fastest Path: One Markdown File
A subagent is a markdown file with YAML frontmatter. Only name and description are required. Everything else is optional.
---
name: repo-scout
description: Searches the codebase to locate files, symbols, and patterns. Use proactively for any "where is X" question.
tools: Read, Grep, Glob
model: haiku
---
You are a search specialist. Find the relevant files, read only the
lines you need, and return absolute paths plus a two-line summary each.
Never edit anything. Never dump whole files back.Drop that at .claude/agents/repo-scout.md and it’s live for this project. Put it in ~/.claude/agents/ instead and it follows you into every project on the machine. Both directories are scanned recursively, so subfolders like agents/research/ are fine; identity comes from the name field, not the path.
Claude Code watches both directories and picks up edits within a few seconds, no restart needed. One exception: if the agents folder didn’t exist when the session started, restart once.
Skip the wizard
Recent versions dropped the interactive creation flow from /agents. Ask Claude to write the file, or write it by hand. Hand-writing is faster once you’ve seen one.
My Roster and Why Each Model
Four agents, and I resisted the urge to add more.
repo-scout runs on haiku. Read, Grep, Glob only. It answers “where does auth get validated” in a few seconds for pennies, and it physically can’t write files.
doc-fetcher also runs on haiku, with WebSearch and WebFetch. It reads changelogs and API docs so my main thread doesn’t have to hold 40KB of HTML.
architect runs on fable, read-only. This is the one I ask for a plan before a refactor. A planning agent that starts editing is a planning agent you can’t trust.
reviewer runs on opus, with Bash added so it can run the test suite. Its description says “use proactively after any non-trivial change.”
The model field accepts the aliases sonnet, opus, haiku, and fable, a full model ID like claude-opus-5 or claude-sonnet-5, or inherit. Leave it out and it defaults to inherit, meaning the subagent runs on whatever your main conversation uses. That default is exactly what you want to override for cheap agents.
The split is obvious once you watch usage: Haiku 4.5 handles the high-volume, low-judgment work, and the Claude 5 models handle anything where being wrong is expensive. My search agent runs 30 times a day. My reviewer runs three.
Skills Are the Other Half
Subagents are who does the work. Skills are how a recurring procedure gets done. Different problem, and people conflate them constantly.
A skill is a directory with a SKILL.md inside, and the directory name becomes the slash command:
---
name: ship
description: Style-gate, build, and deploy the site to production.
disable-model-invocation: true
---
1. Run ./scripts/humanize-check.sh on changed posts. Stop if not CLEAN.
2. Build the theme, then rsync to the server.
3. Purge the CDN cache and verify the post URL returns 200.That gives me /ship. The disable-model-invocation: true line means only I can trigger it, which is what you want for anything that touches production.
The part that matters for context: a skill’s body doesn’t load until it’s used. Long checklists cost nothing sitting on disk. That’s why I moved half my old CLAUDE.md into skills, anything that had become a procedure rather than a fact.
Agents and skills compose, too. A subagent’s frontmatter has a skills field that preloads specific skill content into that agent’s context at startup.
The Directory Layout
.claude/
├── agents/
│ ├── repo-scout.md
│ ├── doc-fetcher.md
│ ├── architect.md
│ └── reviewer.md
├── skills/
│ ├── ship/SKILL.md
│ └── post-audit/SKILL.md
└── settings.jsonAll of it is checked into git. New machine, git clone, and my agents are there. That’s what made me stop treating agent config as a personal dotfile problem, a habit I unpack further in my Claude Code CLI guide.
Background Tasks and How Delegation Fires
Subagents now run in the background by default. Claude only pulls one into the foreground when it needs the answer before it can continue. You can press Ctrl+B to background a running task yourself, or set background: true in the frontmatter to force it.
Background agents get a reduced built-in tool set (Read, Grep, Glob, Bash, Edit, Write, WebFetch, WebSearch, Skill, and others), so one definition can resolve to different tools depending on where it runs. Worth knowing before you debug a “why can’t my agent do X” mystery.
Delegation itself is automatic, driven by your request and the agent’s description field. Write that field for a router, not for a human. If you want certainty, @agent-reviewer guarantees which agent runs, and claude --agent reviewer makes an entire session run as that agent.
Guardrails exist: 20 concurrent subagents, 200 per session, nesting three layers deep.
What I Got Wrong First
My first roster had nine agents. Overlapping descriptions meant Claude picked the wrong one constantly, and I couldn’t tell why. Four sharp agents beat nine fuzzy ones.
Second mistake: giving a research agent Write access “just in case.” The tools field is an allowlist and disallowedTools is a denylist, and if both are set the denylist applies first. Restrict aggressively.
If you’re still deciding whether this tool is your daily driver, my comparison of Cursor, Windsurf, and Claude Code covers the tradeoffs. And if you want the layer below all this, MCP servers are how you give these agents real tools. Full field reference lives in the official subagents docs.
Frequently Asked Questions
Do subagents share my main conversation’s context?
No. Each one starts fresh with its own system prompt plus basic environment details like the working directory, and it does not receive your chat history. That isolation is the point. It also means you must write descriptions and system prompts that stand alone, because the agent has no idea what you were talking about a minute ago.
Should config go in the project or in my home directory?
Put anything codebase-specific in .claude/agents/ and commit it so your team gets it. Preferences that apply everywhere belong in ~/.claude/agents/. I keep repo-scout and doc-fetcher at the user level since they’re generic, and reviewers in the repo.
What’s the difference between a subagent and a skill?
A subagent is a worker with its own context and model. A skill is a set of instructions that loads into whoever’s already working. If you want isolation and a cheaper model, build an agent. If you want a repeatable procedure like a deploy checklist, build a skill and call it with a slash command.
Can I force a specific agent instead of hoping Claude picks it?
Yes, three ways. Name it in plain language and Claude usually delegates, @-mention it to guarantee that one task uses it, or pass --agent <name> to run a whole session under that agent’s prompt, tools, and model.
Does this actually save money?
For me it did, mostly because routing search and docs lookup to Haiku removed the largest chunk of high-volume token spend. The bigger win is fewer compactions on long sessions. I wrote more about how the CLI changed my day-to-day in this piece on Claude Code.