Write your first Claude Code subagent

A subagent is a helper that works in its own context window and sends back a summary. It is a plain Markdown file, so you can write one in five minutes.

When a subagent is the right tool

Use one when a side job would fill your conversation with output you will not look at again: running a test suite, searching many files, reviewing a diff. Only the summary comes back. If you are not sure whether you want a subagent, a skill or a hook, read which one do you need first.

Where the file goes

• .claude/agents/ in a project: that project only, and you can commit it so your team gets it too.
• ~/.claude/agents/: all your projects, only on your machine.

If two subagents share a name, the one in the higher-priority place wins, and the project folder beats the personal one. Claude Code looks inside subfolders too. The name comes from the name field in the file, not from the file name or path.

An example you can paste

Save this as .claude/agents/test-runner.md:

---
name: test-runner
description: Runs the project's tests and reports only the failures. Use proactively after code changes.
tools: Read, Glob, Grep, Bash
model: haiku
---

You run the project's test suite and report back.

1. Find the test command in the project files. If there are several, pick the main one and say which.
2. Run it once.
3. Report: how many passed, how many failed, and for each failure the test name, the error line and the file.
4. Do not edit any file. Do not try to fix anything.
5. If the tests cannot run, say why in one line.

The part between the dashes is the configuration. Everything after it is the subagent's instructions. Only name and description are required.

The fields that matter most

• descriptionWhat Claude reads to decide when to hand work to this subagent. Say clearly when to use it. A phrase like "use proactively" encourages Claude to delegate on its own.
• toolsAn allowlist. If you leave it out, the subagent can use every tool available to subagents. A read-only reviewer should list only the reading tools.
• disallowedToolsA denylist, applied before the allowlist.
• modelsonnet, opus, haiku, a full model ID, or inherit. A small model is often enough for a mechanical job.
• maxTurnsStops the subagent after that many turns, which is a cheap guard against a helper that wanders.
• skillsSkills whose full text is loaded into the subagent when it starts.
• permissionModeHow it handles permission prompts. Leave it alone until you know why you need it.

There are more fields, including memory, background and isolation. Claude Code ignores a field it does not recognise without saying so, so a typo does nothing. Check the spelling, with the capital letters.

How to call it

• Let Claude pick it. Claude compares your request with each description.
• Ask by name. "Use the test-runner subagent on the auth changes."
• Use @. Type @ and choose the subagent from the list.
• Run the whole session as it. claude --agent test-runner.

What it knows and what it does not

A subagent starts with a fresh context. It does not see your conversation or the files Claude already read. It gets its own instructions, the task Claude writes for it, your CLAUDE.md files, and any skills you listed. So put into the task everything it needs, and keep the instructions in the file short and specific.

Three subagents come built in: Explore and Plan, which are read-only, and a general-purpose one that can use every tool.

Limits

• Descriptions are loaded into Claude's context so it can choose. Anthropic warns at startup when the custom ones add up to about 15,000 tokens, so keep each one brief and put the detail in the body of the file.
• A subagent that only has Read, Glob and Grep cannot change files. That is a real limit, unlike a line that says "do not edit".
• Do not rely on a subagent for anything where a wrong answer is costly. Read what it reports.

Check it works

1. Save the file in .claude/agents/ of a scratch project. Most edits are picked up without a restart.
2. Ask for it by name, on a project that has a few tests.
3. Check the summary against what you see when you run the tests yourself.

This follows Anthropic's subagents documentation as we read it in October 2026. That page is the authority, and we are not affiliated with Anthropic. We wrote this from the documentation and have not tested the example on every system.

If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.