Skip to content

What is a subagent?

Glossary entry. Checked on 19 November 2026.

Subagent, in plain words

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 and context engineering.

Share this definition

Sources

Official documentation, checked on 19 November 2026. Products change: if a step differs, the source has the current version.