Skip to main content

​
What Are Subagents?

Subagents are custom AI agents with their own configuration, including:
  • Name and color for visual distinction
  • Tool allowlist to control what they can access
  • Model selection (haiku, sonnet, opus, or inherit)
  • Permission mode for auto-approving actions
  • Preloaded skills for domain knowledge
  • MCP servers for external integrations
  • Lifecycle hooks for events
Subagents are defined in .claude/agents/<name>.md with YAML frontmatter and invoked via the Task tool.

​
Why Subagents Matter

Subagents enable specialization and orchestration:
  • Specialized expertise: Create agents for specific domains (frontend, backend, DevOps)
  • Tool isolation: Limit what each agent can do for safety
  • Parallel execution: Multiple agents can work on different parts of a codebase
  • Persistent memory: Agents remember context across sessions
  • Progressive disclosure: Preload skills for focused context
Subagents cannot invoke other subagents via bash commands. Always use the Task tool.

​
Key Concepts

​
Built-in vs Custom Agents

Built-in agents (available out-of-the-box):
AgentModelToolsUse Case
general-purposeinheritAllComplex multi-step tasks, the default
ExplorehaikuRead-onlyFast codebase search and exploration
PlaninheritRead-onlyPre-planning research before coding
claude-code-guideinheritRead, WebFetch, WebSearchAnswers Claude Code feature questions
Custom agents (defined by you): Create agents tailored to your project’s needs with specific tools, skills, and behavior.

​
Invocation via Task Tool

Always invoke subagents using the Task tool: 
Task(subagent_type="agent-name", description="...", prompt="...", model="haiku")
Never use bash commands like claude agent-name — this won’t work.

​
Frontmatter Fields

​
name
string
required
Unique identifier using lowercase letters and hyphens. Used in Task(subagent_type="name").
​
description
string
required
When to invoke this agent. Use "PROACTIVELY" for auto-invocation by Claude.Example: "Use this agent PROACTIVELY for deployment pipelines"
​
tools
string or list
Comma-separated allowlist of tools. Inherits all tools if omitted.Examples:
  • Read, Write, Edit, Bash
  • Task(agent_type) — Restrict which subagents this agent can spawn
  • ["Read", "Grep", "Glob"]
​
disallowedTools
string or list
Tools to deny, removed from inherited or specified list.Example: NotebookEdit, WebSearch
​
model
string
default:"inherit"
Model alias: haiku, sonnet, opus, or inherit (uses parent’s model).
​
permissionMode
string
Permission mode for this agent:
  • default — Standard permission checking
  • acceptEdits — Auto-accept file edits
  • dontAsk — Bypass most prompts
  • bypassPermissions — Skip all permission checks (dangerous)
  • plan — Read-only planning mode
​
maxTurns
integer
Maximum number of agentic turns before the subagent stops.Example: 25
​
skills
list
Skill names to preload into agent context at startup. Full skill content is injected, not just made available.Example:
skills:
  - deploy-checklist
  - rollback-procedures
​
mcpServers
list
MCP servers for this subagent — server name strings or inline configs.Example:
mcpServers:
  - slack
  - name: pagerduty
    command: npx
    args: ["-y", "@pagerduty/mcp-server"]
​
hooks
object
Lifecycle hooks scoped to this subagent.Supported events: PreToolUse, PostToolUse, PermissionRequest, PostToolUseFailure, Stop (converted to SubagentStop at runtime), SubagentStop
See the Hooks concept page for full details on agent hooks.
​
memory
string
Persistent memory scope:
  • user — Stored in ~/.claude/agent-memory/<name>/, not shared
  • project — Stored in .claude/agent-memory/<name>/, committed to git
  • local — Stored in .claude/agent-memory-local/<name>/, not committed
​
background
boolean
default:"false"
Set to true to always run as a background task.
​
isolation
string
Set to "worktree" to run in a temporary git worktree (auto-cleaned if no changes).
​
color
string
CLI output color for visual distinction.Examples: green, magenta, blue, teal

​
Real Examples

---
name: code-reviewer
description: Reviews code for quality issues
tools: Read, Grep, Glob
model: haiku
---

Review the code for quality issues and report findings.

​
How to Use Subagents

1

Create an agent definition

Create a markdown file in .claude/agents/ with YAML frontmatter:
mkdir -p .claude/agents
touch .claude/agents/my-agent.md
2

Define agent configuration

Add frontmatter and instructions:
---
name: my-agent
description: Specialized agent for X
tools: Read, Write, Edit
model: sonnet
---

You are a specialized agent for X.
Follow these procedures...
3

Invoke from commands or main agent

Use the Task tool to invoke your agent:
Task(
  subagent_type="my-agent",
  description="Do X",
  prompt="Specific instructions for this invocation"
)

​
Agent Skills (Preloaded Knowledge)

Preload skills into agents for focused domain knowledge: 
---
name: weather-agent
skills:
  - weather-fetcher  # Preloaded at agent startup
---

Follow the weather-fetcher skill instructions to fetch temperature.
The weather-fetcher skill is injected into the agent’s context at startup. The agent sees the full skill content without needing to invoke it separately.
Pattern: Agent skills (preloaded via skills: field) vs Skills (invoked via Skill tool). See the Skills concept page for details.

​
Agent Memory

Agents can persist memory across sessions:
ScopeLocationSharedVersion Control
user~/.claude/agent-memory/<name>/NoNo
project.claude/agent-memory/<name>/YesYes
local.claude/agent-memory-local/<name>/NoNo
---
name: weather-agent
memory: project
---

Update your agent memory with the reading details for historical tracking.

Agent Memory Report

Deep dive into persistent memory scopes and how agents learn across sessions

​
Best Practices

Instead of general “backend-engineer” or “frontend-engineer” agents, create agents for specific features or domains:Good: deploy-manager, api-tester, database-migratorBad: general-engineer, code-helper
Combine agents with skills for progressive disclosure:
---
name: presentation-curator
skills:
  - presentation-structure
  - presentation-styling
  - vibe-to-agentic-framework
---

You have three preloaded skills with all the presentation knowledge.
Only give agents the tools they need:
# Good: Read-only explorer
tools: Read, Grep, Glob

# Bad: Unrestricted access
# (tools field omitted = inherits all tools)
  • haiku for simple, fast operations
  • sonnet for most tasks
  • opus for complex reasoning
  • inherit to use parent’s model
Add “PROACTIVELY” to the description so Claude knows to invoke the agent automatically:
description: Use this agent PROACTIVELY for deployment pipelines

​
Scope and Priority

When multiple agents share the same name:
1

CLI flag (highest)

--agents '{...}' — Session-scoped agents defined via CLI
2

Project

.claude/agents/ — Project-specific agents, committed to git
3

User

~/.claude/agents/ — Personal agents across all projects
4

Plugin (lowest)

<plugin>/agents/ — Agents from installed plugins

​
Orchestration Patterns

​
Command → Agent → Skill

The recommended pattern for complex workflows:
  1. Command provides the entry point and user interaction
  2. Agent executes tasks with preloaded skills
  3. Skill creates outputs independently
# Command: /weather-orchestrator
---
description: Fetch weather and create SVG card
---

Step 1: Ask user for Celsius or Fahrenheit
Step 2: Task(subagent_type="weather-agent", ...)
Step 3: Skill(skill="weather-svg-creator")

# Agent: weather-agent
---
name: weather-agent
skills:
  - weather-fetcher  # Preloaded
---

Follow weather-fetcher skill to fetch temperature.

Orchestration Workflow

See the complete Command → Agent → Skill pattern with diagrams

Commands

Learn how commands orchestrate agents

Skills

Preload skills into agents for domain knowledge

Hooks

Add lifecycle hooks to agents

Subagents Best Practice

Complete frontmatter reference and built-in agents

​
Further Reading

Build docs developers (and LLMs) love

Get started for freeTalk to us