Short answer: a subagent is a specialist with its own instructions, tools and context window. The main agent delegates a focused task, the subagent works in isolation and returns only the result. Use them to keep the main conversation clean, to enforce a narrow set of tools, and to run independent work in parallel.
Agent tooling changes fast. Commands and file formats below match the versions current at the time of writing; check the official docs for your version before relying on them.
When a subagent is worth it
| Situation | Why a subagent helps |
|---|---|
| Large searches across a codebase or logs | The noise stays in the subagent; you get the conclusion |
| A task that needs strict rules (security review, migrations) | Its own system prompt and a limited tool list |
| Independent pieces of work | Several subagents can run in parallel |
| Repeatable roles in a team | The same reviewer or tester for everyone, versioned in Git |
Define one in Claude Code
Subagents are Markdown files with YAML front matter, in .claude/agents/ (project, shared in Git) or ~/.claude/agents/ (just you). The /agents command lists and creates them interactively.
.claude/agents/aws-cost-reviewer.md
---
name: aws-cost-reviewer
description: Reviews Terraform and CloudFormation changes for AWS cost risks.
Use proactively when infrastructure files change.
tools: Read, Grep, Glob
model: sonnet
---
You are a senior FinOps engineer. Review only the infrastructure changes
you are given.
For each finding, report:
- the resource and file,
- the cost driver (hours, GB processed, requests, storage),
- an estimate with the assumption you used, labelled as an estimate,
- a cheaper alternative if one exists.
Flag in particular: NAT Gateways, cross-AZ traffic, oversized instances,
missing lifecycle rules on S3, log retention without limits.
Never edit files. Finish with a table of findings sorted by impact.How to call it
prompt
Use the aws-cost-reviewer subagent on the changes in infra/ since main.
Then use a separate subagent to check whether every new resource has
the tags "owner" and "cost-center". Run both in parallel and give me
one combined report.The description field matters: Claude uses it to decide when to delegate on its own. “Use proactively when…” makes automatic delegation more likely.
Design rules that work
- One job per subagent. “Reviewer” and “fixer” are two subagents, not one.
- Fewest tools possible. A reviewer does not need write access.
- Define the output. Ask for a table or a fixed structure, so results are easy to merge.
- Return conclusions, not transcripts. Tell it to summarize what it found and where.
A subagent starts without the main conversation’s context. Put everything it needs in the delegation prompt: files, constraints, what “done” means.
And in ChatGPT?
ChatGPT has no user-defined subagent files. The closest options are separate Custom GPTs or Projects for each role, and, for developers, the OpenAI Agents SDK, where an agent can hand off work to specialized agents in code.