| name | Subagent Design Patterns |
| description | Core principles for designing effective subagents. Use when asked to "design a subagent", "structure a subagent", "subagent best practices". Provides essential guidance with references for deep dives. |
| version | 0.2.0 |
Core Concepts
A subagent is an autonomous AI assistant with custom configuration, operating in its own context window.
When to Use Subagents vs. Main Conversation
| Use Main Conversation | Use Subagents |
|---|
| Iterative refinement | Verbose output (logs, data) |
| Shared context across phases | Tool restrictions needed |
| Frequent user feedback | Self-contained tasks |
| Low latency required | Parallel/background work |
Key trade-off: Subagents isolate context but start fresh. Use for self-contained tasks with summary outputs.
For detailed analysis, see references/when-to-use.md.
Five Core Design Decisions
1. Role Clarity (Most Critical)
Write descriptions with:
- Role statement: "Database performance analyst"
- Triggers: "Analyze slow queries", "Explain execution plans"
- Boundaries: "Not for schema design"
Poor: description: Helps with debugging
Strong: description: Database query performance specialist. Use proactively when analyzing slow queries or explaining execution plans. Not for schema design.
See references/role-clarity.md for complete guide with examples.
2. Tool Access Strategy
Grant minimum necessary tools:
| Pattern | Tools | Use For |
|---|
| Read-only | ["Read", "Grep", "Glob"] | Reviewers, analyzers |
| Generation | ["Read", "Write", "Bash"] | Creators, scaffolders |
| Modification | ["Read", "Edit", "Bash"] | Fixers, debuggers |
See references/tool-patterns.md for complete patterns and examples.
3. Model Selection
| Model | Best For | Cost |
|---|
haiku | Data analysis, validation | ~90% cheaper |
sonnet | Code tasks (recommended default) | Balanced |
opus | Complex reasoning | Highest |
inherit | Match parent (most common) | Varies |
4. Permission Modes
default - Standard prompts (testing)acceptEdits - Auto-accept modifications (trusted agents)dontAsk - Auto-deny unpermitted (automation)
5. Common Patterns
| Pattern | Role | Tools | Model |
|---|
| Reviewer | Code/doc analysis | Read-only | Sonnet |
| Analyzer | Data/log processing | Read+Bash | Haiku |
| Generator | Create artifacts | Read+Write | Sonnet |
| Fixer | Debug/fix issues | Read+Edit+Bash | Sonnet |
| Validator | Check configs | Read+Bash | Haiku |
Anti-Patterns to Avoid
- Vague descriptions ("Helps with stuff")
- Too many tools (grant only what's needed)
- System prompts >5000 chars
- Overlapping subagents
- No summary output
Quick Reference
For deeper guidance:
references/role-clarity.md - Writing powerful descriptionsreferences/tool-patterns.md - Tool access with examplesreferences/parallel-execution.md - Background/parallel design- See Implementation skill for technical frontmatter specs
