Skip to main content
Last Updated: February 28, 2026 3:22 PM PKT
Complete reference for Claude Code subagents — built-in agent types, custom agent definitions, and frontmatter fields.

​
Frontmatter Fields

​
name
string
required
Unique identifier using lowercase letters and hyphens
​
description
string
required
When to invoke. Use "PROACTIVELY" for auto-invocation by Claude
​
tools
string | list
Comma-separated allowlist of tools (e.g., Read, Write, Edit, Bash). Inherits all tools if omitted. Supports Task(agent_type) syntax to restrict spawnable subagents
​
disallowedTools
string | list
Tools to deny, removed from inherited or specified list
​
model
string
Model alias: haiku, sonnet, opus, or inherit (default: inherit)
​
permissionMode
string
Permission mode: default, acceptEdits, dontAsk, bypassPermissions, or plan
​
maxTurns
integer
Maximum number of agentic turns before the subagent stops
​
skills
list
Skill names to preload into agent context at startup (full content injected, not just made available)
​
mcpServers
list
MCP servers for this subagent — server name strings or inline {name: config} objects
​
hooks
object
Lifecycle hooks scoped to this subagent: PreToolUse, PostToolUse, Stop (converted to SubagentStop at runtime)
​
memory
string
Persistent memory scope: user, project, or local
​
background
boolean
Set to true to always run as a background task (default: false)
​
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 (e.g., green, magenta). Functional but absent from official frontmatter table — documented in interactive quickstart only

​
Memory Scopes

ScopeStorage LocationSharedVersion Controlled
user~/.claude/agent-memory/<name>/NoNo
project.claude/agent-memory/<name>/YesYes
local.claude/agent-memory-local/<name>/NoNo
See claude-agent-memory.md for full details.

​
Invocation

Agents are invoked via the Task tool, never via bash commands: 
Task(subagent_type="agent-name", description="...", prompt="...", model="haiku")
Critical: Subagents cannot invoke other subagents via bash commands. Always use the Task tool.
Other invocation and management methods:

CLI Flag

--agents '{...}' — Define session-scoped agents via JSON

List Agents

claude agents — List all configured agents grouped by source

Interactive Management

/agents — Create, edit, and manage agents interactively

Command Delegation

A command file can delegate to an agent

Agent Resumption

Completed subagents can be resumed with their agent ID

​
Example: Minimal Agent

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

Review the code for quality issues and report findings.

---
name: deploy-manager
description: Use this agent PROACTIVELY for deployment pipelines and release management
tools: Read, Write, Edit, Bash, Grep, Glob, Task(monitor, rollback)
disallowedTools: NotebookEdit
model: sonnet
permissionMode: acceptEdits
maxTurns: 25
skills:
  - deploy-checklist
  - rollback-procedures
mcpServers:
  - slack
  - name: pagerduty
    command: npx
    args: ["-y", "@pagerduty/mcp-server"]
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-deploy-command.sh"
  PostToolUse:
    - matcher: "Write"
      hooks:
        - type: command
          command: "./scripts/log-file-changes.sh"
  Stop:
    - hooks:
        - type: command
          command: "./scripts/notify-deploy-complete.sh"
memory: project
background: false
isolation: worktree
color: blue
---

You are a deployment manager. Follow the deploy-checklist skill for
pre-flight checks and use rollback-procedures if any step fails.
Notify the team via Slack when deployment completes.

​
Scope and Priority

When multiple subagents share the same name, the higher-priority location wins:
LocationScopePriority
--agents CLI flagCurrent session1 (highest)
.claude/agents/Current project2
~/.claude/agents/All your projects3
Plugin’s agents/ directoryWhere plugin is enabled4 (lowest)

​
Claude Agents

​
Official Claude Agents

Built-in agent types available via subagent_type in the Task tool:
Model: inherit | Tools: AllComplex multi-step tasks — the default agent type for research, code search, and autonomous work
Model: haiku | Tools: Read-only (no Write, Edit)Fast codebase search and exploration — optimized for finding files, searching code, and answering codebase questions
Model: inherit | Tools: Read-only (no Write, Edit)Pre-planning research in plan mode — explores the codebase and designs implementation approaches before writing code
Model: inherit | Tools: Glob, Grep, Read, WebFetch, WebSearchAnswers questions about Claude Code features, hooks, slash commands, MCP servers, settings, IDE integrations, and keyboard shortcuts
Model: inherit | Tools: Read, EditConfigures the user’s Claude Code status line setting

​
Custom Agents Example

Model: sonnet | Color: magentaTools: Read, Write, Edit, Grep, GlobSkills:
  • presentation/vibe-to-agentic-framework
  • presentation/presentation-structure
  • presentation/presentation-styling
Manages presentation updates with self-evolving skills.

​
Sources

Create Custom Subagents

Official documentation for subagent creation

CLI Reference

Command-line flags and options

CHANGELOG

Latest updates and features

Build docs developers (and LLMs) love

Get started for freeTalk to us