Subagents
Subagents
.claude/agents/*.md
Vendor docs
frontmatter
| name | type | required | meaning | concept | |
|---|---|---|---|---|---|
| background | string | Set to `true` to always run this subagent as a background task, even when Claude needs its result right away. When unset, Claude chooses, and as of v2.1.198 it runs subagents in the background by default | docs ↗ | ||
| color | string | Display color for the subagent in the task list and transcript. Accepts `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan` | docs ↗ | ||
| description | string | yes | When Claude should delegate to this subagent | docs ↗ | |
| disallowedTools | string | Tools to deny, removed from inherited or specified list | docs ↗ | ||
| effort | string | Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model | docs ↗ | ||
| hooks | string | Lifecycle hooks scoped to this subagent. Ignored for plugin subagents | docs ↗ | ||
| initialPrompt | string | 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 | docs ↗ | ||
| isolation | string | Set to `worktree` to run the subagent in a temporary git worktree, giving it an isolated copy of the repository branched by default from your default branch rather than the parent session's `HEAD`. The worktree is automatically cleaned u... | docs ↗ | ||
| maxTurns | string | Maximum number of agentic turns before the subagent stops | docs ↗ | ||
| mcpServers | string | MCP servers available to this subagent. Each entry is either a server name referencing an already-configured server (e.g., `"slack"`) or an inline definition with the server name as key and a full MCP server config as value. Ignored for ... | docs ↗ | ||
| memory | string | Persistent memory scope: `user`, `project`, or `local`. Enables cross-session learning | docs ↗ | ||
| model | string | Model to use: `sonnet`, `opus`, `haiku`, `fable`, a full model ID (for example, `claude-opus-4-8`), or `inherit`. Defaults to `inherit` | docs ↗ | ||
| name | string | yes | Unique identifier using lowercase letters and hyphens. Hooks receive this value as `agent_type`. The filename doesn't have to match | docs ↗ | |
| permissionMode | string | Permission mode: `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, or `manual` as an alias for `default`. The `manual` alias requires Claude Code v2.1.200 or later. Ignored for plugin subagents | docs ↗ | ||
| skills | string | Skills to preload into the subagent's context at startup. The full skill content is injected, not only the description. Subagents can still invoke unlisted project, user, and plugin skills through the Skill tool | docs ↗ | ||
| tools | string | Tools the subagent can use. Inherits all tools if omitted. To preload Skills into context, use the `skills` field rather than listing `Skill` here | docs ↗ |