Lesson 4.218 min · 5 cards · 8 exercises · 1 mission

Define a subagent

One file in .claude/agents/: the description, the system prompt, which tools it may use, its model, and how to call it reliably.

In lesson 4.1, every time you split work off you had to repeat yourself: "use a subagent, only write tests in test/, don't touch src/, run npm test, report which tests fail". By the third time, it is a sign you need a subagent of your own: one file that fixes what it does, which tools it may use and which model it runs on. This lesson creates test-writer for todo-api.

When you need a subagent of your own

The docs put it simply: define a subagent when you keep spawning the same kind of helper with the same instructions. What you gain over the built-in ones:

  • Fixed instructions: written once, followed on every delegation.
  • Limited tools: a reviewer that can only read can't edit a file by accident.
  • A chosen model: simple work runs on a faster, cheaper model.
  • Sharing: commit it to the repo and the whole team has the same helper.

The quickest way to get your first file is to ask Claude to write it: "Create a test-writer subagent in .claude/agents/ that…". In the current version, /agents just reminds you to do that, or to edit the agents folder directly. Whoever writes the file, open it and read it, because it decides what the subagent is allowed to do.

One file, two parts

A subagent is a Markdown file, much like a skill from level 3: YAML frontmatter at the top, content below.

Markdown
---
name: code-reviewer
description: Reviews code for quality and best practices. Use after code changes.
tools: Read, Grep, Glob
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and give
specific, actionable feedback on quality, security and tests.
  • name and description are the two required fields. description tells Claude when to delegate to this subagent, so write it like a skill's description: what it does, and when to use it.
  • The body is the subagent's system prompt (the base instructions that shape how it works). The key point: the subagent gets this prompt plus a few environment details such as the working directory, and not the Claude Code system prompt. Anything you want it to do has to be written down.

Mistakes that stop a subagent working the way you expect:

  • A missing description, or --- not on the first line: Claude Code skips the whole file.
  • A misspelled field: multi-word names use camelCase, such as disallowedTools and maxTurns. Write disallowed-tools and the field is ignored without any error. Run claude --debug and search the log for "does not recognize or apply" to find ignored fields.

No restart is needed: Claude Code watches the agents folders, and a few seconds after you save a file, the next delegation uses the new version.

Where it lives

The file's location decides who can use the subagent:

Location Available in Priority
Organization managed settings The whole organization 1 (highest)
--agents flag at launch (JSON) That session only 2
.claude/agents/ in the repo This project 3
~/.claude/agents/ Every project on your machine 4
A plugin's agents/ folder Where the plugin is enabled 5

The two you will use most are .claude/agents/ for subagents tied to one codebase (commit them so the team can use and improve them) and ~/.claude/agents/ for personal helpers you want in every project. If two places define a subagent with the same name, the higher-priority one wins. The filename doesn't have to match name, but keeping them the same makes files easier to find.

Tools: what to allow, what to block

There are two ways to limit tools:

  • tools is an allowlist: only the tools listed can be used. tools: Read, Grep, Glob makes a read-only subagent. Leave it out and the subagent inherits every tool available to subagents.
  • disallowedTools is a denylist: inherit everything except the tools listed. disallowedTools: Write, Edit keeps Bash but blocks file edits.

One trap: disallowedTools: Bash(git push *) does not block just git push; it removes Bash from the subagent entirely. To keep Bash and block one command, add a Bash(git push *) deny rule to permissions.deny in your settings. That rule covers the main conversation and every subagent.

Also keep in mind that background subagents (the default) keep only a reduced tool set, including the everyday ones such as Read, Grep, Glob, Bash, Edit and Write. And tools can't limit folders. "Only edit test/" is an instruction in the system prompt, not a rule. To enforce it, use a hook (level 6).

The permissionMode field sets a subagent's own permission mode, but it only takes effect when the main conversation is in the default mode. If the main conversation is in auto mode or acceptEdits, the subagent follows the main conversation's mode.

Choosing a model

The model field takes sonnet, opus, haiku, fable, a full ID such as claude-sonnet-5-5, or inherit. Leave it out and the subagent runs on the same model as the conversation that calls it.

When several places set a model, Claude Code uses the first of these:

  1. the model Claude passes when it starts the subagent (when you ask, for example "use haiku for this");
  2. the model field in the file;
  3. the CLAUDE_CODE_SUBAGENT_MODEL environment variable;
  4. the main conversation's model.

Match the model to the difficulty of the work. Searching, listing and summarising logs are simple, and a fast, cheap model like haiku is enough. Writing tests or reviewing code needs better reasoning, so use sonnet or the default. The effort field sets the subagent's own effort level if you need it. To see which model a subagent actually runs on, open /tasks: the subagent's row names the model.

test-writer for todo-api

Create .claude/agents/test-writer.md:

Markdown
---
name: test-writer
description: Writes and runs tests for todo-api routes. Use proactively when a route is added or changed, or when a bug needs a regression test.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
color: green
---
You write tests for todo-api. The project uses node:test; tests live in test/todos.test.js.

1. Read the route in src/routes/ and the existing tests first; reuse their helpers
2. Add tests only under test/. Never edit files in src/, even if a test fails
3. Cover the happy path, the error statuses (400, 404) and the { error: "..." } body
4. Run npm test
5. Report: the tests you added, which pass, which fail and why. A failing test that exposes a real bug is a good result: say so, don't fix src/

When we tried it for real, we learned something worth remembering. Asked to "add a regression test for deleting the same todo twice" without naming the agent, Claude did it itself in the main conversation, even with "Use proactively" in the description. For a task that small, Claude judged doing it directly to be faster. "Use proactively" only encourages delegation; it doesn't guarantee it. To be sure, name the agent:

Use the test-writer agent to add a regression test for deleting the same todo twice

or type @ and pick test-writer (agent) from the suggestions. That time Claude delegated straight away. The subagent ran on Sonnet while the main conversation ran on Opus. It edited only test/todos.test.js and reported that the new test fails because the API returns 500 instead of 404. That is exactly the bug planted in todo-api, and it didn't go off and fix src/.

Now the "in parallel" part. Because the subagent runs in the background, you can have test-writer write tests for the error cases of PATCH /todos/:id while you and Claude work on something else in the main conversation that doesn't touch test/. The two tasks don't depend on each other, so neither waits.

A few more fields are coming in the next lesson: skills to preload skills, memory so the subagent remembers across sessions, and isolation: worktree so it works on its own copy of the repo. Lesson 4.3 uses them to build the three most common subagent patterns: reviewer, tester and debugger.

Practice lesson 4.2

5 flashcards, 8 exercises checked right on the page, 1 mission on your machine.

Start practice

Related reference

Type to search the reference, templates and lessons.