Creating Subagents
creating-subagents
Subagents are specialized AI instances with focused expertise, isolated context, and scoped tool access.
SKILL.md
Full skill instructions
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].
# ❌ 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:
---
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:
pm-spec → architect-review → implementer-tester
Each agent:
- Has single responsibility
- Updates status on completion
- Hooks trigger next stage