What a subagent actually is
A subagent is a Markdown file in .claude/agents/ with a YAML frontmatter header and a body. The header carries the metadata - a name, a description that tells Claude when to reach for it, and optionally a model and a list of tools it is allowed to use. The body, everything below the frontmatter, is the subagent’s system prompt. That is the whole format. No plugin, no runtime, no registration step - just a file the agent reads.
A minimal one looks like this:
name: code-reviewer- the handle you and Claude use to refer to it.description: Reviews a diff for correctness and security issues.- a clear, specific trigger so the agent knows the job this assistant is for.- A body that reads like instructions to a colleague: what to look at, what to ignore, what shape of answer to return.
Because it lives in the repo, a subagent is versioned, reviewed, and shared like any other file. That is the point - it is project knowledge, not a setting buried in a UI.
Give each one a single, clear job
The most common mistake is building a subagent that tries to do everything. A good subagent has one goal, a defined input, and a predictable output. “Review this diff for security” is a job. “Be my helpful coding partner” is not - that is just your main session with extra steps.
Write the body as if you were briefing someone who knows the language but not your codebase. State the goal in the first line. Spell out what the subagent should not do, because a narrow scope is what makes the output trustworthy. The same discipline that makes a good CLAUDE.md - lean, specific, no wishful thinking - makes a good subagent prompt.
Whitelist tools on purpose
The tools field is where most setups quietly go wrong. If you omit the field, the subagent inherits every tool the main session has - including any connected MCP servers. That is rarely what you want. A reviewer that only needs to read files should not be able to run shell commands or edit anything.
So list the tools explicitly. Give a code reviewer read and search access and nothing else. Give a test-writer the ability to edit files and run the test command. This is the same least-privilege thinking that drives good settings.json permissions - the narrower the surface, the less there is to go wrong, and the more confidently you can let the subagent run on its own. Tools you grant here interact with your project’s permission allowlist, so the two layers should agree.
Invoke them explicitly
Claude can pick a subagent automatically when a request matches its description, but in practice you get better results by asking for it by name or by intent: “use a subagent to review this for security” or “hand the test writing to the test-writer subagent.” Explicit invocation keeps you in control of when a fresh context spins up and what it works on.
The reason to bother is context hygiene. A subagent runs in its own window, so a long review or a noisy test run does not flood your main session’s history. The main agent gets back a clean summary instead of the entire transcript - which is a real, practical part of keeping a session’s context under control rather than a separate feature.
Where subagents fit best
Subagents earn their keep on tasks you do over and over: reviewing a diff, writing tests for a new module, drafting or updating docs, auditing a change before it ships. Anything you would otherwise re-explain every session is a candidate to capture once as a scoped assistant.
They are not the right tool for everything, though. If something must happen deterministically every single time - reformatting after an edit, blocking a destructive command - that belongs in a hook, which runs real code and cannot drift. Subagents are for judgment-heavy work you want delegated; hooks are for guarantees. Knowing which is which is part of the broader set of Claude Code best practices.
How this fits a clean setup
Subagents are one slice of a project that was configured on purpose rather than assembled ad hoc. When claudesetup scaffolds a Claude Code project in one command, it lays down the structure these files live in alongside the conventions, hooks, and context handoff that make them work together - so a subagent you add later drops into a repo that already knows how to treat it.