Agents

First Pass: Structure and YAML Frontmatter

Focus Areas:

• Not done: YAML frontmatter present and syntactically valid
• Not done: Required fields: name and description
• Not done: Optional fields validated if present: tools, model
• Not done: System prompt exists and is non-empty
• Not done: File structure follows markdown format

Required YAML Frontmatter:

Optional YAML Fields:

Critical Issues to Flag Immediately:

• Missing YAML frontmatter (agent won’t be recognized)
• Missing name field
• Missing description field
• Invalid YAML syntax (tabs, malformed structure)
• Invalid model value (must be: sonnet, opus, haiku, inherit)
• Invalid tool names in tools field
• Empty system prompt

Reference: Anthropic - Claude Code Subagents Documentation (opens in a new tab)

Second Pass: Security and Tool Access

Principle of Least Privilege: Agents should have ONLY the tools necessary for their specific function.

Tool Access Patterns:

✅ GOOD - Read-only analysis agent:

✅ GOOD - Scoped editing agent:

❌ BAD - Overly broad access:

❌ BAD - Unnecessary destructive access:

Security Checks:

• Not done: Tool access scoped to minimum required
• Not done: Read-only agents don’t have Write/Edit/Bash
• Not done: Bash access is justified for agent purpose
• Not done: If tools omitted (inherits all), this is intentional and documented
• Not done: No dangerous tool combinations without justification

Common Secure Patterns:

• Analyst/Reviewer: Read, Grep, Glob (read-only)
• Code Generator: Read, Grep, Write (creates new files)
• Refactoring Agent: Read, Grep, Edit (modifies existing)
• Automation Agent: Read, Write, Bash (needs command execution)

Red Flags:

• Inheriting all tools without clear justification
• Bash access without explanation
• Write/Edit access for analysis-only agents
• Tool access mismatched to agent description

Reference: reference/claude-code-requirements.md - Tool Access Security (lines 109-133)

Third Pass: Description and Activation Triggers

Effective Descriptions: Descriptions must be specific about BOTH functionality AND activation triggers.

✅ GOOD - Specific with activation triggers:

✅ GOOD - Clear automatic delegation:

✅ GOOD - Narrow scope with examples:

❌ BAD - Too vague:

❌ BAD - No activation triggers:

❌ BAD - Too broad (violates single responsibility):

Check For:

• Not done: Description states what the agent does
• Not done: Description includes activation triggers (when to use)
• Not done: Description is specific, not vague
• Not done: Single responsibility (focused scope)
• Not done: Appropriate level of detail (not too terse, not too verbose)

Activation Language Patterns:

• “Use when…” - Explicit trigger conditions
• “PROACTIVELY invoke…” - Encourages automatic delegation
• “Use for…” - Specific use cases
• Language/framework specific - Improves targeting

Fourth Pass: System Prompt Quality

System Prompt Requirements:

Clarity and Specificity:

• Not done: Role clearly defined
• Not done: Capabilities explicitly stated
• Not done: Constraints and boundaries documented
• Not done: Expected behavior specified
• Not done: Output format defined (if applicable)

Prompt Engineering Best Practices:

✅ GOOD - Structured with examples:

✅ GOOD - Includes structured thinking:

❌ BAD - Too vague:

❌ BAD - No structure or examples:

Structured Thinking Guidance:

• Not done: <thinking> blocks guide reasoning process
• Not done: Key questions posed for each major step
• Not done: Decision criteria made explicit
• Not done: Systematic analysis approach modeled

Token Efficiency:

• Not done: Concise without losing clarity
• Not done: Examples are minimal but sufficient
• Not done: No unnecessary verbosity
• Not done: Direct language preferred

Reference: Anthropic Chain of Thought documentation (40% error reduction with structured thinking)

Fifth Pass: Model Selection and Best Practices

Model Selection Guidance:

When to Use Each Model:

Haiku - Simple, straightforward tasks:

• Formatting code
• Running predefined scripts
• Simple file operations
• Quick analysis with clear criteria

Sonnet - Most agent tasks (default):

• Code review
• Bug analysis
• Test generation
• Documentation writing
• Moderate complexity reasoning

Opus - Complex reasoning only:

• Architectural decisions
• Complex refactoring across multiple files
• Novel problem-solving
• High-stakes analysis requiring maximum accuracy

Inherit - Context-dependent:

• When agent needs same context as main conversation
• When model selection should match user’s choice
• For consistency across conversation

Best Practice Checks:

• Not done: Model specified or intentionally omitted
• Not done: Model complexity matches task complexity
• Not done: Not using opus unnecessarily (cost/latency)
• Not done: Haiku used where speed matters and task is simple
• Not done: Single responsibility principle followed
• Not done: Agent scope appropriately focused

Anti-Patterns:

• Using opus for simple formatting tasks
• Using haiku for complex analysis
• Agent trying to handle too many different task types
• Model selection not documented/justified

Reference: Anthropic - Subagent Configuration Best Practices (opens in a new tab)

Sixth Pass: Plugin Marketplace Standards

For Marketplace-Bound Agents:

Elevated Standards:

• Missing examples: SUGGESTED → IMPORTANT
• Vague descriptions: IMPORTANT → CRITICAL
• Poor system prompt: SUGGESTED → IMPORTANT
• Undocumented tool access: IMPORTANT → CRITICAL

Documentation Requirements:

• Not done: Clear purpose and use cases
• Not done: Examples in system prompt
• Not done: Tool access justified
• Not done: Model selection explained
• Not done: Expected outputs demonstrated

Production Readiness:

• Not done: Error handling considered
• Not done: Edge cases addressed
• Not done: Clear success/failure criteria
• Not done: Graceful degradation patterns

Internal vs Marketplace:

• Internal agents: Can accept more SUGGESTED issues
• Marketplace agents: Must fix all IMPORTANT issues
• Both: Must fix all CRITICAL security/functionality issues

Priority Classification

Classify findings using reference/priority-framework.md:

• CRITICAL - Prevents functionality or exposes security vulnerabilities
• IMPORTANT - Significantly impacts quality or maintainability
• SUGGESTED - Improvements that aren’t essential
• OPTIONAL - Personal preferences

Common Agent Anti-Patterns

Over-Privileged Agent:

• Inherits all tools without justification
• Bash access for read-only task
• Fix: Specify minimum required tools

Vague Purpose:

• Description: “Helps with code”
• Better: “Reviews Python code for PEP 8 violations. Use when analyzing .py files.”

Missing Structured Thinking:

• System prompt lacks reasoning guidance
• No decision criteria for complex choices
• Fix: Add <thinking> blocks with key questions

Wrong Model Selection:

• Using opus for simple formatting
• Using haiku for complex analysis
• Fix: Match model to task complexity

Scope Creep:

• Agent trying to handle multiple unrelated tasks
• Jack-of-all-trades, master of none
• Fix: Split into focused, single-purpose agents

Security Oversights:

• Bash access without scoping
• Write access for analysis-only agents
• No consideration of tool access implications
• Fix: Apply principle of least privilege

Final Checklist Summary

Before completing review, verify:

• Not done: YAML frontmatter present and valid
• Not done: Required fields (name, description) present
• Not done: Optional fields valid if present
• Not done: Tool access follows least privilege
• Not done: Description includes activation triggers
• Not done: System prompt is clear and specific
• Not done: Model selection appropriate for task
• Not done: Single responsibility principle followed
• Not done: Security implications considered
• Not done: Marketplace standards met (if applicable)