# How to Use Subagents in Claude Code

> A subagent is a separate Claude with its own context window. Write one as a Markdown file in .claude/agents/ — note /agents is no longer a wizard.

- Canonical: https://guides-ai.pages.dev/guides/claude-code-subagents/
- Plate 03.04 · Topic: Claude Code commands (https://guides-ai.pages.dev/topics/commands/)
- Published: 10 Jun 2026 · Updated: 06 Sept 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.pages.dev/

A subagent is a separate Claude with its own context window and its own instructions. The point
is isolation: a search that reads forty files fills the subagent's window, and only the summary
comes back to yours. It also lets you send cheap work to a cheaper model.

## 1. Delegate the wide work

```text
Use subagents to find every place we call the old fetchUser API.
```

What it does: hands the sprawling search to a separate context, so your main conversation gets
the answer without the forty files it took to find it.

## 2. Write your own

Create `.claude/agents/<name>.md` for the project, or `~/.claude/agents/` for every project.
**Note:** as of v2.1.198, `/agents` no longer opens an interactive wizard — write the file, or
ask Claude to write it for you.

```markdown
---
name: test-writer
description: Writes focused unit tests for a given file
tools: Read, Write, Bash
model: sonnet
---

You write minimal, behavior-focused unit tests. Match the project's existing test style.
Run the tests and confirm they pass before finishing.
```

What it does: defines a subagent. `name` and `description` are required — the description is
what Claude reads when deciding to delegate, so write it as a trigger, not a title. `tools`
narrows the inherited set; `model` takes `sonnet`, `opus`, `haiku`, `fable`, or a full ID.

Claude Code watches these directories and picks up changes within seconds, so no restart in
most cases.

## 3. Invoke it

```text
@"test-writer (agent)" write tests for src/lib/parse.ts
```

What it does: guarantees that subagent runs, rather than hoping Claude picks it. Naming it in
plain prose ("use the test-writer subagent") also works. To run a whole session as one:
`claude --agent test-writer`.

## Verify it worked

Run `/context` after a delegated search. If your main window barely grew, the isolation worked;
if it ballooned, the work happened inline and you got none of the benefit — which is the whole
reason to use a [subagent](/glossary/#subagent) rather than just asking.

Use them for broad searches, parallel independent tasks and focused reviews. Avoid them for
tightly coupled steps that need shared state: a subagent starts blank, so everything it needs
has to be in the task you hand it. Because each one runs its own context, they are also a
[real cost lever](/guides/claude-code-track-costs/) in both directions — see
[managing context](/guides/claude-code-manage-context/) for the rest of that picture.

Source: [Claude Code subagents](https://code.claude.com/docs/en/sub-agents).