# Claude Code Subagent

> A helper agent you define in a Markdown file. Claude hands it tasks to do.

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** Custom subagent, .claude/agents, /agents

## Think of it like

It is like a helper with one job card. You call them in, they do that job, and they report back.

## Definition

A Claude Code subagent is a helper you define in a Markdown file. The file sits in .claude/agents for one project, or in ~/.claude/agents for all of them. A short header gives it a name, says when to use it, and lists its tools and model. The text below the header is its own system prompt. Claude hands it a task, and it works in a fresh context and sends back a summary.

## Example

Emma makes a code-improver subagent. She gives it only Read, Grep and Glob. Claude now sends it code to review, and it can look but never edit.

## Example code

```markdown
---
name: code-improver
description: Suggests code fixes. Use after writing code.
tools: Read, Grep, Glob
model: sonnet
---

You review code and suggest clear fixes.
```

A name, when to use it, its tools and model, then its own instructions.

## Why it matters

Each subagent works in its own clean context. Big searches stay out of your main chat, and each helper gets only the tools it needs.

## Common mistake

Writing a vague description. Claude reads it to decide when to call the subagent, so a fuzzy one is never used.

## Three principles

- **One file each.** Markdown with a header on top.
- **Fresh context.** It works apart and reports back.
- **Only its tools.** List just what the job needs.

## Related terms

- [Subagent](https://learn.benibix.com/term/ai/subagent)
- [Built-in Subagents](https://learn.benibix.com/term/ai/built-in-subagents)
- [--agents Flag](https://learn.benibix.com/term/ai/agents-flag)
- [Agent Tool](https://learn.benibix.com/term/ai/agent-tool)
- [Claude Code Skill](https://learn.benibix.com/term/ai/claude-code-skill)
- [SubagentStart Hook](https://learn.benibix.com/term/ai/subagentstart-hook)

## Told apart from

- [Claude Code Subagent vs Skill](https://learn.benibix.com/compare/claude-code-subagent-vs-claude-code-skill): People think a skill and a subagent are two names for one helper. They are not. A skill is a set of steps that Claude reads into the chat you are in. A subagent is a second worker with its own fresh context and its own tools, and it sends back only a summary. Use a skill to teach Claude a job. Use a subagent to keep a big search out of your chat.

## Taught in

- [Claude Code Subagents](https://learn.benibix.com/learn/ai-claude-code/claude-code-subagents): Claude Code, 15/16

![Three files side by side, each with a header between two lines of dashes. A subagent file in .claude/agents with name, description, tools and model. A SKILL.md with description and allowed-tools. A plugin.json in .claude-plugin with name, version and description.](https://learn.benibix.com/diagrams/ai8-cc-extension-files.svg)

---

Source: https://learn.benibix.com/term/ai/claude-code-subagent
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-19
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
