Claude Code subagents are separate AI workers you define inside Claude Code, each with its own context window, toolset, and model. Set up correctly, they search, summarize, and classify at a fraction of what your main context costs; set up wrong, they waste tokens, overlap with the main agent, or stall on tasks they were never meant to do. On October 8, 2026, the timing for a proper SOP is unusually good: the Claude Haiku 5.5 launch one day earlier made the cheapest model in the family dramatically better, and the latest Claude Code release added cost controls that plug directly into subagent definitions.
This SOP walks six steps, from a one-minute availability check to the failure modes that fill GitHub issues. Each step ends with an expected result so you can verify before moving on. If you want a parallel hands-on for a different model provider, our DeepSeek-V4-Pro on Claude Code SOP covers swapping the backend with two environment variables - that one changes what model Claude Code talks to, this one changes how Claude Code organizes its work. And if you are still deciding which coding tool deserves your budget at all, the free AI coding credits comparison puts the mainstream options side by side.
Step 0: Align on Availability
A subagent is only as cheap as the plan it runs on, so confirm three things before writing any config.
- Check your Claude Code version. Two features in this SOP - the Agent-tool effort parameter and the plugin marketplace install flag - arrived in v2.1.292 per the October 7 release notes. Older builds will silently ignore both.
claude --version-
Confirm your access tier. Subagents work on Claude Pro and Max subscriptions as well as API-key setups, but the model routing in Step 3 only pays off when you can actually call Haiku-class models. If you run Claude Code against a third-party backend, verify that backend honors the model field - otherwise every subagent quietly runs on the same model.
-
Skim the built-in agents. Claude Code ships with three ready-made ones: Explore (read-only search on Haiku, with Quick, Medium, and Very thorough levels), Plan (gathers context before plan mode), and General-purpose (Sonnet with all tools). You may not need to write anything at all if a built-in already covers the job.
Expected result: you know your version number, you know which billing tier you are on, and you can name the three built-in agents without opening the docs. If your version is below v2.1.292, upgrade now so the Step 4 features exist when you reach them.
Step 1: Create Your First Subagent with /agents
Claude Code stores subagents as markdown files with YAML frontmatter. There are two locations, and the priority order matters:
- Project level: .claude/agents/ inside your repository. These take precedence and can be committed so the whole team shares them.
- User level: ~/.claude/agents/ in your home directory. These apply to every project you open and are ideal for personal workflow agents.
When both define the same name, the project-level file wins. Run the interactive manager:
/agentsYou get four options: Create, Edit, Delete, and View. Choose Create and let Claude generate the initial definition - it interviews you about the agent's purpose and writes the file. Then press e to open it in your editor and refine by hand. The generated draft is a starting point; the frontmatter fields in the next step are where quality is decided.
Save the file under .claude/agents/ for anything project-specific. Commit it. A subagent definition is exactly the kind of tribal knowledge that evaporates when a teammate asks "how did you automate that review?"
Expected result: a new markdown file exists under .claude/agents/, /agents lists it, and the file opens cleanly in your editor with a YAML block at the top and a system prompt below.
Step 2: Fill Every Frontmatter Field Deliberately
Each field changes runtime behavior, so go through them one by one rather than accepting the defaults. Here is a working code-reviewer definition we will reference throughout:
---
name: code-reviewer
description: Reviews code changes for quality and consistency. Use PROACTIVELY after writing or modifying code. MUST BE USED before any commit.
tools: Read, Grep, Glob, Bash
model: haiku
permissionMode: default
---name - lowercase with hyphens. This is the handle the main agent and teammates use to address the subagent, so keep it short and descriptive.
description - the single most important field. It decides when Claude Code automatically delegates to this agent. Write it with explicit trigger phrases: Use PROACTIVELY for should-fire-without-asking behavior, MUST BE USED for hard requirements. A vague description like "helps with code" means the agent never gets picked.
tools - the allowlist. Omit it and the subagent inherits every tool, which violates least privilege and makes the agent slower to reason about. A reviewer that can read and search but not write files cannot break anything.
model - one of sonnet, opus, haiku, or inherit (matching whatever the main session uses). Omit it and the default is sonnet. This field is the lever for everything in Step 3 and Step 4.
permissionMode - default, acceptEdits, or bypassPermissions. Use default for anything that touches your codebase; reserve bypassPermissions for sandboxed read-only agents where you have verified the tool list.
skills - which skill packages the agent loads. Note that skills are not inherited from the parent session; if your agent needs one, list it here explicitly.
hooks - optional PreToolUse, PostToolUse, and Stop hooks for automation around the agent's tool calls. Note that one-time hooks are not supported here.
Expected result: your subagent file has every field above filled with a deliberate value, the name is lowercase-hyphenated, and the description contains at least one explicit trigger phrase.
Step 3: Route Models by Task Shape
The routing strategy that dominates community production setups is simple: default to Haiku for subagents unless the task requires reasoning. Haiku handles lookup, summarization, classification, and extraction. Sonnet handles multi-file changes and debugging. Opus handles architecture decisions that get revisited rarely but shape everything downstream.
A widely shared third-party comparison illustrates the spread on a representative research task - these are single-source community numbers, not official benchmarks, so treat them as magnitudes:
| Agent model | Time | Cost | Output quality rating |
|---|---|---|---|
| Haiku | ~8 seconds | ~$0.03 | ~60% |
| Sonnet | ~45 seconds | ~$0.24 | ~85% |
| Opus | ~2 minutes | ~$1.20 | ~95% |
Read the table as a routing rule, not a scoreboard: a 40x cost gap between the cheapest and priciest option means the wrong default is expensive at scale. If you fan out five search subagents per session and each runs on Opus out of laziness, you have spent more on lookups than on the actual implementation. When your main session runs on a heavier model, the inherit option keeps subagents consistent with it - use it when you cannot articulate why a subagent needs something different.
For the boundary cases, ask one question: does this task need judgment across many files, or retrieval within a known scope? Retrieval is Haiku territory. Judgment is Sonnet. Judgment that redefines the project is Opus, and it probably belongs in the main agent anyway, which is the discipline Step 5 formalizes.
Expected result: every subagent you own now declares an intentional model - Haiku for find-and-summarize agents, Sonnet for edit-and-debug agents, and no unexamined defaults left.
Step 4: Pair with Claude Haiku 5.5 and the New Effort Knob
This is where the SOP connects to the batch's hotspot. The model field above does not pin a specific release - fill in haiku and Claude Code resolves it to the latest Haiku, which since October 7 is Haiku 5.5. That matters because the Haiku 5.5 release details show pricing at $0.10 per million input tokens and $0.50 per million output on the under-100K tier, a 1M-token context (up from 200K), and - per Anthropic's own published benchmarks - large jumps on terminal and agentic evaluations versus Haiku 4.5. In plain terms: the search-and-summarize agents from Step 3 just got dramatically more capable at the same routing slot, and the wide context window means a single Explore-style agent can swallow big file listings without spilling.
Two Claude Code features from the v2.1.292 release notes sharpen the pairing. First, the Agent tool accepts an effort parameter, so a subagent can run at a reduced effort level when a task is easy and at full effort when it is hard - within one request you trade cost against intelligence, which is precisely the decision Step 3 makes per agent. Second, plugin distribution got easier: claude plugin install --marketplace lets you pull packaged agents and skills from a marketplace instead of hand-copying files, which is how team conventions spread.
If your routing also uses Sonnet for the heavy subagents, note the simultaneous change on that side: Sonnet 5.5's cache-read price halved to $0.10 per million, which Anthropic says cuts costs about 20% for most agentic workloads. For teams budgeting across providers, our coding-tool credits comparison shows where subscription credits and API pricing intersect.
Expected result: a Haiku-routed subagent in your project completes a real search task, and you can see in the session cost display that it spent cents, not dollars. If you set an effort level, confirm the agent respects it on an easy query.
Step 5: Avoid the Four Classic Failures
The recurring failure reports in Claude Code's GitHub issues cluster into four patterns. Each has a one-line fix.
Failure 1: using subagents for implementation. Subagents cannot spawn further subagents - the Task tool is not passed to them - and their results come back as a summary, not as live working state. Anthropic's own guidance, echoed by engineer Adam Wolf, is that subagents are best at looking things up and returning short summaries. Implementation that mutates many files belongs in the main agent, where you can course-correct mid-stream. Fix: restrict subagent purposes to research, review, and verification.
Failure 2: vague descriptions. An agent described as "a helpful assistant" is never auto-selected, because delegation matching runs on the description text. Fix: rewrite descriptions with explicit trigger phrases per Step 2, then test that delegation actually fires.
Failure 3: tools-wide-open. Inheriting every tool makes agents slower, riskier, and harder to debug. Fix: allowlist per purpose - a test-writer needs test runners and file read access, not your deployment hooks.
Failure 4: re-briefing tax. Every subagent starts with zero context, so if you delegate twenty small interleaved tasks, you pay the project briefing twenty times. Community reports describe sessions burning hundreds of thousands of tokens on repeated context this way. Fix: batch related lookups into one subagent call with a thorough brief, and keep chatty iteration in the main agent.
Expected result: an audit of your subagent definitions shows no implementation-assigned subagents, no vague descriptions, no unbounded tool lists, and delegation patterns that batch related work.
FAQ
Q1: Where exactly do subagent files live, and which location wins on conflict?
A1: Project-level files go in the .claude/agents/ directory of your repository, user-level files in the agents folder under your home directory. When both define the same agent name, the project-level definition takes precedence. Commit the project-level ones so your whole team inherits the same roster.
Q2: What happens if I omit the tools field?
A2: The subagent inherits every tool available to the main session. That is convenient but against least-privilege practice - the agent can do more than its job requires, and the broader surface makes behavior harder to predict. Always declare an explicit allowlist for production agents.
Q3: Which model should a new subagent use by default?
A3: The community production answer is Haiku unless the task requires reasoning. Lookups, summaries, classification, and extraction run fine on Haiku and cost an order of magnitude less; reach for Sonnet when the agent edits multiple files or debugs, and reserve Opus for architectural judgment, which usually belongs in the main agent anyway.
Q4: Do subagents share context with the main conversation?
A4: No. Each subagent runs in its own independent context window, like a fork of the project view. It returns only a summary to the main thread, which keeps the main context clean - but it also means the subagent knows nothing from your conversation unless you put it in the prompt, and it cannot recursively launch other subagents.
Q5: How does the new effort parameter interact with model routing?
A5: Routing (Step 3) picks the model per subagent; the effort parameter, added to the Agent tool in Claude Code v2.1.292, then tunes how hard that model works within a request. Together they let a cheap Haiku agent run at minimal effort for trivial lookups while the same definition can be called with higher effort when the task deserves it.