Subagent Frontmatter

An agent file is a Markdown file that defines a subagent. The keys at the top of the file (the frontmatter) set its name, tools, model, and limits. The body is its prompt. For example, a file with name: reviewer and tools: Read, Grep makes a read-only review agent.

Edit the file, or pass --agents JSON. To turn a subagent off, delete the file or deny Agent(name) in permissions.deny.

Example

claude --agents '{
  "tester": {
    "description": "Runs the test suite and reports failures.",
    "prompt": "Run the tests. Report each failing test and its error.",
    "tools": ["Bash", "Read"],
    "model": "haiku",
    "maxTurns": 10
  }
}'

Keys

Key	Status	What it does	Notes
`name`	Documented: An official docs page names this item.	The unique ID of the agent.	At most 256 characters. Must not start with `-` or contain `:`. Hooks receive it as `agent_type`. Claude Code treats a file with no `name` as documentation.
`description`	Documented: An official docs page names this item.	Tells Claude when to delegate to the agent.	Required. Claude Code skips a file with `name` but no `description`. A literal `\n` becomes a newline. It may not be empty in `--agents` JSON.
`tools`	Documented: An official docs page names this item.	An allowlist of tools.	A comma-separated string or a YAML list. If you omit it, the agent inherits all tools that subagents can use. `Agent(a, b)` limits which types a `--agent` main thread can start. `mcp__server__*` picks a whole server.
`disallowedTools`	Documented: An official docs page names this item.	A denylist of tools. Claude Code applies it first. Then `tools` resolves against what remains.	An entry such as `Bash(git push )` removes the whole tool. `mcp__github__` withholds MCP tools.
`model`	Documented: An official docs page names this item.	The model of the agent.	`sonnet`, `opus`, `haiku`, `fable`, a full model ID, or `inherit`. Order of choice: the per-call `model`, this field, `CLAUDE_CODE_SUBAGENT_MODEL`, the main model. `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1` forces one model. See Models.
`permissionMode`	Documented: An official docs page names this item.	The permission mode of the agent.	`default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, or `manual` (same as `default`). `bypassPermissions` applies only when the main session has it. Claude Code ignores it for plugin agents.
`maxTurns`	Documented: An official docs page names this item.	The most agentic turns before the agent stops.	A positive integer. At the limit the output returns marked partial, and you can resume the agent. The program accepts a number or a string.
`autoCompactWindow`	Documented: An official docs page names this item.	Lowers the auto-compact window for this agent.	An integer from `100000` to `1000000`. Needs 2.1.296. Since `2.1.312`, it also lowers the window that `CLAUDE_CODE_AUTO_COMPACT_WINDOW` sets. It never raises a window. See Context and Compaction.
`skills`	Documented: An official docs page names this item.	Skills preloaded into the agent context.	Claude Code injects the full skill text, for at most 32 names. A skill with `disable-model-invocation: true` cannot be preloaded. Claude Code skips a missing skill and logs it.
`mcpServers`	Documented: An official docs page names this item.	MCP servers for this agent.	A list of server names, or inline `{name: config}` objects. Inline servers connect at start and disconnect at the end. Claude Code ignores it for plugin agents.
`hooks`	Documented: An official docs page names this item.	Hooks scoped to this agent.	Events: `PreToolUse`, `PostToolUse`, `Stop` (becomes `SubagentStop`). Claude Code ignores it for plugin agents. See Hooks.
`memory`	Documented: An official docs page names this item.	The scope of persistent memory.	`user` is `~/.claude/agent-memory/<name>/`. `project` is `.claude/agent-memory/<name>/`. `local` is `.claude/agent-memory-local/<name>/`. Claude Code logs an invalid value and drops it.
`background`	Documented: An official docs page names this item.	Keeps the agent in the background.	`true` or `false`, as a string or boolean. Other values log an error. A teammate may not start such an agent.
`omitClaudeMd`	Documented: An official docs page names this item.	Starts without user, project, and local `CLAUDE.md`.	`true` only. Managed policy files still load. `Explore`, `Plan`, and the web-reading agent set it.
`effort`	Documented: An official docs page names this item.	The effort level while the agent runs.	`low`, `medium`, `high`, `xhigh`, `max`. The program text also lists an integer. `CLAUDE_CODE_EFFORT_LEVEL` wins.
`isolation`	Documented: An official docs page names this item.	Runs the agent in a temporary git worktree.	The docs name `worktree`. The program schema also accepts `remote`. The worktree branches from the default branch. In a probe in `-p`, `isolation: remote` in a file ran the agent in a local worktree and started no cloud session. It was not tried with a cloud login.
`color`	Documented: An official docs page names this item.	The display color.	`red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`.
`initialPrompt`	Documented: An official docs page names this item.	The first user turn when the agent is the main session.	Used with `--agent` or the `agent` setting. Claude Code processes commands and skills. Not read when the agent starts as a subagent.
`experimental`	Documented: An official docs page names this item. Experimental: The program or the official docs call this experimental or beta.	A map of experimental options.	`cacheTtl`: `5m` or `1h` sets the prompt cache TTL when neither a `subagentPromptCacheTtl` setting nor an env var sets a value. Claude Code ignores `1h` in subscription overage. Claude Code ignores unknown keys.
`observer`	Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. CLAUDE_CODE_EXPERIMENTAL_OBSERVER_AGENTS	An agent type that starts as a background observer whenever this agent runs.	A trimmed string. Needs `CLAUDE_CODE_EXPERIMENTAL_OBSERVER_AGENTS`. Without it, Claude Code ignores the field. With it, the named agent starts in the background. It gets an activity digest after each turn of this agent. It has an `ObserverReport` tool. An observer cannot have its own observer. Source: the program and Probes.
`observerMessage`	Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Same gate as observer.	Text added to each activity digest sent to the observer.	A string. It follows the default digest instruction as the last line (checked by a probe).
`observeSubagents`	Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. Same gate as observer.	Whether subagents inherit the observer.	A boolean, default true. `false` stops inheritance.

Rules for Files

Claude Code skips a file in any of these cases. It has no name. Its opening --- is not on line 1. It has a bad name or no description. Its YAML does not parse. Details go to the --debug log.
A plugin agent whose frontmatter has no name or does not parse still loads, under its file name.
A plugin agent has the name plugin:folder:file. The file agents/review/security.md in my-plugin is my-plugin:review:security.
A plugin agent cannot use permissionMode, hooks, or mcpServers.
Frontmatter keys are case-sensitive and use camelCase. In a probe, Claude Code ignored Tools and disallowed-tools, while tools and disallowedTools worked. See Probes.

The `--agents` JSON

--agents takes a JSON object. Each key is an agent name. The value uses these fields:

description (required), prompt (required), tools, disallowedTools, model, effort (level or integer), permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, background, omitClaudeMd, isolation, observer, observerMessage, observeSubagents.

The prompt field replaces the file body. These agents have priority 2, below managed settings. In print mode (-p), --agents also takes a file path (since 2.1.281). An interactive session refuses a path. The plugin mod call $.agent.register uses the same schema.

Exact Fields

The exact fields are in two files. For the --agents JSON, see https://clawdipedia.cc/schemas/claude-code-agents-json.json, made from the program's own validator. For the frontmatter, see the agent definition in https://clawdipedia.cc/schemas/claude-code-frontmatter.json, made from the program's frontmatter validators. It lists every field of this release. Build on the fields it names. Look up each one there before you rely on it.

Subagents: where agent files live.
Subagent Runtime: built-in agents and limits.
Skill Frontmatter: the keys of a skill.
Hooks: the hooks key.

Source: Create Custom Subagents and the program (the frontmatter schema, the frontmatter parser, and the --agents JSON schema).

Example​

Keys​

Rules for Files​

The --agents JSON​

Exact Fields​

Related Pages​

Example

Keys

Rules for Files

The `--agents` JSON

Exact Fields

Related Pages