Creating Subagents
Subagents are specialized AI instances with focused expertise, isolated context, and scoped tool access.
When to Create
- •Task repeats across projects (code review, security audit)
- •Domain expertise needed (data science, API design)
- •Pipeline step requires isolation (PM → Architect → Implementer)
- •Tool access must be restricted
Skip if: one-off task, no specialization needed.
Quick Reference
| Field | Required | Purpose |
|---|---|---|
name | Yes | Lowercase, hyphens only |
description | Yes | When to delegate (triggers) |
tools | No | Allowlist; omit = inherit all |
disallowedTools | No | Denylist; removed from inherited |
permissionMode | No | default, acceptEdits, plan, etc. |
skills | No | Preload skill content into context |
hooks | No | Lifecycle hooks (PreToolUse, Stop) |
color | No | Background color for UI identification |
Design Process
1. Define the Problem
Before writing code, answer:
- •What task does this agent solve?
- •What does success look like?
- •What tools are absolutely required?
- •What should the agent NOT do?
2. Write Description First
Description determines when agent is invoked. Write it before the prompt.
Pattern: [Role]. [Trigger condition]. Use proactively [when].
yaml
# ❌ BAD: Vague, no trigger description: Helps with code # ❌ BAD: Describes process, not trigger description: Reviews code and provides feedback # ✅ GOOD: Clear role + trigger + proactive hint description: Code quality reviewer. Use proactively after code changes.
3. Minimal Viable Prompt
Start with the smallest prompt that works:
markdown
--- name: code-reviewer description: Code quality reviewer. Use proactively after code changes. tools: Read, Glob, Grep, Bash color: blue --- You are a code reviewer. When invoked: 1. Run git diff to see changes 2. Review modified files 3. Report: Critical → Warnings → Suggestions Include fix examples.
4. Test Before Deploy
Run the agent on real tasks. Document:
- •Did it activate when expected?
- •Did it have the right tools?
- •Was output useful and structured?
- •Did it stay in scope?
5. Iterate Based on Failures
When agent fails, identify the gap:
| Symptom | Fix |
|---|---|
| Doesn't activate | Improve description triggers |
| Wrong scope | Add constraints to prompt |
| Missing context | Add required tools or skills |
| Unstructured output | Define output format in prompt |
| Does too much | Split into focused agents |
Tool Access by Role
| Role | Tools |
|---|---|
| Read-only | Read, Grep, Glob |
| Research | Read, Grep, Glob, WebFetch, WebSearch |
| Code modification | Read, Write, Edit, Bash, Glob, Grep |
| Full access | (omit field — inherits all) |
Common Mistakes
| Mistake | Fix |
|---|---|
| Vague description | Specific triggers: "after code changes" |
| Tool inheritance by default | Explicit tools field for security |
| No structured output | Define format in prompt |
| Monolithic mega-agent | Split into single-purpose agents |
| Missing "Use proactively" | Add to description for auto-delegation |
| Prompt before description | Write description first — it's the API |
Creation Checklist
- • Problem clearly defined (what, success criteria, non-goals)
- • Description written first with trigger conditions
- • Tools explicitly listed (not inherited)
- • Prompt is minimal and focused
- • Output format defined
- • Tested on real task
- • Iterated based on failures
Pipeline Pattern
Chain agents for multi-stage workflows:
code
pm-spec → architect-review → implementer-tester
Each agent:
- •Has single responsibility
- •Updates status on completion
- •Hooks trigger next stage