# What are Claude Code subagents, and how do you make one?

> A Claude Code subagent takes one task off your hands, works on it in a context window of its own and sends back only a summary. Explore, which Claude uses for codebase searches, is a built-in one. Yours is a Markdown file with YAML frontmatter in `.claude/agents/` or `~/.claude/agents/`, and Claude delegates to it when a task fits its description.

Mindket editors · Published 2026-10-29 · Updated 2026-11-03 · https://mindket.com/blog/claude-code-subagents

## In short

- Give every agent file a `tools` line, so Claude Code enforces what it can touch.
- Put the effort into the description, and type `@` when one particular agent has to run.
- If `/agents` prints only a reminder, ask Claude to write the agent or write the file yourself.
- To try one, save the sample in `.claude/agents/` as `docs-link-checker.md` and ask for it by name.

## What a subagent knows when it starts, and what comes back

Ask Claude a broad question about your codebase and it [hands the search to Explore](https://code.claude.com/docs/en/best-practices) without being asked. Explore does the reading in its own context window. When it finishes, a summary lands in your chat, and the files it opened and the commands it ran stay behind.

A subagent can't see your conversation so far, the skills you've invoked or any file Claude has already read. It gets its own tool access and permissions, and a system prompt made of the agent's own prompt plus environment details Claude Code appends, not the Claude Code system prompt ([Anthropic's subagent guide](https://code.claude.com/docs/en/sub-agents)).

Your [CLAUDE.md files](https://mindket.com/blog/claude-md-file) do come along, with a snapshot of git status and the full text of any skill the agent preloads. A long CLAUDE.md therefore loads again, and takes up context again, in every custom subagent's window. Explore and Plan skip CLAUDE.md and the git snapshot.

1. Claude weighs your request against each description and the current context
2. A new context window opens with the agent's own prompt and tools
3. The subagent works in the background. You keep working meanwhile. If it needs a permission, the prompt appears in your main session and names the subagent asking.

Source: [Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents) (read 2026-11-03)

| Subagent | What Claude uses it for | Tools |
| --- | --- | --- |
| Explore | Searching and analyzing a codebase without making changes | Read-only: Write and Edit are denied |
| Plan | Gathering context in plan mode before Claude presents a plan | Read-only: Write and Edit are denied |
| General-purpose | Tasks that need both exploration and changes, or several dependent steps | Every tool available to subagents |

## Make one: a sample agent file

One file holds the whole definition. YAML at the top sets the name, the description and limits such as tools and model, and the Markdown below becomes the subagent's system prompt. Only `name` and `description` are required. [The field reference](https://code.claude.com/docs/en/sub-agents) lists the optional ones, from `maxTurns` and `skills` to `memory` and `isolation`.

Our sample, written for this post, checks links in a docs folder, the kind of simple job Anthropic suggests handing to Haiku. Its tools line lists only Read, Grep and Glob, so Claude Code itself stops the agent from editing a file. A "don't edit anything" line in the prompt would only be a request.

````markdown
---
name: docs-link-checker
description: Checks relative links and anchors in Markdown files under docs/ and reports broken ones. Use proactively after editing files in docs/.
tools: Read, Grep, Glob
model: haiku
---

You check links in the Markdown files you are given, or in docs/ if none are named.

1. Find every relative link and every #anchor.
2. Confirm each target file exists and each anchor matches a heading in it.
3. Skip links that start with http:// or https://.

Reply with one line per broken link: file, line, target and the reason.
If every link resolves, reply "All links resolve" and nothing else.

````

- `name` is what Claude and hooks see. It can't contain a colon, and it doesn't have to match the file name.
- `tools` is an allowlist. Leave it out and the subagent inherits every tool available to subagents.
- `model` accepts `sonnet`, `opus`, `haiku`, `fable`, a full model ID, or `inherit` for the main conversation's model.

1. Make a `.claude/agents/` folder in your project for an agent the team shares, or use `~/.claude/agents/` for one you want in every project.
2. Save the sample there as `docs-link-checker.md`.
3. Ask for it by name, as in "Use the docs-link-checker subagent on docs/".

## Where agent files live, and what to check when one misbehaves

If `/agents` prints a one-line reminder instead of opening a menu, nothing is broken. On current versions it tells you to ask Claude, or to edit `.claude/agents/` and `~/.claude/agents/` directly. The interactive wizard belongs to v2.1.197 and earlier.

Asking Claude is the route the guide's own quickstart takes: describe the agent and where to save it, for example a read-only code improver in `~/.claude/agents/` that uses Sonnet. Then open the file and check that its frontmatter matches what you asked for, the model included.

Claude Code reads agent files from [five places](https://code.claude.com/docs/en/sub-agents), and when two definitions share a name, the higher-priority location wins. Inside one `.claude/agents/` folder and its subfolders there's no ranking: if two files declare the same name, Claude Code loads only one, in whatever order the filesystem returns them. Keep names unique.

A misspelled field fails quietly. Field names are camelCase, and Claude Code ignores a field it doesn't recognize without reporting an error. If `maxTurns` or `permissionMode` seems to do nothing, check its spelling first.

An agent that came in a [plugin](https://mindket.com/blog/claude-code-plugins), the package that carries agents between teams along with skills, hooks and MCP servers, has one more trap. For security, a plugin's agents ignore the `hooks`, `mcpServers` and `permissionMode` fields, so a setting in one of those does nothing there.

[![Sid's post on X (@sidbid): Claude Code is getting a brand new feature, custom subagents, and typing /agents gets you started, posted 24 July 2025](https://mindket.com/blog/shots/x-sidbid-custom-subagents.webp?v=8143fcf83ff3)](https://x.com/sidbid/status/1948495478146167251)

Sid (@sidbid) on X, 24 July 2025

> A screenshot of X's own embed of the 2025 announcement, taken on 3 November 2026, in US Pacific time and without its video. Select it to open the post on X.

## How Claude picks a subagent, and how you pick one yourself

Of the things Claude weighs before it delegates, the `description` is the only one you write in advance. Ending it with "Use proactively" and a situation, as the sample does, makes Claude more likely to reach for the agent unasked.

Keep each description short anyway. Once all your subagents' descriptions together pass 15,000 tokens, Claude Code [warns at startup](https://code.claude.com/docs/en/sub-agents), though it still loads every one.

- Ask in plain words: "Use the test-runner subagent to fix failing tests". Claude typically delegates, but it's still Claude's call.
- Type `@` and pick the subagent from the typeahead, the way you'd pick a file. That one runs for certain, though Claude still gets your full message and writes its task prompt.
- Start the session with `claude --agent code-reviewer`, and the main thread becomes that agent, with its tool limits and model. Setting `agent` in `.claude/settings.json` makes it a project's default.

## Subagent or skill, and when a subagent is worth it

A skill [loads into your current conversation](https://code.claude.com/docs/en/features-overview) and adds to its context. It's reusable content, such as instructions or reference material.

A subagent's `skills` field preloads the full text of the [skills](https://mindket.com/blog/what-are-agent-skills) it names, and a skill set to `context: fork` [runs inside a subagent](https://code.claude.com/docs/en/skills).

A subagent pays off on [independent jobs](https://code.claude.com/docs/en/best-practices) that can run at the same time, and on long output that should stay out of your chat, such as a full test run. Review is another use, since an agent that didn't write the code brings none of your conversation's assumptions to it.

Each subagent sends its own requests, and they count toward the same usage limits as your main conversation, so tokens are the main cost. A fresh one must first gather context your conversation already had, which can make it slower than working in place. Nor is the answer smarter: by default it's the same model, or a smaller one, on the same task.

Once you keep spawning the same kind of worker with the same instructions, such as a link check after every docs edit, save it as an agent file like the sample.

**Main conversation or subagent: which one the task fits**

| | Main conversation | Subagent |
| --- | --- | --- |
| Needs frequent back-and-forth or iterative refinement | ✓ Yes | ✗ No |
| Phases share a lot of context, such as planning, building and testing | ✓ Yes | ✗ No |
| A quick, targeted change | ✓ Yes | ✗ No |
| Latency matters | ✓ Yes | ✗ No |
| Produces verbose output you don't need in your chat | ✗ No | ✓ Yes |
| Needs tool limits or permissions of its own | ✗ No | ✓ Yes |
| Self-contained work that can come back as a summary | ✗ No | ✓ Yes |

Source: [Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents) (read 2026-11-03)

## Reference: where agent files load from, and the default limits

**Three limits Claude Code sets on subagents**

- **15,000** tokens of combined subagent descriptions before Claude Code warns at startup (Source: [Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents), read 2026-11-03)
- **3** layers of subagents allowed below your main conversation, by default (Source: [Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents), read 2026-11-03)
- **20** subagents running at once before a new one fails to start, by default (Source: [Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents), read 2026-11-03)

| Location | Scope | Priority |
| --- | --- | --- |
| Managed settings | Your organization | 1, highest |
| The `--agents` flag, as JSON | The current session only, never saved to disk | 2 |
| `.claude/agents/` | The current project | 3 |
| `~/.claude/agents/` | All your projects | 4 |
| A plugin's `agents/` folder | Wherever the plugin is enabled | 5, lowest |

> Every fact here comes from the Anthropic pages listed under Sources, read on November 2 and 3, 2026. It's a reading of the documentation, not hands-on testing, and Claude Code changes fields, defaults and commands between releases.

## Frequently asked questions

### Can a subagent start its own subagents?

Yes, down to three layers below your main conversation by default. At that depth Claude Code withholds the Agent tool from every subagent except a fork, so the deepest one does its job itself and returns one summary. Setting `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` changes the number of layers. Width has its own cap: while 20 subagents are running, a session fails to start a 21st.

### Do I have to restart Claude Code after adding a subagent?

Usually not. Claude Code watches `.claude/agents/` and `~/.claude/agents/`, and the next delegation picks up a new or edited file within a few seconds. You do need a restart if the agents folder didn't exist when the session started, if the agent sits under a directory added with `--add-dir`, or if the session began with `--disable-slash-commands`.

### What is the difference between a subagent and a fork?

A fork inherits the whole conversation so far, while a regular subagent starts fresh from its definition. A fork shares the main session's system prompt, tools and model and reuses its prompt cache. For work that needs the same context, that makes a fork cheaper than a fresh subagent. Type `/subtask` and the task to start one yourself. A fork can't start more forks.

### How do I stop Claude from using a subagent?

Put it on the `deny` list in your permission settings as `Agent(name)`, for example `Agent(Explore)`. That works for built-in and custom subagents alike. Old `Task(...)` entries keep working too: Claude Code v2.1.63 renamed the Task tool to Agent and kept the old name as an alias.

### Can a subagent remember things between sessions?

Yes, once you turn on persistent memory with one frontmatter line. Set `memory: user` and its notes go under `~/.claude/agent-memory/` for every project. With `project` they go in `.claude/agent-memory/`, where you can commit them, and `local` uses `.claude/agent-memory-local/`, outside version control. None of this touches your own [auto memory](https://code.claude.com/docs/en/memory), which a regular subagent doesn't load.

### Which model does a subagent use if I leave model out?

Your main conversation's model, unless you've set the `CLAUDE_CODE_SUBAGENT_MODEL` environment variable. A model alias Claude passes for a single call beats both. To put one model on every subagent, also set `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`, which needs Claude Code v2.1.257 or later.

### Where can I get subagents someone else wrote?

In a plugin, which brings its agents along with skills, hooks and MCP servers, or in a Mindket [kit](https://mindket.com/kits), a zip of plain text files where nothing runs by itself. Read the frontmatter of any agent file you didn't write before you use it. Mindket's [agents page](https://mindket.com/agents) lists a different kind: instructions for a browser agent, each shown in full so you can read what it does before you hand it over.

## Sources

- [Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents) (read 2026-11-03)
- [Claude Code docs: Best practices](https://code.claude.com/docs/en/best-practices) (read 2026-11-02)
- [Claude Code docs: Extend Claude Code](https://code.claude.com/docs/en/features-overview) (read 2026-11-02)
- [Claude Code docs: Extend Claude with skills](https://code.claude.com/docs/en/skills) (read 2026-11-02)
- [Claude Code docs: How Claude remembers your project](https://code.claude.com/docs/en/memory) (read 2026-11-02)

[Read the CLAUDE.md guide](https://mindket.com/blog/claude-md-file)