Sub-agents Best Practice
Last Updated: Apr 04, 2026 | Claude Code v2.1.92
Claude Code subagents -- frontmatter fields and official built-in agent types.
Frontmatter Fields (16)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Unique identifier using lowercase letters and hyphens |
description | string | Yes | When to invoke. Use "PROACTIVELY" for auto-invocation by Claude |
tools | string/list | No | Comma-separated allowlist of tools (e.g., Read, Write, Edit, Bash). Inherits all tools if omitted. Supports Agent(agent_type) syntax to restrict spawnable subagents; the older Task(agent_type) alias still works |
disallowedTools | string/list | No | Tools to deny, removed from inherited or specified list |
model | string | No | Model alias: haiku, sonnet, opus, or inherit (default: inherit) |
permissionMode | string | No | Permission mode: default, acceptEdits, auto, dontAsk, bypassPermissions, or plan |
maxTurns | integer | No | Maximum number of agentic turns before the subagent stops |
skills | list | No | Skill names to preload into agent context at startup (full content injected, not just made available) |
mcpServers | list | No | MCP servers for this subagent -- server name strings or inline {name: config} objects |
hooks | object | No | Lifecycle hooks scoped to this subagent. All hook events are supported; PreToolUse, PostToolUse, and Stop are the most common |
memory | string | No | Persistent memory scope: user, project, or local |
background | boolean | No | Set to true to always run as a background task (default: false) |
effort | string | No | Effort level override when this subagent is active: low, medium, high, max. Default: inherits from session |
isolation | string | No | Set to "worktree" to run in a temporary git worktree (auto-cleaned if no changes) |
initialPrompt | string | No | Auto-submitted as the first user turn when this agent runs as the main session agent (via --agent or the agent setting). Commands and skills are processed. Prepended to any user-provided prompt |
color | string | No | CLI output color for visual distinction (e.g., green, magenta) |
Official Built-in Agents (5)
| # | Agent | Model | Tools | Description |
|---|---|---|---|---|
| 1 | general-purpose | inherit | All | Complex multi-step tasks -- the default agent type for research, code search, and autonomous work |
| 2 | Explore | haiku | Read-only (no Write, Edit) | Fast codebase search and exploration -- optimized for finding files, searching code, and answering codebase questions |
| 3 | Plan | inherit | Read-only (no Write, Edit) | Pre-planning research in plan mode -- explores the codebase and designs implementation approaches before writing code |
| 4 | statusline-setup | sonnet | Read, Edit | Configures the user's Claude Code status line setting |
| 5 | claude-code-guide | haiku | Glob, Grep, Read, WebFetch, WebSearch | Answers questions about Claude Code features, Agent SDK, and Claude API |