# Claude Code Subagents: Multi-Agent Setup Guide By Amir Teymoori --- 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](https://amirteymoori.com/opencode-multi-agent-setup-specialized-ai-coding-agents/) 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. ```markdown --- 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: ```markdown --- 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.json ``` All 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](https://amirteymoori.com/how-to-use-claude-code-cli-like-a-pro/). ## 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](https://amirteymoori.com/cursor-vs-windsurf-vs-claude-code-which-ai-coding-tool-should-you-choose-in-2025/) covers the tradeoffs. And if you want the layer below all this, [MCP servers](https://amirteymoori.com/ai-agents-and-mcp-servers-explained-the-future-of-intelligent-automation/) are how you give these agents real tools. Full field reference lives in the [official subagents docs](https://code.claude.com/docs/en/sub-agents). ## 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 ` 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](https://amirteymoori.com/claude-code-the-ai-powered-cli-thats-changing-how-developers-work/).