Claude Code Subagents: The Complete 2026 Reference (Frontmatter, Scopes, Built-Ins, and Production Patterns)

If you’ve already read Claude Code Subagents: Best Practices 2026 for the how-to-think about subagent architecture, this is the complete reference page — every frontmatter field, every scope location, every built-in, verified against Anthropic’s official Claude Code documentation as of May 2026.

If you’re configuring subagents in production, this is the page to bookmark.

What a Subagent Is (One Paragraph)

From the official docs (May 2026): “Subagents are specialized AI assistants that handle specific types of tasks. Use one when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again: the subagent does that work in its own context and returns only the summary. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.”

A subagent is a Markdown file with YAML frontmatter, stored in one of five scope locations, that Claude Code can delegate to when a task matches its description. The subagent runs in its own context window and returns only its final output to the main conversation — this is the primary reason to use them.

The Five Scope Locations (Priority Order)

When multiple subagents share the same name, the higher-priority location wins:

Claude Code scans .claude/agents/ and ~/.claude/agents/ recursively — you can organize definitions into subfolders like agents/review/ or agents/research/. The subdirectory path does not affect the identifier; identity comes only from the name field. Keep name values unique across the entire tree. If two files in one scope declare the same name, Claude Code keeps one and discards the other without warning.

Plugin subagents have one quirk: a file at agents/review/security.md in plugin my-plugin registers as the scoped identifier my-plugin:review:security — the subfolder becomes part of the name.

The 17 Frontmatter Fields

Subagent files use YAML frontmatter. Only name and description are required.

---
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.

The body becomes the system prompt. Subagents receive only this system prompt plus basic environment details (working directory) — not the full Claude Code system prompt.

Required fields

Tool control

Special syntax for restricting which subagents can be spawned: tools: Agent(worker, researcher), Read, Bash. This is an allowlist — only worker and researcher can be spawned. Agent without parentheses allows any. Omitting Agent entirely prevents spawning any subagent.

Model selection

Resolution order when Claude invokes a subagent:

1. CLAUDE_CODE_SUBAGENT_MODEL environment variable, if set
2. Per-invocation model parameter
3. Subagent definition’s model field
4. Main conversation’s model

Use haiku for fast, cheap exploration agents (the built-in Explore does this). Use opus for deep reasoning agents. Use inherit when the subagent should match the parent session’s capability.

Permission modes

Plugin subagents ignore permissionMode (security restriction).

Persistent memory and execution control

isolation: worktree is especially powerful: the worktree is automatically cleaned up if the subagent makes no changes, and you get a totally isolated copy of the repo for experimental work.

Integration with other primitives

mcpServers inline trick: define a server inline here instead of in .mcp.json to keep the MCP tools out of the main conversation’s context. The subagent gets the tools; the parent doesn’t pay the context cost.

The Three Built-In Subagents

Claude Code ships with three built-ins that the parent agent invokes automatically. Each inherits the parent’s permissions with additional tool restrictions.

Explore

• Model: Haiku (fast, low-latency)
• Tools: Read-only (Write and Edit denied)
• Purpose: File discovery, code search, codebase exploration

Claude delegates to Explore when it needs to search or understand a codebase without making changes. Invocations specify a thoroughness level: quick for targeted lookups, medium for balanced exploration, very thorough for comprehensive analysis.

This is the subagent doing the heavy lifting in most “explore this codebase” workflows. Because it’s Haiku-based, it’s cheap to run in parallel — feel free to spawn 5–10 Explore subagents at once for a large repo.

Plan

• Model: Inherits from main conversation
• Tools: Read-only
• Purpose: Codebase research for planning

Used in plan mode to gather context before presenting a plan. Prevents infinite nesting (subagents cannot spawn other subagents), so Plan is the one that gets to research while the main agent stays in plan-presentation mode.

General-purpose

• Model: Inherits from main conversation
• Tools: All tools
• Purpose: Complex, multi-step tasks that need both exploration and action

Claude delegates here when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps. The most capable but also most expensive built-in.

Other helpers

Production Patterns

Pattern 1: Cheap Explorers + Expensive Closer

Spawn multiple Haiku-based Explore subagents in parallel to gather context, then have a single Opus-based main conversation synthesize. Cost-efficient for codebase Q&A and refactor planning.

---
name: codebase-mapper
description: Maps a codebase area with read-only Haiku for cost efficiency
tools: Read, Grep, Glob
model: haiku
---

Pattern 2: Isolated Worktree for Risky Experiments

Set isolation: worktree for experimental refactors. The subagent gets its own copy of the repo, makes changes, and either commits to a branch or has the worktree auto-cleaned if no changes are kept.

---
name: refactor-tryout
description: Try refactor in isolated worktree. Main repo unaffected.
isolation: worktree
permissionMode: acceptEdits
---

Pattern 3: MCP-Scoped to Subagent Only

Need Playwright for browser testing but don’t want its 30+ tool descriptions in the main context? Define it inline in a subagent.

---
name: browser-tester
description: Tests features in a real browser
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

The MCP server connects when the subagent starts and disconnects when it finishes. The parent conversation never sees the Playwright tools.

Pattern 4: Persistent Memory for Learning Agents

Add memory: project to let a subagent accumulate insights across conversations. Useful for code-reviewers that learn project conventions over time.

---
name: code-reviewer
description: Reviews code; learns project conventions over time
memory: project
model: sonnet
---

Memory lives at ~/.claude/agent-memory/<project>/<agent-name>/. The first 200 lines of MEMORY.md (or 25KB) are loaded into the subagent’s context at startup.

Pattern 5: Background Long-Running Tasks

Set background: true to always spawn this subagent as a background task. Useful for “watch and notify” agents that don’t need to block the main conversation.

---
name: test-watcher
description: Watches test output and notifies on failures
background: true
tools: Read, Bash
---

Pattern 6: Restricted Spawn Allowlist for Coordinators

When you run an agent as the main thread (claude --agent coordinator), it can spawn subagents via the Agent tool. To restrict which types it can spawn, use Agent(type1, type2) syntax:

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

If the coordinator tries to spawn anything else, the request fails and the coordinator only sees worker and researcher in its prompt as allowed types.

Subagents vs Skills vs Hooks (Three-Way Decision)

The most common confusion is Subagent vs Skill. Use a subagent when you need a separate context window (the work shouldn’t bloat the main session). Use a skill when you need a reusable procedure that can run inline in the main session.

For the broader configuration-file comparison, see AGENTS.md vs CLAUDE.md vs .cursor/rules.

Common Pitfalls

1. Naming collisions. Two files in the same scope with the same name — one wins silently. Always grep your ~/.claude/agents/ and .claude/agents/ trees for duplicate names.
2. Forgetting subagents can’t spawn subagents. This is by design (prevents infinite nesting). If your subagent needs to delegate further, it can’t — the architecture flattens to “main + first-level subagents.”
3. MCP context bloat. Defining MCP servers in .mcp.json makes their tool descriptions visible in every session. Define MCP inline in a subagent to keep them scoped.
4. Editing subagent files on disk and expecting hot-reload. Subagents are loaded at session start. Edit the file directly → restart. Edit via /agents UI → takes effect immediately.
5. acceptEdits outside the working directory. This mode auto-accepts only paths in the working directory or additionalDirectories. Anything outside still prompts.
6. plan mode without a Plan subagent. When the main agent is in plan mode and needs codebase research, it delegates to the Plan built-in. If you’ve shadowed Plan with a custom subagent of the same name, things break in subtle ways.

CLI-Defined Subagents (Ephemeral)

For one-off testing or automation scripts, pass subagent definitions as JSON when launching Claude Code. These exist only for the session — not saved to disk:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on quality, security, best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, provide fixes."
  }
}'

The --agents flag accepts JSON with the same fields as file-based subagents. Use prompt for the system prompt (equivalent to the markdown body).

FAQ

What’s the difference between a subagent and an agent team?

Subagents work within a single session, returning summaries to the parent. Agent teams are independent sessions that communicate with each other. For background work that runs in parallel and is monitored from one place, see Claude Code’s background agents feature.

Can a subagent spawn another subagent?

No, by design. This prevents infinite nesting. The architecture is two-level: main + first-level subagents. If you need delegation chains, use agent teams instead.

Where does subagent memory live?

~/.claude/agent-memory/<project>/<agent-name>/MEMORY.md. The first 200 lines (or 25KB) load at startup. Detail files (debugging.md, patterns.md) load on demand. Machine-local — not shared across machines or cloud environments.

What model does a subagent use by default?

inherit — same as the main conversation. You can override with sonnet, opus, haiku, a full model ID, or set CLAUDE_CODE_SUBAGENT_MODEL environment variable.

How do I make a subagent read-only?

Set tools: Read, Grep, Glob (allowlist) or disallowedTools: Write, Edit, MultiEdit, NotebookEdit (denylist). The allowlist is cleaner if you only need a few tools.

Can subagents access MCP servers?

Yes, three ways: (1) inherited from main session if mcpServers is omitted, (2) inline definition in the subagent’s mcpServers field (scoped to subagent only), (3) string reference to a session-configured server. Inline definitions are the trick for keeping MCP context out of the main conversation.

What’s isolation: worktree?

Runs the subagent in a temporary git worktree, giving it an isolated copy of the repository. Changes don’t affect the main repo unless you commit and merge. The worktree is auto-cleaned if the subagent makes no changes — useful for experimental refactors.

Plugin subagent restrictions?

Plugins cannot use hooks, mcpServers, or permissionMode (security restriction). If you need those fields, copy the agent file from the plugin into .claude/agents/ or ~/.claude/agents/.

How do I see what subagents are loaded?

Run /agents in Claude Code. The Library tab shows all subagents (built-in, user, project, plugin). The Running tab shows live subagents and lets you open or stop them.

Does the subagent filename have to match the name field?

No. Identity comes only from the name frontmatter field. The filename and subdirectory path don’t affect identification or invocation — except for plugin subagents where subfolders become part of the scoped identifier (my-plugin:review:security).

Related Articles

• Claude Code Subagents Best Practices 2026
• AGENTS.md vs CLAUDE.md vs .cursor/rules: Three-Way Comparison
• Inside Career-Ops: 14-Mode Skills Architecture Lessons
• Career-Ops on Claude Code: The Complete 2026 Reference
• 15 Best Claude Code Skills You Should Install in 2026
• Browse 165+ Real AI Coding Rules

External References

• Create custom subagents — Claude Code Docs (Anthropic, May 2026)
• Background agents
• Agent teams