Shayan Rais
4.0 KiB
4.0 KiB
Sub-agents Best Practice
Claude Code subagents — frontmatter fields and official built-in agent types.
| ← Back to Claude Code Best Practice |  |
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 to use: sonnet, opus, haiku, a full model ID (e.g., claude-opus-4-6), 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 (Opus 4.6 only). 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 | Display color for the subagent in the task list and transcript: red, blue, green, yellow, purple, orange, pink, or cyan |
(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 |