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