v1truv1us 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