Subagents

What are they for?

On large tasks, instead of doing everything linearly, Claude Code can distribute work among several subagents with specific roles (reviewer, planner, debugger, researcher). Benefits:

• Parallelism: several working at once = faster.
• Clean context: each subagent has its own "memory", without mixing.
• Specialization: each one with its own instructions and tools.
• Background: they can run in the background without blocking you.

Creating a subagent

A subagent is a Markdown file with YAML frontmatter (configuration) and a body that serves as its system prompt (its personality and role instructions).

.claude/agents/
├── revisor.md
├── depurador.md
└── investigador.md

Example: a code reviewer subagent

---
name: revisor
description: Reviews code for bugs and bad practices. Use it after writing or changing code.
tools: Read, Grep, Glob
model: sonnet
color: blue
---

You are a senior code reviewer. Your job is to read the changes and find:
- Potential bugs and uncovered edge cases.
- Unclear names and hard-to-maintain code.
- Security issues.

Do not edit files: only report what you find, ordered by severity.
Be direct but constructive.

Frontmatter fields

Where they are stored

• Project (recommended): .claude/agents/<name>.md
• Personal: ~/.claude/agents/<name>.md
• Via plugin: inside the plugin ( agents/... )
• Session only: with the --agents '{...}' flag (not saved to disk)

How to invoke them

Natural delegation

Simply ask the main agent:

Direct mention

@"revisor (agent)" review src/pagos.ts

Interactive assistant

Use the /agents command to open an assistant that guides you through creating and managing subagents without writing YAML by hand.

From the terminal

# Launch with a specific subagent
claude --agent revisor

# View, monitor, and manage subagents in parallel
claude agents

Creating one without knowing YAML

Subagents in parallel (real example)

What changed in v2.1.232

A subagent with subagent_type: "fork" can inherit the full conversation and prompt cache. Non-teammate agent spawns from interactive sessions now run in the background by default.

Do not treat every subagent as a fork. Use isolated subagents for bounded research or review, use a fork when the full history is necessary, and use /fork when you want a separate visible background session. More agents add cost and coordination; start with one.

Verified source

Claude Code v2.1.232 release notes, reviewed August 16, 2026.