How to create a custom subagent in Claude Code

A subagent is a specialist that Claude Code can hand a job to: its own instructions, its own set of allowed tools, and its own separate conversation. You define one with a single markdown file. We built a small one and ran it in Claude Code 2.1.278 in September 2026, including a test of whether its tool limit really holds.

The short version: save a file such as .claude/agents/word-counter.md with a name, a description and a tools list. The tools line is the important one: a subagent can only use what you list, even when the main session allows more.

The file

This is the subagent we tested, saved as .claude/agents/word-counter.md:

---
name: word-counter
description: Counts the words in a file. Use when the user asks for a word count of a file.
tools: Read
model: haiku
---

You are a careful word counter. Begin every reply with the exact text COUNTER-AGENT-7: and then give the number of words in the file you were asked about, and nothing else.

The part above the second --- is configuration. Only name and description are required. Everything below it is the subagent's instructions. The marker text (COUNTER-AGENT-7:) is there only so we could tell from the outcome that the subagent followed its own instructions.

Where to save it: .claude/agents/ for one project (commit it to share it) or ~/.claude/agents/ for all your projects.
Names use lowercase letters and hyphens. The file name doesn't have to match.
Reloading: Claude Code watches the agents folders and picks up a new or edited file within seconds. The documentation lists exceptions that need a restart: the first agent file you create in a brand-new agents folder, and folders added with --add-dir.

Running it (tested)

We asked: "Use the word-counter subagent to count the words in a.txt, then tell me exactly what it replied." What happened, step by step:

Claude called its Agent tool with subagent_type set to word-counter.
The subagent made one call of its own: Read on the file.
It replied COUNTER-AGENT-7: 9. The file held "the quick brown fox jumps over the lazy dog", which is nine words, and the marker shows the custom instructions were in effect.
Claude relayed the answer. In this non-interactive run the subagent ran in the background: Claude first received "Async agent launched" and picked up the result afterwards.

You can ask for a subagent by name, as we did, or let Claude decide. The description is what Claude reads when it decides, so say plainly when the subagent should be used.

The tools limit really holds (tested)

This is the reason to use subagents for anything sensitive. We started Claude with both Read and Bash allowed, then told it to have the word-counter also run echo hello-from-subagent. The subagent counted the words with Read, then reported that it could not run the shell command. Its only tool call was the read. The main session had Bash, but the subagent didn't, because its file says tools: Read.

So a reviewer subagent with tools: Read, Grep, Glob can look at your code but can't edit it or run anything, however the request is worded. Two details from the documentation:

If you leave tools out, the subagent inherits every tool it is allowed to have. Always write the list for anything you want limited.
disallowedTools removes specific tools from an inherited or listed set. An entry with a specifier, like Bash(git push *), still removes the whole Bash tool. For pattern-level control, use permission rules or a hook, as in the git push guide.

Other fields worth knowing

Field	What it does
`model`	`sonnet`, `opus`, `haiku`, a full model ID, or `inherit`. Use a cheaper model for simple jobs.
`permissionMode`	How the subagent handles permission prompts, such as `dontAsk` or `acceptEdits`.
`maxTurns`	Stops the subagent after this many steps and returns partial output.
`skills`, `mcpServers`	Skills to preload and MCP servers only this subagent may use.
`hooks`	Hooks that run only while this subagent is running.
`isolation: worktree`	Runs the subagent in a temporary copy of the repository so it cannot touch your working files.
`memory`	Lets the subagent keep notes between sessions.

What it costs

A subagent is a second, separate model session. In our tiny tests the delegated runs cost about $0.055 to $0.059 each, roughly double a plain small request. Subagents pay off when the job is big or noisy, such as reading many files, because only the final report comes back to your main conversation. For a one-line question, asking directly is cheaper.

What a subagent doesn't get

According to the documentation, a subagent receives only its own instructions plus basic environment details, not Claude Code's main system prompt, and its cd commands don't carry over between calls or change your main session's folder. Put everything it needs to know in its file or in the request you hand it.

Custom slash commands Running Claude Code from scripts