majiayu000 Subagent Creator
Create effective subagents that handle autonomous tasks via the Task tool.
Subagents vs Skills
| Aspect | Subagent | Skill |
|---|---|---|
| Invocation | Explicit via Task tool | Auto-triggered by context |
| Context | Isolated (fresh context window) | Shared with parent |
| Complexity | Single .md file | Folder with resources |
| Use case | Autonomous discrete tasks | Guidance and procedures |
| Nesting | Cannot spawn other subagents | Can reference other skills |
Use subagent when:
- Task is discrete and autonomous
- Fresh context window is beneficial
- Task can run in parallel with other work
- Specialized tool restrictions needed
Use skill when:
- Guidance needed throughout conversation
- Context sharing is important
- Multiple resources (scripts, references) needed
Subagent Structure
agents/
└── agent-name.md
├── YAML frontmatter (metadata)
└── Markdown body (system prompt)
Frontmatter Fields
| Field | Required | Description |
|---|---|---|
name |
Yes | Lowercase, hyphens only (e.g., code-reviewer) |
description |
Yes | When to use - this triggers dispatch decisions |
tools |
No | Comma-separated: Bash, Glob, Grep, Read, Edit, Write |
model |
No | sonnet, opus, haiku, or inherit (default: inherit) |
permissionMode |
No | default, acceptEdits, bypassPermissions, plan |
skills |
No | Comma-separated skills to auto-load |
Tools Reference
Read-only: Glob, Grep, Read, WebFetch, WebSearch
Write: Edit, Write, NotebookEdit
Execute: Bash
All: * (or omit field)
Permission Modes
| Mode | Description |
|---|---|
default |
Normal permission prompts |
acceptEdits |
Auto-accept file edits |
bypassPermissions |
Skip all permission prompts |
plan |
Plan mode - explore but don't modify |
Writing Effective Prompts
Structure
---
name: agent-name
description: When to use this agent. Be specific about triggers.
tools: Tool1, Tool2
model: sonnet
---
# Agent Name
One-line role description.
## Input Required
What the agent expects to receive.
## Process
Step-by-step what the agent does.
## Output Format
Exact format of the response.
## Rules
- Constraints and boundaries
- What to avoid
Best Practices
- Be specific about role - First line defines identity
- Define clear inputs - What must be provided
- Structure the process - Numbered steps
- Specify output format - Use code blocks for templates
- Set boundaries - What NOT to do
Description Guidelines
The description field triggers when the agent is suggested. Include:
- Primary use case
- Required inputs
- Expected output type
# Good
description: Use after completing a task to review code changes. Provide BASE_SHA, HEAD_SHA, and requirements. Returns issues with file:line references.
# Bad
description: Reviews code.
Examples
Minimal Subagent
---
name: summarizer
description: Use to summarize long documents or conversations. Provide the content to summarize.
tools: Read
model: haiku
---
# Summarizer
Summarize the provided content in 3-5 bullet points.
Focus on: key decisions, action items, conclusions.
Skip: greetings, filler, obvious context.
Full Subagent
See references/subagent-examples.md for complete examples.
Creation Process
- Define the task - What autonomous work does this agent do?
- Choose tools - Minimum needed (prefer restrictive)
- Choose model - haiku for simple, sonnet for complex, opus for critical
- Write prompt - Role, process, output, rules
- Test - Dispatch via Task tool, iterate
Init Script
scripts/init_subagent.py <agent-name> --path <output-directory>
Creates template agent file with proper structure.
Anti-Patterns
- Too broad - Agent tries to do everything
- Too many tools - Give minimum necessary
- Vague output - Always specify exact format
- No boundaries - Must define what NOT to do
- Wrong model - Don't use opus for simple tasks