A subagent in Claude Code runs in its own context window with its own tool list and, if you choose, its own model. That keeps verbose output out of your main conversation and lets you restrict what a task can touch. This post builds a read-only code reviewer, then covers model resolution, where agent files live and when not to delegate. Everything here comes from the official sub-agents documentation.

The file format
A subagent is a Markdown file with YAML frontmatter. The body after the closing --- becomes the subagent's system prompt. Only name and description are required. The fields you will use most:
description: when Claude should delegate to this subagent.tools: the tools it may use, as a comma-separated string or a YAML list. If omitted, it inherits all tools available to subagents.disallowedTools: tools to remove from the inherited or specified list.model:sonnet,opus,haiku,fable, a full model ID, orinherit.maxTurns: the maximum number of agentic turns before it stops.
Field names are camelCase and must match exactly: the docs say Claude Code silently ignores unrecognised fields, so a typo gives you no error.
A read-only reviewer
Save this as .claude/agents/code-reviewer.md. The tool allowlist is what makes it read-only: it can read, glob and grep, and it has no edit or shell tool.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
maxTurns: 20
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
Report findings as a list with file and line, and do not edit anything.The first five lines of the body come from the documentation's example. The maxTurns line and the last sentence are my additions, using fields from the same table.
Where the file can live
When subagents share a name, the higher-priority location wins:
- Managed settings (organisation-wide)
- The
--agentsCLI flag (current session) .claude/agents/(current project)~/.claude/agents/(all your projects)- A plugin's
agents/directory
Put a reviewer in .claude/agents/ and commit it, and the whole team gets the same one.



