title: "Subagents" description: "Delegate tasks to isolated agents — parallel execution, specialized roles, and persistent memory" section: "Core" readTime: "8 min" badge: "NEW"

Subagents

Subagents let Claude delegate tasks to isolated agent contexts that run with their own conversation history, tools, and memory. Use them to parallelize work, isolate risky operations, or specialize agents for different roles.

Why Subagents

Built-in Agent Types

Custom Agents

Define custom subagents in .claude/agents/<name>.md (project) or ~/.claude/agents/<name>.md (personal):

---
name: security-reviewer
description: Reviews code for security vulnerabilities. Use when auditing PRs, new API endpoints, or auth flows.
model: claude-opus-4
effort: high
allowed-tools: Read Glob Grep
---
 
You are a security-focused code reviewer. When reviewing code:
 
1. Check for injection vulnerabilities (SQL, command, path traversal)
2. Verify authentication and authorization on every endpoint
3. Look for hardcoded secrets or API keys
4. Flag insecure dependencies
5. Check input validation at system boundaries
 
Return findings as: CRITICAL / HIGH / MEDIUM / LOW with file references.

Claude invokes this automatically when you ask for a security review, or you can call it directly: /security-reviewer.

Frontmatter fields for agents

Preloading Skills into Subagents

List skills in the skills frontmatter field to inject their full content at subagent startup:

---
name: api-builder
description: Builds REST API endpoints following our conventions
skills:
  - api-conventions
  - error-handling-patterns
  - openapi-docs
---
 
Build the API endpoint described by the user. Follow the loaded conventions.

Unlike regular sessions (where skills load on demand), preloaded skills are fully injected at startup. The subagent has all the context it needs from the first turn.

Run a Skill as a Subagent

Add context: fork to a skill's frontmatter to run it in isolation:

---
name: deep-research
description: Research a topic thoroughly without polluting the main session
context: fork
agent: Explore
---
 
Research $ARGUMENTS:
 
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references and line numbers

The skill content becomes the subagent's task. Results are summarized back into your main conversation.

Parallel Execution with /batch

Run multiple subagents simultaneously using the bundled /batch skill:

/batch
  "Implement the user authentication module"
  "Set up database migration for the users table"
  "Write integration tests for the login endpoint"

All three run in parallel. Each gets its own isolated context. Wall-clock time is roughly that of the slowest task — but token cost is 3×.

When to use parallel agents:

• Tasks that are truly independent (no shared file writes)
• Time matters more than cost
• Each task is well-defined with clear scope

Subagent Memory

Subagents can maintain their own auto memory, separate from the main session. Enable it in the .agent.md definition:

---
name: db-specialist
description: Database design and migration specialist
memory: true
---

The subagent accumulates knowledge across sessions: table naming conventions it learned, migration patterns that worked, performance optimizations it discovered.

Delegation Pattern

Claude decides to spawn a subagent when:

1. The task is self-contained and doesn't need conversation history
2. A skill has context: fork set
3. You explicitly ask Claude to delegate
4. /batch is used

The result comes back as a summary in your main conversation. You can ask for more detail or iterate from there.

Related

• Skills — context: fork and agent frontmatter
• Hooks — Lifecycle events that apply to subagents
• Plugins — Distribute custom agents as plugins
• Agent Teams — Orchestrating parallel agent workflows