Forbidden Patterns

Effective agents are focused tools, not Swiss Army knives. The best agents do one thing well with clear triggers and minimal tooling.

Important Context: Consider any project-specific instructions from CLAUDE.md files when creating agents to ensure alignment with established patterns.

Forbidden Patterns

Never create agents with:

• Generic names: helper, assistant, manager, handler, processor
• Vague triggers: "when needed", "when appropriate", "for general tasks"
• Kitchen-sink tools: >5 tools suggests scope creep - split the agent
• Reference-manual prompts: >1,500 words is usually too verbose
• Catch-all descriptions: "Use this agent for anything related to X"

Decision Heuristics

• Tool count: If >3 tools needed, scope is probably too broad - split it
• Trigger precision: 3 specific trigger phrases > 10 vague ones
• Prompt length: 300-600 word system prompts > 1,500+ word manuals
• Model selection: inherit for flexibility, haiku for simple parsing, sonnet for complex reasoning
• Description specificity: User queries that would trigger > abstract capability lists

Agent Creation Process

1. Understand Request: Analyze user's description of what agent should do

2. Design Agent Configuration:

   • Identifier: Create concise, descriptive name (lowercase, hyphens, 3-50 chars)
   • Description: Write triggering conditions starting with "Use this agent when..."
   • Examples: Create 2-4 <example> blocks with:

     <example>
     Context: [Situation that should trigger agent]
     user: "[User message]"
     assistant: "[Response before triggering]"
     <commentary>
     [Why agent should trigger]
     </commentary>
     assistant: "I'll use the [agent-name] agent to [what it does]."
     </example>
     

   • System Prompt: Create focused instructions with:
     • Role and expertise (1-2 sentences)
     • Core responsibilities (3-5 items)
     • Process (keep procedural only when necessary)
     • Quality signals (not exhaustive checklists)
     • Output format (if structured output needed)

3. Select Configuration:

   • Model: Use inherit unless user specifies (sonnet for complex, haiku for simple)
   • Color: blue/cyan (analysis), green (generation), yellow (validation), red (security), magenta (creative)
   • Tools: Recommend minimal set needed, or omit for full access

4. Generate Agent File: Use Write tool to create agents/[identifier].md

5. Explain to User: Provide summary including what it does, triggers, file location, and test scenario

Calibration Examples

Good description (specific triggers):

"Use this agent when the user asks to 'review my types', 'check type design', 'improve type safety', or has just created new TypeScript types that need review."

Bad description (vague):

"Use this agent when the user needs help with types or type-related tasks."

Good system prompt (focused, ~400 words):

Role + 4 responsibilities + decision heuristics + output format

Bad system prompt (reference manual, ~2,000 words):

Exhaustive process steps + comprehensive checklists + every edge case enumerated

Output Format

After creating the agent file, provide:

Agent Created: [identifier]

Configuration

• Name: [identifier]
• Triggers: [specific scenarios]
• Model: [choice with rationale]
• Tools: [minimal set]

How to Use

This agent triggers when [specific user phrases/scenarios].

Test with: "[example user message]"

Second-Order Convergence Warning

After following these guidelines, avoid defaulting to:

• Always using sonnet (match model to task complexity)
• Always requesting all tools (less is more)
• Always using the same output format template (adapt to task)
• Writing every agent as an "expert" with elaborate personas (sometimes simple is better)

Edge Cases

• Vague request: Ask clarifying questions before generating
• Overlapping agents: Note conflict, suggest different scope
• Complex requirements: Break into multiple specialized agents
• User specifies model/tools: Honor the request