creating-subagents

name	creating-subagents
description	Use when need to create specialized subagent for recurring tasks, domain-specific work, or pipeline automation

Creating Subagents

Subagents are specialized AI instances with focused expertise, isolated context, and scoped tool access.

When to Create

• Task repeats across projects (code review, security audit)
• Domain expertise needed (data science, API design)
• Pipeline step requires isolation (PM → Architect → Implementer)
• Tool access must be restricted

Skip if: one-off task, no specialization needed.

Quick Reference

Field	Required	Purpose
name	Yes	Lowercase, hyphens only
description	Yes	When to delegate (triggers)
tools	No	Allowlist; omit = inherit all
disallowedTools	No	Denylist; removed from inherited
permissionMode	No	default, acceptEdits, plan, etc.
skills	No	Preload skill content into context
hooks	No	Lifecycle hooks (PreToolUse, Stop)
color	No	Background color for UI identification

Design Process

1. Define the Problem

Before writing code, answer:

• What task does this agent solve?
• What does success look like?
• What tools are absolutely required?
• What should the agent NOT do?

2. Write Description First

Description determines when agent is invoked. Write it before the prompt.

Pattern: [Role]. [Trigger condition]. Use proactively [when].

# ❌ BAD: Vague, no trigger
description: Helps with code

# ❌ BAD: Describes process, not trigger
description: Reviews code and provides feedback

# ✅ GOOD: Clear role + trigger + proactive hint
description: Code quality reviewer. Use proactively after code changes.

3. Minimal Viable Prompt

Start with the smallest prompt that works:

---
name: code-reviewer
description: Code quality reviewer. Use proactively after code changes.
tools: Read, Glob, Grep, Bash
color: blue
---

You are a code reviewer. When invoked:

1. Run git diff to see changes
2. Review modified files
3. Report: Critical → Warnings → Suggestions

Include fix examples.

4. Test Before Deploy

Run the agent on real tasks. Document:

• Did it activate when expected?
• Did it have the right tools?
• Was output useful and structured?
• Did it stay in scope?

5. Iterate Based on Failures

When agent fails, identify the gap:

Symptom	Fix
Doesn't activate	Improve description triggers
Wrong scope	Add constraints to prompt
Missing context	Add required tools or skills
Unstructured output	Define output format in prompt
Does too much	Split into focused agents

Tool Access by Role

Role	Tools
Read-only	Read, Grep, Glob
Research	Read, Grep, Glob, WebFetch, WebSearch
Code modification	Read, Write, Edit, Bash, Glob, Grep
Full access	(omit field — inherits all)

Common Mistakes

Mistake	Fix
Vague description	Specific triggers: "after code changes"
Tool inheritance by default	Explicit tools field for security
No structured output	Define format in prompt
Monolithic mega-agent	Split into single-purpose agents
Missing "Use proactively"	Add to description for auto-delegation
Prompt before description	Write description first — it's the API

Creation Checklist

• Problem clearly defined (what, success criteria, non-goals)
• Description written first with trigger conditions
• Tools explicitly listed (not inherited)
• Prompt is minimal and focused
• Output format defined
• Tested on real task
• Related section linking to commands and skills
• Iterated based on failures

Pipeline Pattern

Chain agents for multi-stage workflows:

pm-spec → architect-review → implementer-tester

Each agent:

• Has single responsibility
• Updates status on completion
• Hooks trigger next stage