# Subagent Design Patterns

> 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.

- Skill: `v1truv1us/subagent-design-patterns` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add v1truv1us/subagent-design-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/v1truv1us/subagent-design-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: v1truv1us (https://skillmd.com/u/v1truv1us)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/v1truv1us/subagent-design-patterns

---


## 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 descriptions
- `references/tool-patterns.md` - Tool access with examples
- `references/parallel-execution.md` - Background/parallel design
- See Implementation skill for technical frontmatter specs