tags:
- domain/agents
- artifact/doc
- source/skills-claude
Sub-agents Best Practice
Claude Code subagents — frontmatter fields and official built-in agent types.
<table width="100%"> <tr> <td><a href="../">← Back to Claude Code Best Practice</a></td> <td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td> </tr> </table>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 |
Sources
🔗 Связи
- [[MOC - Skills]] — Skills library
- [[skills/skills-claude]] — Category: skills-claude