Anthropic Agent Spec — Official Reference
Source: https://code.claude.com/docs/en/sub-agents (fetched 2026-09-09)
Documented Frontmatter Fields
Only name and description are required.
| Field | Required | Description |
|---|---|---|
name |
Yes | Unique identifier using lowercase letters and hyphens |
description |
Yes | When Claude should delegate to this subagent |
tools |
No | Tools the subagent can use (allowlist). Inherits all tools if omitted |
disallowedTools |
No | Tools to deny, removed from inherited or specified list |
model |
No | sonnet, opus, haiku, fable, a full model ID, or inherit |
permissionMode |
No | default, acceptEdits, auto, dontAsk, bypassPermissions, plan, or manual (default alias) |
maxTurns |
No | Maximum number of agentic turns before the subagent stops |
skills |
No | Skills to preload at startup; unlisted skills remain invocable through the Skill tool |
mcpServers |
No | List of MCP servers; each entry is a configured-name string or one-key inline definition |
hooks |
No | Lifecycle hooks scoped to this subagent |
memory |
No | Persistent memory scope: user, project, or local |
background |
No | Set to true to always run as background task. Default: false |
effort |
No | low, medium, high, xhigh, or max; availability depends on the model |
isolation |
No | worktree — run in temporary git worktree |
color |
No | Display color: red, blue, green, yellow, purple, orange, pink, cyan |
initialPrompt |
No | Auto-submitted as first user turn when running as main agent via --agent |
Total: 16 fields in Anthropic's public supported-frontmatter table.
Runtime Experimental Extension
Claude Code v2.1.248+ also recognizes an experimental object whose current
cacheTtl value accepts 5m or 1h. This runtime extension is intentionally
kept separate from the 16 fields in the public documentation table because
experimental options can change or disappear without the stability expected of
documented frontmatter.
Key Facts
- The body (markdown after frontmatter) becomes the system prompt that guides the subagent
- Subagents receive ONLY the system prompt + basic environment details, NOT the full Claude Code system prompt
toolsis an allowlist (like skills'allowed-tools)disallowedToolsis a denylist — if both set, disallowed applied first, then tools resolved- Naming parallel (marketplace note): agents use camelCase
disallowedTools; skills use kebab-casedisallowed-tools(schema 3.7.0+). The validator rejects either mismatch — never copy-paste between agent and skill frontmatter without renaming - Subagents can spawn nested subagents when
Agentis available, up to three layers below the main conversation by default.CLAUDE_CODE_MAX_AGENT_SPAWN_DEPTHcan set the depth from 1 through 3; omit or denyAgentto prevent delegation. - The
skillsfield preloads full skill content, but subagents can still invoke unlisted project, user, and plugin skills through the Skill tool
Plugin Agent Restrictions
The IS agent gate separately rejects compatible-with and when_to_use on
agents. Put activation context in description or the body. The optional
when_to_use skill field has a different contract; do not copy it onto agents.
Claude Code ignores these fields on plugin agents (plugins/*/agents/*.md):
hooks— ignored when loading from pluginmcpServers— ignored when loading from pluginpermissionMode— ignored when loading from plugin
These are standalone-only features. If needed, copy the agent to .claude/agents/ or ~/.claude/agents/.
Tool Scoping
Main-thread agents launched with --agent can use Agent(type) syntax to restrict
which subagents they spawn. Inside a subagent, including Agent enables nested
delegation while the depth limit allows it, but a parenthesized type list is ignored.
Skills Preloading
skills:
- api-conventions
- error-handling-patternsFull content of each skill is injected at startup. This is the inverse of context: fork in skills.
Model Resolution Order
CLAUDE_CODE_SUBAGENT_MODELenv var- Per-invocation
modelparameter - Subagent definition's
modelfrontmatter - Main conversation's model
Example Agent File
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.Scope Priority (highest to lowest)
- Managed settings (organization-wide)
--agentsCLI flag (current session only).claude/agents/(project)~/.claude/agents/(personal)- Plugin
agents/directory (where plugin enabled)