Sub-agents Best Practice

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

string

required

Unique identifier using lowercase letters and hyphens

string

required

When to invoke. Use "PROACTIVELY" for auto-invocation by Claude

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

string | list

Tools to deny, removed from inherited or specified list

string

Model alias: haiku, sonnet, opus, or inherit (default: inherit)

string

Permission mode: default, acceptEdits, dontAsk, bypassPermissions, or plan

integer

Maximum number of agentic turns before the subagent stops

list

Skill names to preload into agent context at startup (full content injected, not just made available)

list

MCP servers for this subagent — server name strings or inline {name: config} objects

object

Lifecycle hooks scoped to this subagent: PreToolUse, PostToolUse, Stop (converted to SubagentStop at runtime)

string

Persistent memory scope: user, project, or local

boolean

Set to true to always run as a background task (default: false)

string

Set to "worktree" to run in a temporary git worktree (auto-cleaned if no changes)

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

Scope	Storage Location	Shared	Version Controlled
`user`	`~/.claude/agent-memory/<name>/`	No	No
`project`	`.claude/agent-memory/<name>/`	Yes	Yes
`local`	`.claude/agent-memory-local/<name>/`	No	No

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.

Example: Full-Featured Agent (All Fields)

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

Location	Scope	Priority
`--agents` CLI flag	Current session	1 (highest)
`.claude/agents/`	Current project	2
`~/.claude/agents/`	All your projects	3
Plugin’s `agents/` directory	Where plugin is enabled	4 (lowest)

Claude Agents

Official Claude Agents

Built-in agent types available via subagent_type in the Task tool:

general-purpose

Model: inherit | Tools: AllComplex multi-step tasks — the default agent type for research, code search, and autonomous work

Explore

Model: haiku | Tools: Read-only (no Write, Edit)Fast codebase search and exploration — optimized for finding files, searching code, and answering codebase questions

Plan

Model: inherit | Tools: Read-only (no Write, Edit)Pre-planning research in plan mode — explores the codebase and designs implementation approaches before writing code

claude-code-guide

Model: inherit | Tools: Glob, Grep, Read, WebFetch, WebSearchAnswers questions about Claude Code features, hooks, slash commands, MCP servers, settings, IDE integrations, and keyboard shortcuts

statusline-setup

Model: inherit | Tools: Read, EditConfigures the user’s Claude Code status line setting

Custom Agents Example

presentation-curator
weather-agent

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

Get Started

Core Concepts

Best Practices

Workflows & Patterns

Implementation Examples

Frontmatter Fields

Memory Scopes

Invocation

CLI Flag

List Agents

Interactive Management

Command Delegation

Agent Resumption

Example: Minimal Agent

Example: Full-Featured Agent (All Fields)

Scope and Priority

Claude Agents

Official Claude Agents

Custom Agents Example

Sources

Create Custom Subagents

CLI Reference

CHANGELOG

​Frontmatter Fields

​Memory Scopes

​Invocation

CLI Flag

List Agents

Interactive Management

Command Delegation

Agent Resumption

​Example: Minimal Agent

​Example: Full-Featured Agent (All Fields)

​Scope and Priority

​Claude Agents

​Official Claude Agents

​Custom Agents Example

​Sources

Create Custom Subagents

CLI Reference

CHANGELOG

Frontmatter Fields

Memory Scopes

Invocation

Example: Minimal Agent

Example: Full-Featured Agent (All Fields)

Scope and Priority

Claude Agents

Official Claude Agents

Custom Agents Example

Sources