Subagents
Subagents are specialized AI assistants that run in isolated contexts with their own conversation history and restricted tool access. Instead of handling everything in a single conversation, the main agent delegates focused tasks to subagents that work independently and return results.
Why subagents matter
- Context isolation - verbose output (test results, large searches) stays out of your main conversation
- Tool restrictions - a research subagent can be limited to read-only tools
- Parallelism - multiple subagents can work simultaneously on different parts of a codebase
- Cost control - route simple tasks to faster, cheaper models
Built-in subagent patterns (Claude Code)
| Type | Typical tools | Purpose |
|---|---|---|
| Explore | Usually read-focused | File discovery, code search, codebase exploration |
| Plan | Usually read-focused | Research and design during plan mode |
| General-purpose | Full tool access | Complex multi-step tasks requiring both reading and writing |
Claude automatically delegates to these based on what the task requires. You can also request a specific type:
Use an Explore subagent to find all files that import the auth module
Sources: Anthropic Claude Code subagents, Cursor agent overview, Cursor tools overview
Custom subagents
Create a custom subagent by adding a SKILL.md file (see Skills for the full skill format):
.claude/agents/code-reviewer/SKILL.md
---
name: code-reviewer
description: Reviews code for quality and best practices
allowed-tools: Read, Grep, Glob
model: sonnet
maxTurns: 10
---
You are a senior code reviewer. When invoked:
1. Review modified files for clarity and correctness
2. Check error handling and edge cases
3. Flag any security concerns
Organize feedback by priority: Critical → Warning → Suggestion
Subagents can be scoped to a project (.claude/agents/) or to all your projects (~/.claude/agents/).
If your tool version uses tools instead of allowed-tools, use the key your tool expects.
Download custom subagents I use for analysis and exploration:
Sage — A powerful "second opinion" reasoning agent for complex analysis, debugging, architecture review, and hard problems. Use when the main agent needs deeper reasoning — code review, root cause analysis, refactoring strategy, tricky bugs, security audits, or evaluating trade-offs.
Example prompt:
The function check_balance() returns None intermittently. Use the sage to trace all code
paths and find where it fails: @src/services/payment.py
Scribe — A research agent for searching and reading remote codebases on GitHub. Use when you need to look up how a library or framework is implemented, search across multiple repositories, find usage examples in open-source code, investigate dependency source code, or trace bugs into third-party libraries.
scribe subagent requires you to have gh the github CLI installed and authenticated: https://cli.github.com
Example prompt:
Use the scribe to find open-source projects that implement
rate limiting middleware in Starlette. Show me different approaches.
Use the scribe to check if any of our team's repos already have
a retry decorator utility so I don't duplicate it.