# What is a subagent?

A subagent is a specialised assistant that a main AI agent hands part of a task to. In Claude Code, each subagent runs in its own context window with its own instructions, tool access and permissions, so long side work stays out of the main conversation.

## Why use one

- **Keep the main context clean**: a subagent can read a hundred files and report back a summary.
- **Limit what it can do**: give a reviewer subagent read-only tools.
- **Reuse a setup** across projects.
- **Control cost**: Claude Code's docs mention routing work to a cheaper model.

## Where they live in Claude Code

Custom subagents are Markdown files with YAML frontmatter in `.claude/agents/` (one project) or `~/.claude/agents/` (all your projects). When both define the same name, the project one wins. See also [AI agent](https://ai-powered.com/academy/glossary/ai-agent) and [context engineering](https://ai-powered.com/academy/code-with-ai-agents/context-engineering).

## Sources

Official documentation, checked on 19 November 2026:

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

## Related terms

- [AI agent](https://ai-powered.com/academy/glossary/ai-agent): An AI agent is a system in which a language model decides, step by step, which tools to use and what to do next to finish a task, checking the result of each step before the next. A fixed script decides nothing; an agent directs its own process.
- [Context window](https://ai-powered.com/academy/glossary/context-window): The context window is the amount of text a language model can look at while it writes a reply: your messages, files, tool results and its own earlier answers. It is the model's working memory, separate from what it learned in training, and it is measured in tokens.
- [Agent skill](https://ai-powered.com/academy/glossary/agent-skill): An agent skill is a folder that teaches an AI agent how to do one kind of task. It holds a SKILL.md file (a name, a description of when to use it, and instructions) and can include scripts, templates and reference files. The agent loads it only when a task matches the description.
