Sub-Agents Reference

Name: sub-agents
Rating: 78
Author: scooter-lacroix

Create specialized AI agents with isolated contexts for specific tasks.

When to Use

•"How do I create a sub-agent?"
•"Configure agent tools"
•"What built-in agents exist?"
•"Agent model selection"
•"Agent chaining patterns"

Quick Start

Interactive (Recommended)

bash

/agents

Opens menu to create, edit, and manage agents.

Manual Creation

bash

mkdir -p .maestro/agents
cat > .maestro/agents/reviewer.md << 'EOF'
---
name: reviewer
description: Code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer focusing on quality and security.

## Review Checklist
- Code clarity and naming
- Error handling
- Security vulnerabilities
- Test coverage
EOF

CLI-Based

bash

claude --agents '{
  "reviewer": {
    "description": "Code reviewer",
    "prompt": "Review for quality and security",
    "tools": ["Read", "Bash"],
    "model": "sonnet"
  }
}'

Agent File Format

yaml

---
name: agent-name
description: When/why to use this agent
tools: Read, Edit, Bash      # Optional, inherits all if omitted
model: sonnet                 # sonnet, opus, haiku, inherit
---

System prompt content here...

Configuration Fields

Field	Required	Options
`name`	Yes	lowercase, hyphens
`description`	Yes	When to use
`tools`	No	Tool list (inherits all if omitted)
`model`	No	`sonnet`, `opus`, `haiku`, `inherit`

Built-In Agents

Agent	Model	Tools	Purpose
General-purpose	Sonnet	All	Complex multi-step tasks
Plan	Sonnet	Read-only	Plan mode research
Explore	Haiku	Read-only	Fast codebase search

Model Selection

Model	Speed	Best For
Haiku	Fastest	Search, quick lookups
Sonnet	Fast	Most tasks (default)
Opus	Slower	Complex reasoning

Tool Combinations

yaml

# Code Reviewer (read-only)
tools: Read, Grep, Glob, Bash

# Debugger
tools: Read, Edit, Bash, Grep, Glob

# Implementer
tools: Read, Write, Edit, Bash, Glob

Example Agents

Code Reviewer

yaml

---
name: code-reviewer
description: Reviews code for quality and security. Use after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Review code for:
- Security vulnerabilities
- Code quality issues
- Missing error handling
- Test coverage gaps

Output findings by priority: Critical > Warning > Suggestion

Debugger

yaml

---
name: debugger
description: Debug errors and test failures.
tools: Read, Edit, Bash, Grep, Glob
model: inherit
---

Debugging process:
1. Capture error details
2. Identify failure location
3. Form hypotheses
4. Test and verify
5. Implement fix

File Locations

Type	Location	Priority
Project	`.maestro/agents/`	Highest
User	`~/.maestro/agents/`	Lower

Advanced Patterns

Resumable Agents

code

[Agent returns agentId: "abc123"]

# Later: resume with context
claude -r "abc123" "Continue analysis"

Agent Chaining

code

Use code-analyzer to find issues,
then use optimizer to fix them

Best Practices

•Single responsibility - One clear purpose per agent
•Restrict tools - Only grant what's needed
•Clear descriptions - Action-oriented, include "proactively"
•Version control - Check .maestro/agents/ into git