CONCEPT Four frontmatter fields do the heavy lifting
A subagent's YAML frontmatter defines its metadata and configuration. There are more optional fields, but four cover almost every case — and only the first two are required.
| Field | Required | What it does |
|---|---|---|
name | Yes | Unique identifier, lowercase letters and hyphens. This is how the subagent is invoked; the filename doesn't have to match. |
description | Yes | States when Claude should delegate to this subagent. Claude reads it to decide whether to hand off the task. |
tools | No | Allowlist of tools the subagent may use. Omit it and the subagent inherits all tools from the main conversation. |
model | No | Which model to run on: sonnet, opus, haiku, fable, a full model ID, or inherit. Defaults to inherit. |
name + description + a system-prompt
body. Everything else refines capability (tools) and cost/quality (model).CONCEPT tools: restrict or inherit; model: pick a tier or inherit
Tools. Leaving tools out means the subagent inherits every internal and MCP
tool the main conversation has. Listing tools turns it into an allowlist — a read-only reviewer, for
instance, lists Read, Grep, Glob and therefore cannot edit or write files. (A companion
disallowedTools field works as a denylist instead, removing tools from the inherited set.)
Model. The model field controls which model the subagent uses. Use an alias
(sonnet / opus / haiku / fable), a full model ID, or
inherit to match the main conversation. If you omit it, the default is
inherit. Routing a verbose, mechanical task to a cheaper/faster model like Haiku is a common way
to control cost.
tools: Read, Grep, Glob guarantees the agent can
analyse but never modifies files — capability enforced by config, not by hoping the prompt behaves.DIAGRAM How each field is resolved
CODE A fully-specified subagent
A read-only code-improver on Sonnet: it can scan but not modify, and it runs on a fixed model regardless of the session's model.
# file: ~/.claude/agents/code-improver.md --- name: code-improver description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code. tools: Read, Grep, Glob # allowlist → cannot Write or Edit model: sonnet # fixed model instead of inherit --- You are a code improvement specialist. For each issue you find, explain the problem, show the current code, and provide an improved version.
TRADE-OFFS Restrict tools/model vs. inherit everything
✅ Explicit restriction
- Enforces capability limits (e.g. read-only) at the config layer
- Predictable model → predictable cost & behaviour
- Smaller tool surface = tighter, more focused agent
⚠️ Inherit everything (omit fields)
- Least configuration; agent is maximally capable
- But no tool guardrail — it can do anything the main session can
- Model tracks the session, so cost varies with your current model
EXAM TRAPS
name and
description are required. tools and model are optional.tools means the subagent has no tools." → The opposite:
omit tools and it inherits all tools. To limit it, you must list an allowlist (or use
disallowedTools).model defaults to Sonnet / a fixed model." → The default
is inherit — it uses the same model as the main conversation.name." → It doesn't. Identity comes
from the name field; the filename is free-form.PRACTICE
Q1 · Which frontmatter fields are required, and which are optional?
Required: name and description. Optional (among others):
tools and model.
Q2 · You want a subagent that can read but never write files. How?
Set an allowlist that excludes Write/Edit, e.g. tools: Read, Grep, Glob (or use
disallowedTools: Write, Edit). Since tools is an allowlist, only the listed tools
are available.
Q3 · A subagent has no model field. What model does it run on?
It defaults to inherit — the same model as the main conversation. To pin it, set
model: to sonnet, opus, haiku, fable, or a
full model ID.