diegosouzapw Agent Specialization Skill
Guide for creating focused, single-purpose agents that maximize effectiveness.
When to Use
- Designing new agents for workflows
- Refactoring god-mode agents into specialists
- Optimizing agent context usage
- Creating eval-friendly agent architecture
Core Principle
"One Agent, One Prompt, One Purpose"
Every agent should:
- Have exactly one purpose
- Run exactly one prompt
- Use the full context window for that purpose
- Be reproducible and improvable
Design Workflow
Step 1: Identify the Single Purpose
Ask: "What is the ONE question this agent answers?"
| Good Purpose | Bad Purpose |
|---|---|
| "Classify this issue" | "Classify, plan, and implement" |
| "Generate a patch plan" | "Fix all the bugs" |
| "Review against spec" | "Review, test, and document" |
Step 2: Determine Minimum Required Context
Apply the Minimum Context Principle:
## Required Context
- [Specific file or section needed]
- [Pattern or example needed]
## NOT Needed
- [Documentation that's irrelevant]
- [Code that won't be touched]
Step 3: Select Appropriate Tools
Only include tools the agent will actually use:
| Purpose | Tools |
|---|---|
| Classification | Read |
| Planning | Read, Write, Glob |
| Implementation | Read, Write, Edit, Bash |
| Review | Read, Bash, Glob |
| Documentation | Read, Write |
Step 4: Choose Model
Match model to task complexity:
| Model | Best For |
|---|---|
| haiku | Classification, simple extraction |
| sonnet | Planning, moderate reasoning |
| opus | Complex implementation, critical decisions |
Step 5: Design Focused Output Format
Output should be:
- Structured (JSON when appropriate)
- Minimal (only what downstream needs)
- Parseable (for automation)
Agent Template
---
description: [Single sentence describing the ONE purpose]
tools: [Only tools actually needed]
model: [haiku/sonnet/opus based on complexity]
---
# [Agent Name]
You are a [role] agent. Your ONE purpose is to [specific task].
## Your Capabilities
- **[Tool]**: [How it supports the purpose]
## Process
[Focused steps for the single purpose]
## Output Format
[Structured output format]
## Rules
1. [Constraint that maintains focus]
2. [Another constraint]
Anti-Patterns to Avoid
God Mode Agent
# BAD: Does everything
You are an all-purpose assistant. Plan features,
implement code, write tests, review changes, and
create documentation. Handle any request.
Unfocused Output
# BAD: Returns everything
Return a detailed analysis including history,
context, alternatives, implications, and
recommendations for all stakeholders.
Kitchen Sink Tools
# BAD: All tools enabled
tools: [Read, Write, Edit, Bash, Glob, Grep, WebFetch, Task, ...]
Benefits of Specialization
- Full Context Window: 100% for the task
- No Context Confusion: Single objective
- Reproducible: Same prompt, same behavior
- Improvable: Can optimize independently
- Eval-Friendly: Can A/B test models
- Debuggable: Clear scope of responsibility
Example: Specialized vs God Mode
God Mode (Bad)
Handle the GitHub issue:
1. Classify it
2. Create a branch
3. Plan the implementation
4. Implement the feature
5. Write tests
6. Run tests
7. Review the implementation
8. Fix any issues
9. Create documentation
10. Create a PR
Specialized (Good)
/classify-issue → Issue Classifier Agent
/generate-branch-name → Branch Namer Agent
/feature → Plan Generator Agent
/implement → Plan Implementer Agent
/test → Test Runner Agent
/review → Spec Reviewer Agent
/patch → Patch Planner Agent
/document → Documentation Generator Agent
/pull-request → PR Creator Agent
Each agent does ONE thing well.
Memory References
- @one-agent-one-purpose.md - Full principle documentation
- @minimum-context-principle.md - Context engineering guidance
- @review-vs-test.md - Example of different purposes
Version History
- v1.0.0 (2025-12-26): Initial release
Last Updated
Date: 2025-12-26 Model: claude-opus-4-5-20251101