Subagents are isolated assistants with their own context window. They are invoked via the Task tool in Claude Code.
Each subagent is a .md file inside .claude/agents/ with YAML frontmatter and a prompt.
Example: scanner.md
---
name: scanner
description: Scans a single source file for deprecated API calls.
tools: Read, Grep, Glob
prompt: |
You are a scanner subagent...
Always return JSON with a clear schema. Include status (success/error), the file path, and relevant data.
{
"status": "success",
"file": "path/to/file",
"occurrences": [...]
}
If anything fails (missing file, permission denied), return an error status with details.
{
"status": "error",
"file": "path/to/file",
"error": "File not found"
}
Only give the subagent the tools it needs. Scanner does not need Write. Rewriter does not need Bash.
Subagents never communicate directly. The orchestrator collects results and passes them as input to the next subagent.
---
name: rewriter
tools: Read, Write, Edit
prompt: |
Apply migration mapping to a file. Return JSON with changes_made.
For the full implementation, see .claude/agents/ in the repository.