Short answer: a subagent is a Markdown file in ~/.claude/agents/ or .claude/agents/ with a name, a description and its own instructions. Claude hands it a job when the description matches the task, so write the description as when to use it, not what it is.
A subagent is a second Claude with its own context window and its own instructions. The main session hands it a job, it works on that job without filling your conversation, and it reports back with a result. A code reviewer, a test runner or a researcher that reads forty files and returns three paragraphs are the classic examples.
The part most people get wrong is not writing the agent. It is getting Claude to use it.
Where does a subagent live?
A subagent is one Markdown file: frontmatter on top, instructions below.
| Folder | Who gets it |
|---|---|
~/.claude/agents/ | You, in every project |
.claude/agents/ | Everyone working in this repository, once it is committed |
The file name does not have to match the agent's name, but keeping them the same saves confusion later.
What does a minimal agent look like?
---
name: reviewer
description: Reviews a diff for correctness and security problems. Use after writing or changing code, before committing.
tools: Read, Grep, Glob
model: inherit
permissionMode: plan
---
You review code changes. Read the diff, then the files it touches.
Report bugs first, then security problems, then anything unclear.
Quote the line for every finding. Do not suggest style changes.The body becomes the subagent's system prompt. Write it as instructions to a colleague who cannot see your screen: it does not see your conversation, only the task the main session gives it.
Why does the description matter so much?
When Claude considers delegating, the description is the only part of the file it reads. A vague description means the agent never runs.
Weak: Helps with code
Strong: Reviews a diff for correctness and security issues. Use after writing or changing code.A description that gets picked does four things: it starts with what the agent does, it says when to use it ("Use when..." or "Use after..."), it names something concrete such as file types or tools, and it avoids filler words like "helps", "various" or "things".
You can also call an agent by name in your prompt ("use the reviewer agent on this branch"), which always works.
Which fields are worth knowing?
| Field | What it does |
|---|---|
tools | The tools it may use. Empty inherits the usual set |
disallowedTools | Removed from whatever it would otherwise have |
model | inherit uses the session's model |
effort | How much thinking per turn. Worth raising for design work, not for search |
permissionMode | plan lets it read and reason but change nothing, ideal for reviewers |
maxTurns | A ceiling that stops an agent that misunderstood |
background | Starts it detached, so you keep working |
isolation | An isolated copy of the repository, cleaned up if nothing changed |
mcpServers | Servers started for this agent only |
skills | Skills loaded into its context at startup |
hooks | Hooks registered only while this agent runs |
How do I limit what a subagent can do?
Give it the smallest tools list that does the job and set permissionMode: plan if it should only report. A reviewer with Read, Grep, Glob cannot edit anything, whatever its instructions say.
Should the agent be mine or the project's?
Put it in the project when it encodes how this codebase works (its test command, its review checklist). Put it in your home folder when it is how you like to work, in every repository.
Where can you check this?
Can you build one without guessing the fields?
Config Studio for Claude Code has an Agents editor with every frontmatter key Claude Code accepts, each explained in plain words. Its Try it tab has Will this ever get picked?, which scores your description against the checks above before you save it. The lesson Create your own Claude Code agents, skills and commands walks through it step by step.
