agent-specialization
Guide creation of focused single-purpose agents following the One Agent One Prompt One Purpose principle. Use when designing new agents, refactoring general agents into specialists, or optimizing agent context for a single task.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for 'Agent Specialization' based on the 'One Agent One Prompt One Purpose' principle. It guides developers in creating highly focused, efficient, and reproducible AI agents by minimizing context, selecting task-specific tools, and avoiding the 'God Mode' anti-pattern. By implementing this methodology, users can build AI systems that are easier to debug, evaluate, and optimize for complex, multi-step workflows.
Use Cases
- Refactoring 'God-Mode' Agents: Deconstruct a single, over-complicated agent that handles too many disparate tasks into a coordinated team of specialized agents to improve accuracy and reliability.
- Workflow Pipeline Design: Architect a multi-step automation where each stage (e.g., classification, planning, implementation, and review) is handled by a dedicated agent with a focused prompt.
- Context Window Optimization: Maximize model performance by ensuring the entire context window is dedicated to a single specific task, reducing noise and the likelihood of hallucinations.
- Enterprise AI Scaling: Create a library of reproducible, single-purpose agent templates that can be independently versioned, A/B tested, and benchmarked against specific KPIs.
| name | agent-specialization |
|---|---|
| description | Guide creation of focused single-purpose agents following the One Agent One Prompt One Purpose principle. Use when designing new agents, refactoring general agents into specialists, or optimizing agent context for a single task. |
| allowed-tools | Read, Grep, Glob |
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