Claude Code Subagents: A Practical Multi-Agent Guide for Your First Deployment

Bottom line up front: Claude Code subagents handle well-defined tasks in isolated contexts so your main session stays clean. Start with a read-only reviewer, give it the fewest tools possible, and run three real tasks before deciding if it stays.

Below: when to dispatch a subagent, how to control its permissions, and what mistakes to avoid on your first deployment. Every config block is copy-paste ready.

What Are Claude Code Subagents and Why Should You Care?

Think of the main session as your desk. A subagent is a colleague you send to a separate room with a clear checklist: read these files, check for these issues, bring back a bullet list. The colleague never touches your desk.

This matters because long Claude Code sessions accumulate context: file reads, tool outputs, exploratory tangents. Past a certain point, the model loses track of what still matters. Subagents prevent that by absorbing the noisy middle -- the 30 files read, the 200 lines of logs parsed -- and delivering only the conclusion.

In my workflow, the single decision criterion is this: if a task generates a lot of intermediate material but the final output is a short summary, it belongs in a subagent. Code review, test-failure triage, file-structure audits -- all high-noise, low-signal-output tasks. A quick variable rename? Keep it in the main session. The handoff cost alone would outweigh the benefit.

How Do You Create Your First Subagent? (Copy-Paste Config)

Save this file to .claude/agents/article-reviewer.md in your project. You now have a read-only review assistant:

---
name: article-reviewer
description: Use when the user requests a review of a Markdown article. Checks for duplicate paragraphs, headline-body mismatches, excessive code ratio, and machine-translation tone. Does not modify files -- returns an issue list with suggestions only.
tools: Read, Grep, Glob
model: haiku
---

You are an article review assistant. Your job is to find problems, not rewrite the article.

Workflow:
1. Confirm the article path the user specified. Read only the necessary files.
2. List issues from highest to lowest severity.
3. For each issue, state the location, the reason, and a suggested fix.
4. Never publish, edit, or create files.

Invoke it like this:

Use article-reviewer to review {path}. Return only the top 10 issues worth fixing.

Three fields determine whether this subagent works well:

• description -- Claude Code reads this to decide whether to dispatch. Write when to use it, not what it is. "Use when the user requests a review" beats "content review expert."
• tools -- Whitelist. Only Read, Grep, Glob. Omitting this field grants every tool from the main session -- unnecessary risk for a read-only agent.
• model -- haiku for speed and cost. Omitting defaults to inherit (the main session's model).

Only name and description are required in the frontmatter. Everything else (tools, model, disallowedTools) is optional. Check the official docs for the current field list.

When Should You Dispatch a Subagent vs. Keep the Task In-Session?

Not every task benefits from delegation. The table below covers the four most common beginner scenarios:

The one-sentence test: Can you define "done" in a single sentence? If yes, the task is a subagent candidate. If not, clarify the goal in the main session first.

Good subagent tasks: "Check this diff for security risks and list them." "Summarize test failures from the last CI run." "Find all TODO comments in /src and group by priority."

Bad subagent tasks: "Make this project better." "Optimize everything you can find." "Plan the next quarter." These have no verifiable completion criteria.

Why Does Context Isolation Matter for Multi-Agent Workflows?

In practice, context isolation means the main session stays focused on decisions and integration while subagents handle the grunt work. A code review subagent reads 40 changed files and returns five risk items. A test-runner subagent parses 300 lines of output and reports the first real failure. The main session never sees the intermediate material.

Claude Code ships with built-in subagents that demonstrate this pattern:

• Explore -- uses a lightweight model with read-only tools. Its job is to scan the codebase and find relevant files fast.
• Plan -- gathers context in planning mode before the main session commits to an approach.
• General-purpose -- inherits the main session's model and full toolset for complex multi-step tasks.

Notice the cost-optimization pattern: Explore runs on Haiku with read-only tools because it only needs to find things. You should follow the same principle -- match model weight and tool scope to task complexity.

Should You Use Project-Level or User-Level Subagents?

Project-level agents live in .claude/agents/ inside your project. User-level agents live in ~/.claude/agents/ and work across all projects.

Start with project-level. Most subagents are project-specific: an article reviewer for a content repo, a test summarizer for a backend service, an SEO checker for a marketing site. Project-level agents travel with version control, so every team member gets the same set.

User-level agents suit stable, project-agnostic utilities -- "summarize terminal output" or "draft a code review comment." Don't promote an agent to user-level until it has proven reliable across multiple real tasks.

One more consideration: project-level agents carry team norms. User-level agents carry personal habits. Keeping this boundary clean simplifies maintenance as your agent library grows.

How Should You Write the Description Field?

The description field is the dispatch rule, not a job title. Claude Code reads it to decide whether a subagent matches the current task. "Content review expert" tells it nothing. "Use when the user requests a review of a Markdown article; checks for duplicate paragraphs, headline mismatches, and excessive code ratio" tells it exactly when to activate.

Two categories belong in every description:

1. Trigger conditions -- what situations should invoke this agent.
2. Exclusion zones -- what this agent must never do. "Review only. Never rewrite, publish, or create files."

If you want Claude Code to dispatch automatically without manual invocation, add "use proactively" to the description. But hold off on this until the subagent has been stable under manual use. Automatic dispatch on an untested agent makes debugging harder -- you won't know if the problem is the agent's config or the dispatch decision itself.

How Do You Set Tool Permissions Without Over-Granting Access?

The most common beginner mistake: omitting the tools field and letting a review agent inherit every tool from the main session. The agent was supposed to read files. Instead, it edited one.

Two permission strategies:

Whitelist (tools) -- explicitly name every allowed tool. Best for read-only agents where you know the exact toolset:

tools: Read, Grep, Glob

Blacklist (disallowedTools) -- inherit everything, then block specific dangerous tools. Best for agents that need broad capabilities but must never write files:

disallowedTools: Write, Edit

Here is a copy-paste config for a research agent that can run read-only commands and search but must never modify files:

---
name: safe-researcher
description: Use when research, information gathering, or read-only command execution is needed. Can use all tools except file writing. Returns conclusions only.
disallowedTools: Write, Edit
---

You are a research assistant. Read files, search, run read-only commands. Never write or modify any file. Return conclusions only.

When both tools and disallowedTools appear, the blacklist filters first, then the whitelist selects from what remains. Tools listed in both are removed.

Start with fewer tools than you think necessary. When the agent lacks a needed capability, its output will reveal it: "I could not read the test file" or "I don't have permission to run this command." Add tools incrementally. Permissions are easy to expand and hard to undo after an incident.

What Is the Difference Between Manual and Automatic Dispatch?

Three invocation methods, in order of commitment:

Start with natural language invocation. Every manual dispatch trains your judgment about which tasks belong in subagents. Once a pattern stabilizes, enable automatic dispatch by adding "use proactively" to the description.

Automatic dispatch works best for high-frequency, well-bounded tasks: auto-review after every code change, auto-proofread after every content rewrite. Without a stable foundation, automatic dispatch creates debugging ambiguity.

What Should Your First Subagent Do?

Build a read-only reviewer. It carries the lowest risk and the clearest verification criteria.

A read-only reviewer:

• Reads files without modifying them
• Outputs an issue list, never a rewrite
• Checks specific things: duplicate paragraphs, excessive jargon, code-to-text ratio, headline accuracy
• Fails safely -- even wrong judgments cause no file damage

This is deliberate. Your first subagent should teach you how to delegate, not how to automate. Once you trust your delegation skills -- clear handoff instructions, verifiable completion criteria, appropriate tool scope -- you can graduate to agents that write, test, or deploy.

Validate over three real tasks before deciding to keep an agent:

1. Short article -- can it follow instructions and return only issues?
2. Code-heavy tutorial -- does it flag necessary code as "excessive" (false positive test)?
3. Already-polished article -- does it manufacture problems to appear useful (false discovery test)?

Three tasks surface the common failure modes. Don't judge a subagent by a single run.

What Are the Hidden Costs of Context Isolation?

Subagents start with empty context. They don't know what you just discussed in the main session. This is a feature for noise isolation and a cost for context-dependent tasks.

Mitigate the cost with precise handoff instructions:

• Specify files: "Read /src/auth/login.ts and /tests/auth.test.ts."
• Define scope: "Check only for SQL injection vulnerabilities."
• Set boundaries: "Do not modify any file. Do not suggest refactors."
• Declare output format: "Return a numbered list, max 10 items, severity high to low."

Vague delegation produces vague results. "Take a look at this project" gives the subagent no anchor. "Read these three files, check for these two issue types, return a bullet list" gives it everything it needs.

One hard constraint to remember: subagents cannot spawn their own subagents. Nesting is not supported. If a task requires multi-layer delegation, orchestrate from the main session by dispatching multiple subagents sequentially.

How Do You Debug a Subagent That Produces Poor Results?

Four diagnostic checkpoints, in order:

1. Description too vague -- the agent doesn't know when to activate or what to focus on. Rewrite with explicit trigger conditions and exclusion zones.
2. Task too large -- the agent can't converge. Break the task into smaller, verifiable pieces.
3. Tool permissions wrong -- too broad creates risk; too narrow prevents execution. Check the tools or disallowedTools field.
4. Input material insufficient -- the agent didn't see the key files. Add explicit file paths to your delegation prompt.

Most subagent failures are delegation failures, not model failures. The same agent with a clear handoff ("read these three files, check for duplicate paragraphs, return line numbers") outperforms itself with a vague handoff ("review this article") by a wide margin.

Track each failure as a one-liner: was it description, permission, task scope, or input? After five failures, you will find a pattern -- and fixing the pattern fixes most future issues.

What Advanced Features Should You Add After the Basics Work?

Three directions, each solving a specific pain point. Don't add any of them on day one.

Blacklist permissions -- when you need the agent to keep most tools but block a specific dangerous action. Use disallowedTools instead of tools. Covered above.

Memory -- when a high-frequency agent keeps forgetting project-specific conventions. Enable memory to let it accumulate patterns across sessions: naming conventions, common pitfalls, project-specific rules. Only useful for agents you invoke daily.

Pre-loaded knowledge (skills) -- when an agent always needs to read the same reference doc before starting. Load the doc at spawn time instead of making it re-read every session. Useful for agents tied to a specific style guide or API spec.

Add these features in response to real friction, not in anticipation of it. The sequence: start with a whitelist-only read agent, stabilize it, then add blacklist/memory/skills as pain points emerge.

Related Reading

• Claude Code Complete Guide 2026 - The complete Claude Code reference guide
• Claude Code /loop Guide - Use /loop for subagent orchestration
• Multi-Agent SSH Collaboration Guide - Multi-agent SSH setup across machines
• Claude Code Permissions Guide - Tool permissions and access control in depth
• Codex Skills & Subagents - Compare with Codex subagents

FAQ

Where should I put subagent files -- project-level or user-level?

Project-level in .claude/agents/. When both exist with the same name, project-level takes priority (organization-managed settings and --agents CLI flag rank even higher). Start project-level for version control and team sharing.

What happens if I skip the tools field entirely?

The subagent inherits every tool from the main session. For review agents, this means it can edit files even though it shouldn't. Always set an explicit whitelist for read-only agents.

Can a subagent dispatch its own subagent?

No. Nesting is not supported. Orchestrate multi-agent workflows from the main session.

What model does a subagent use by default?

inherit -- whatever the main session runs. Set model: haiku explicitly for lightweight tasks to save cost and reduce latency.

How do I enable automatic dispatch?

Add "use proactively" to the description field. Only do this after the agent is stable under manual invocation across several real tasks.

What Should You Do Next?

Three takeaways to carry forward:

1. Subagents are task delegates, not multi-agent magic. They excel at bounded, verifiable, high-noise tasks.
2. Start project-level, start read-only, start manual. Don't go global, writable, or automatic on day one.
3. Description beats name. Boundaries beat power. A narrowly scoped agent with clear instructions outperforms a broadly capable agent with vague ones.

External references:

• Claude Code Official Subagents Documentation -- covers /agents, project vs. user paths, frontmatter fields, and tool permissions.
• Anthropic Claude Code Overview -- full documentation index for Claude Code features and architecture.

— Leo