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

yaml

# ❌ 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:

markdown

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

Search AI Tools

creating-subagents

Install this agent skill to your Project

SKILL.md