skills/agent-creator/references/anthropic-agent-spec.md (3907 bytes)
1 # Anthropic Agent Spec — Official Reference 2 3 Source: https://code.claude.com/docs/en/sub-agents (fetched 2026-04-05) 4 5 ## Supported Frontmatter Fields 6 7 Only `name` and `description` are required. 8 9 | Field | Required | Description | 10 |:------|:---------|:------------| 11 | `name` | Yes | Unique identifier using lowercase letters and hyphens | 12 | `description` | Yes | When Claude should delegate to this subagent | 13 | `tools` | No | Tools the subagent can use (allowlist). Inherits all tools if omitted | 14 | `disallowedTools` | No | Tools to deny, removed from inherited or specified list | 15 | `model` | No | `sonnet`, `opus`, `haiku`, a full model ID, or `inherit`. Defaults to `inherit` | 16 | `permissionMode` | No | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, or `plan` | 17 | `maxTurns` | No | Maximum number of agentic turns before the subagent stops | 18 | `skills` | No | Skills to load into the subagent's context at startup (full content injected) | 19 | `mcpServers` | No | MCP servers available to this subagent (inline definition or string reference) | 20 | `hooks` | No | Lifecycle hooks scoped to this subagent | 21 | `memory` | No | Persistent memory scope: `user`, `project`, or `local` | 22 | `background` | No | Set to `true` to always run as background task. Default: `false` | 23 | `effort` | No | `low`, `medium`, `high`, `max` (Opus 4.6 only). Default: inherits from session | 24 | `isolation` | No | `worktree` — run in temporary git worktree | 25 | `color` | No | Display color: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` | 26 | `initialPrompt` | No | Auto-submitted as first user turn when running as main agent via `--agent` | 27 28 Total: 16 official fields. 29 30 ## Key Facts 31 32 - The **body** (markdown after frontmatter) becomes the **system prompt** that guides the subagent 33 - Subagents receive ONLY the system prompt + basic environment details, NOT the full Claude Code system prompt 34 - `tools` is an **allowlist** (like skills' `allowed-tools`) 35 - `disallowedTools` is a **denylist** — if both set, disallowed applied first, then tools resolved 36 - Naming parallel (marketplace note): agents use camelCase `disallowedTools`; skills use kebab-case `disallowed-tools` (schema 3.7.0+). The validator rejects either mismatch — never copy-paste between agent and skill frontmatter without renaming 37 - Subagents **cannot spawn other subagents** (no nesting) 38 - Subagents **don't inherit skills** from parent conversation — must list explicitly via `skills` field 39 40 ## Plugin Agent Restrictions 41 42 Plugin agents (`plugins/*/agents/*.md`) do NOT support: 43 44 - `hooks` — ignored when loading from plugin 45 - `mcpServers` — ignored when loading from plugin 46 - `permissionMode` — ignored when loading from plugin 47 48 These are standalone-only features. If needed, copy the agent to `.claude/agents/` or `~/.claude/agents/`. 49 50 ## Tool Scoping 51 52 Subagents can use `Agent(type)` syntax to restrict which subagents they can spawn (only for main-thread agents via `--agent`). 53 54 ## Skills Preloading 55 56 ```yaml 57 skills: 58 - api-conventions 59 - error-handling-patterns 60 ``` 61 62 Full content of each skill is injected at startup. This is the inverse of `context: fork` in skills. 63 64 ## Model Resolution Order 65 66 1. `CLAUDE_CODE_SUBAGENT_MODEL` env var 67 2. Per-invocation `model` parameter 68 3. Subagent definition's `model` frontmatter 69 4. Main conversation's model 70 71 ## Example Agent File 72 73 ```markdown 74 --- 75 name: code-reviewer 76 description: Reviews code for quality and best practices 77 tools: Read, Glob, Grep 78 model: sonnet 79 --- 80 81 You are a code reviewer. When invoked, analyze the code and provide 82 specific, actionable feedback on quality, security, and best practices. 83 ``` 84 85 ## Scope Priority (highest to lowest) 86 87 1. Managed settings (organization-wide) 88 2. `--agents` CLI flag (current session only) 89 3. `.claude/agents/` (project) 90 4. `~/.claude/agents/` (personal) 91 5. Plugin `agents/` directory (where plugin enabled)