D3 · Claude Code › Cluster 7 · Subagents

7.2 · Subagent Configuration

name · description · tools · model

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.

FieldRequiredWhat it does
nameYesUnique identifier, lowercase letters and hyphens. This is how the subagent is invoked; the filename doesn't have to match.
descriptionYesStates when Claude should delegate to this subagent. Claude reads it to decide whether to hand off the task.
toolsNoAllowlist of tools the subagent may use. Omit it and the subagent inherits all tools from the main conversation.
modelNoWhich model to run on: sonnet, opus, haiku, fable, a full model ID, or inherit. Defaults to inherit.
🔑 Minimum viable subagent = 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.

Read-only reviewer pattern: 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

flowchart TD START["Subagent frontmatter"] --> N["name → identifier used to invoke"] START --> D["description → Claude uses it to decide when to delegate"] START --> T{"tools listed?"} T -->|"yes"| TR["🟠 Restrict to that allowlist"] T -->|"omitted"| TI["🟢 Inherit ALL tools"] START --> M{"model set?"} M -->|"alias / full ID"| MS["Run on that model"] M -->|"omitted / inherit"| MI["🟢 Use main conversation's model"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class TI ok; class MI ok; class TR gate;

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

Trap: "All four fields are required." → Only name and description are required. tools and model are optional.
Trap: "Omitting 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).
Trap: "Omitting model defaults to Sonnet / a fixed model." → The default is inherit — it uses the same model as the main conversation.
Trap: "The filename must equal the 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.