Features · Extend it · since version 1.0.60

Subagents

Hand a side task to a specialised helper that works in its own context and reports back a summary.

What it is

A subagent is an assistant set up for one kind of task. It has its own context window, its own system prompt and its own list of allowed tools. Claude delegates a matching task to it, the subagent does the work separately, and only its result comes back to your main conversation.

Why it matters

  • A cleaner main conversationSearch results, logs and file contents from a side task stay in the subagent's context instead of filling yours.
  • Tighter limitsEach subagent can be restricted to the tools it needs, for example read-only tools for a reviewer.
  • ReuseA subagent saved in your home folder is available in all your projects; one saved in a repository is shared with the team.
  • Cost controlA subagent can be set to run on a faster, lower-cost model.

How it works

  1. Create a Markdown file in .claude/agents/ (this project) or ~/.claude/agents/ (all your projects).
  2. At the top, add YAML frontmatter with a name and a description, and optionally the tools and model it may use.
  3. Write the subagent's system prompt below the frontmatter.
  4. Claude delegates a task when it matches the description, or you can name the subagent yourself with an @-mention.
  5. The subagent works on its own and returns its result to the main conversation.

Hands-on example coming

This feature has no reviewed example yet. The official documentation below has the details.

Update history

  1. Version 1.0.60 · Jul 24, 2025

    Introduced Custom subagents arrived, created with the /agents command.

Official documentation