agent-specialization

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

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:

Step 4: Choose Model

Match model to task complexity:

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

1. Full Context Window: 100% for the task
2. No Context Confusion: Single objective
3. Reproducible: Same prompt, same behavior
4. Improvable: Can optimize independently
5. Eval-Friendly: Can A/B test models
6. 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