--- name: agent-builder description: Use when creating, improving, or troubleshooting Claude Code subagents. Expert guidance on agent design, system prompts, tool access, model selection, and best practices for building specialized AI assistants. tags: meta globs: - "**/.claude/agents/**/*.md" - "**/.claude/agents/**/*.markdown" alwaysApply: false --- # Agent Builder - Claude Code Subagent Expert Use this skill when creating, improving, or troubleshooting Claude Code subagents. Provides expert guidance on agent design, system prompt engineering, tool configuration, and delegation patterns. ## When to Use This Skill Activate this skill when: - User asks to create a new subagent - User wants to improve an existing agent - User needs help with agent configuration or tool access - User is troubleshooting agent invocation issues - User wants to understand when to use agents vs skills vs commands - User asks about agent chaining or delegation patterns ## Quick Reference ### Agent File Structure ```markdown --- name: agent-name description: When and why to use this agent tools: Read, Write, Bash(git *) model: sonnet --- Your detailed system prompt defining: - Agent role and expertise - Problem-solving approach - Output format expectations - Specific constraints or requirements ``` ### File Locations **Project agents** (shared with team, highest priority): ``` .claude/agents/my-agent.md ``` **Personal agents** (individual use, lower priority): ``` ~/.claude/agents/my-agent.md ``` **Plugin agents** (from installed plugins): ``` /agents/agent-name.md ``` ## Creating Effective Subagents ### Step 1: Identify the Use Case **Good candidates for subagents:** - Complex, multi-step workflows - Specialized expertise (debugging, security review, data analysis) - Tasks requiring focused context - Repeatable processes with specific quality bars - Code review and analysis workflows **NOT good for subagents (use Skills/Commands instead):** - Simple one-off prompts (use Slash Commands) - Context-aware automatic activation (use Skills) - Quick transformations or formatting ### Step 2: Design Agent Scope **Best practices:** - **Single responsibility** - Each agent does ONE thing exceptionally well - **Clear boundaries** - Define what's in/out of scope - **Specific expertise** - Don't create "general helper" agents - **Measurable outcomes** - Agent should produce concrete deliverables **Examples:** - ✅ **code-reviewer** - Reviews code changes for quality, security, and best practices - ✅ **debugger** - Root cause analysis and minimal fixes for errors - ✅ **data-scientist** - SQL query optimization and data analysis - ❌ **helper** - Too vague, no clear scope - ❌ **everything** - Defeats purpose of specialization ### Step 3: Write the System Prompt The system prompt is the most critical part of your agent. It defines the agent's personality, capabilities, and approach. **Structure for effective prompts:** ```markdown --- name: code-reviewer description: Analyzes code changes for quality, security, and maintainability tools: Read, Grep, Bash(git *) model: sonnet --- # Code Reviewer Agent You are an expert code reviewer specializing in [language/framework]. ## Your Role Review code changes thoroughly for: 1. Code quality and readability 2. Security vulnerabilities 3. Performance issues 4. Best practices adherence 5. Test coverage ## Review Process 1. **Read the changes** - Get recent git diff or specified files - Understand the context and purpose 2. **Analyze systematically** - Check each category (quality, security, performance, etc.) - Provide specific file:line references - Explain why something is an issue 3. **Provide actionable feedback** Format: ### 🔴 Critical Issues - [Issue] (file.ts:42) - [Explanation] - [Fix] ### 🟡 Suggestions - [Improvement] (file.ts:67) - [Rationale] - [Recommendation] ### ✅ Good Practices - [What was done well] 4. **Summarize** - Overall assessment - Top 3 priorities - Approval status (approve, approve with comments, request changes) ## Quality Standards **Code must:** - [ ] Follow language/framework conventions - [ ] Have proper error handling - [ ] Include necessary tests - [ ] Not expose secrets or sensitive data - [ ] Use appropriate abstractions (not over-engineered) **Flag immediately:** - SQL injection risks - XSS vulnerabilities - Hardcoded credentials - Memory leaks - O(n²) or worse algorithms in hot paths ## Output Format Always provide: 1. Summary (1-2 sentences) 2. Categorized findings with file:line refs 3. Approval decision 4. Top 3 action items Be thorough but concise. Focus on what matters. ``` ### Step 4: Configure Tools Access **Available tools:** - `Read` - Read files - `Write` - Create new files - `Edit` - Modify existing files - `Bash` - Execute shell commands - `Grep` - Search file contents - `Glob` - Find files by pattern - `WebFetch` - Fetch web content - `WebSearch` - Search the web - Plus any connected MCP tools **Tool configuration patterns:** **Inherit all tools** (omit `tools` field): ```yaml --- name: full-access-agent description: Agent needs access to everything # No tools field = inherits all --- ``` **Specific tools only**: ```yaml --- name: read-only-reviewer description: Reviews code without making changes tools: Read, Grep, Bash(git *) --- ``` **Bash with restrictions**: ```yaml --- name: git-helper description: Git operations only tools: Bash(git *), Read --- ``` **Security best practice:** Grant minimum necessary tools. Don't give `Write` or `Bash` unless required. ### Step 5: Choose Model **Model options:** - `sonnet` - Balanced, good for most agents (default) - `opus` - Complex reasoning, architectural decisions - `haiku` - Fast, simple tasks (formatting, quick checks) - `inherit` - Use main conversation's model **When to use each:** **Sonnet (most agents):** ```yaml model: sonnet ``` - Code review - Debugging - Data analysis - General problem-solving **Opus (complex reasoning):** ```yaml model: opus ``` - Architecture decisions - Complex refactoring - Deep security analysis - Novel problem-solving **Haiku (speed matters):** ```yaml model: haiku ``` - Syntax checks - Simple formatting - Quick validations - Low-latency needs **Inherit (context-dependent):** ```yaml model: inherit ``` - Agent should match user's model choice - Cost sensitivity ### Step 6: Write Clear Description The `description` field determines when Claude invokes your agent automatically. **Best practices:** - Start with "Use when..." or "Analyzes..." or "Helps with..." - Be specific about the agent's domain - Mention key capabilities - Include when NOT to use (if helpful) **Examples:** ✅ **Good descriptions:** ```yaml description: Analyzes code changes for quality, security, and maintainability issues description: Use when debugging errors - performs root cause analysis and suggests minimal fixes description: Helps with SQL query optimization and data analysis tasks ``` ❌ **Poor descriptions:** ```yaml description: A helpful agent # Too vague description: Does code stuff # Not specific enough description: Reviews, debugs, refactors, tests, documents, and deploys code # Too broad ``` ## Agent Patterns ### Pattern 1: Code Reviewer **Purpose:** Systematic code review with quality gates ```markdown --- name: code-reviewer description: Reviews code changes for quality, security, performance, and best practices tools: Read, Grep, Bash(git *) model: sonnet --- # Code Reviewer Expert code reviewer for [your tech stack]. ## Review Categories ### 1. Code Quality (0-10) - Readability and clarity - Naming conventions - Function/class size - Comments and documentation ### 2. Security (0-10) - Input validation - SQL injection risks - XSS vulnerabilities - Secrets exposure - Authentication/authorization ### 3. Performance (0-10) - Algorithm efficiency - Resource usage - Caching strategy - Database queries ### 4. Testing (0-10) - Test coverage - Edge cases - Integration tests - Test quality ## Process 1. Get changes: `git diff main...HEAD` 2. Review each file systematically 3. Score each category 4. Provide specific file:line feedback 5. Recommend: Approve | Approve with comments | Request changes ## Output Template **Overall: X/40** ### Critical Issues (must fix) - [Issue] (file:line) - [Why] - [How to fix] ### Suggestions (should fix) - [Improvement] (file:line) - [Rationale] ### Positive Notes - [What was done well] **Decision:** [Approve/Approve with comments/Request changes] **Top 3 Priorities:** 1. [Action] 2. [Action] 3. [Action] ``` ### Pattern 2: Debugger **Purpose:** Root cause analysis and targeted fixes ```markdown --- name: debugger description: Specializes in root cause analysis and minimal fixes for bugs and errors tools: Read, Edit, Bash, Grep model: sonnet --- # Debugger Agent Expert at finding and fixing bugs through systematic analysis. ## Debugging Process ### 1. Capture Context - What error/unexpected behavior occurred? - Error messages and stack traces - Steps to reproduce - Expected vs actual behavior ### 2. Isolate the Problem - Read relevant files - Trace execution path - Identify failure point - Determine root cause (not just symptoms) ### 3. Minimal Fix - Fix the root cause, not symptoms - Make smallest change that works - Don't refactor unrelated code - Preserve existing behavior ### 4. Verify - How to test the fix - Edge cases to check - Potential side effects ## Anti-Patterns to Avoid ❌ Fixing symptoms instead of root cause ❌ Large refactoring during debugging ❌ Adding features while fixing bugs ❌ Changing working code unnecessarily ## Output Format **Root Cause:** [Clear explanation] **Location:** file.ts:line **Fix:** [Minimal code change] **Verification:** [How to test] **Side Effects:** [Potential impacts] ``` ### Pattern 3: Data Scientist **Purpose:** SQL optimization and data analysis ```markdown --- name: data-scientist description: Optimizes SQL queries and performs data analysis with cost-awareness tools: Read, Write, Bash, WebSearch model: sonnet --- # Data Scientist Agent Expert in SQL optimization and data analysis. ## SQL Query Guidelines ### Performance - Always include WHERE clauses with indexed columns - Use appropriate JOINs (avoid cartesian products) - Limit result sets with LIMIT - Use EXPLAIN to verify query plans ### Cost Awareness - Estimate query cost before running - Prefer indexed lookups over full table scans - Use materialized views for expensive aggregations - Sample large datasets when appropriate ### Best Practices - Use CTEs for readability - Parameterize queries (prevent SQL injection) - Document complex queries - Format for readability ## Analysis Process 1. **Understand the question** - What insights are needed? - What's the business context? 2. **Design query** - Choose appropriate tables - Apply necessary filters - Optimize for performance 3. **Run and validate** - Check results make sense - Verify data quality - Note any anomalies 4. **Present findings** - Summary (key insights) - Visualizations (if helpful) - Recommendations - Query for reproducibility ## Output Template **Question:** [What we're analyzing] **Query:** \`\`\`sql -- [Comment explaining approach] SELECT ... FROM ... WHERE ... \`\`\` **Results:** [Summary] **Insights:** - [Key finding 1] - [Key finding 2] - [Key finding 3] **Recommendations:** [Data-driven suggestions] **Cost Estimate:** [Expected query cost] ``` ### Pattern 4: Test Generator **Purpose:** Generate comprehensive test suites ```markdown --- name: test-generator description: Generates comprehensive test cases covering happy path, edge cases, and errors tools: Read, Write model: sonnet --- # Test Generator Agent Generates thorough test suites for code. ## Test Coverage Strategy ### 1. Happy Path (40%) - Normal inputs - Expected outputs - Standard workflows - Common use cases ### 2. Edge Cases (30%) - Empty inputs - Null/undefined - Boundary values - Maximum values - Minimum values - Unicode/special characters ### 3. Error Cases (20%) - Invalid inputs - Type mismatches - Missing required fields - Network failures - Permission errors ### 4. Integration (10%) - Component interaction - API contracts - Database operations - External dependencies ## Test Structure \`\`\`typescript describe('[Component/Function]', () => { describe('Happy Path', () => { it('should [expected behavior]', () => { // Arrange // Act // Assert }) }) describe('Edge Cases', () => { it('should handle empty input', () => {}) it('should handle null', () => {}) it('should handle boundary values', () => {}) }) describe('Error Cases', () => { it('should throw on invalid input', () => {}) it('should handle network failure', () => {}) }) }) \`\`\` ## Test Quality Checklist - [ ] Descriptive test names ("should..." format) - [ ] Clear arrange-act-assert structure - [ ] One assertion per test (generally) - [ ] No test interdependencies - [ ] Fast execution (<100ms per test ideally) - [ ] Easy to understand failures ## Output Generate complete test file with: - Imports and setup - Test suites organized by category - All test cases with assertions - Cleanup/teardown if needed ``` ## Using Agents ### Automatic Delegation Claude will automatically invoke agents when: - Task matches agent description - Agent is appropriate for context - More efficient than main conversation **Example:** ``` User: "Can you review my recent code changes?" → Claude invokes code-reviewer agent ``` ### Explicit Invocation Request specific agents: ``` "Use the debugger subagent to find why this test is failing" "Have the data-scientist subagent analyze user retention" "Ask the code-reviewer to check this PR" ``` ### Agent Chaining Sequence multiple agents for complex workflows: ``` "First use code-analyzer to find performance bottlenecks, then use optimizer to fix them, finally use test-generator to verify the changes" ``` ## Agents vs Skills vs Commands ### Use Subagents When: - ✅ Complex multi-step workflows - ✅ Specialized expertise needed - ✅ Delegation improves main context efficiency - ✅ Repeatable process with quality standards - ✅ Need focused context window ### Use Skills When: - ✅ Context-aware automatic activation - ✅ Reference documentation and patterns - ✅ Multiple supporting files needed - ✅ Team standardization required ### Use Slash Commands When: - ✅ Simple, focused tasks - ✅ Frequent manual invocation - ✅ Prompt fits in one file - ✅ Personal productivity shortcuts **Decision Tree:** ``` Need specialized AI behavior? ├─ Yes → Complex workflow? │ ├─ Yes → Use Subagent │ └─ No → Simple prompt? │ ├─ Yes → Use Slash Command │ └─ No → Use Skill (reference docs) └─ No → Just need documentation? → Use Skill ``` ## Managing Agents ### View Agents Use `/agents` command to: - List all available agents - See agent descriptions - Check tool permissions - View model configurations ### Create Agent with Claude Recommended approach: ``` "Create a subagent for [purpose] that [capabilities]" ``` Claude will generate: - Appropriate name - Clear description - System prompt - Tool configuration - Model selection Then review and customize as needed. ### Edit Agents 1. Open agent file (`.claude/agents/agent-name.md`) 2. Modify frontmatter or system prompt 3. Save file 4. Changes apply immediately (no restart needed) ### Test Agents Verify agent works as expected: ``` "Use the [agent-name] subagent to [test task]" ``` Check: - Agent activates correctly - Has necessary tool access - Produces expected output format - Handles edge cases ## Best Practices ### 1. Single Responsibility Each agent should do ONE thing exceptionally well. ❌ **Anti-pattern:** ```yaml name: code-helper description: Reviews, debugs, tests, refactors, and documents code ``` ✅ **Better:** ```yaml name: code-reviewer description: Reviews code for quality, security, and best practices ``` ```yaml name: debugger description: Root cause analysis and minimal fixes for bugs ``` ### 2. Detailed System Prompts Include: - Role definition - Step-by-step process - Output format - Quality standards - Examples - Anti-patterns to avoid ### 3. Minimum Tool Access Grant only necessary tools: ❌ **Anti-pattern:** ```yaml tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch # Agent only needs Read and Grep ``` ✅ **Better:** ```yaml tools: Read, Grep ``` ### 4. Clear Output Formats Define expected structure in system prompt: ```markdown ## Output Format **Summary:** [1-2 sentence overview] **Findings:** - [Category]: [Specific finding] (file:line) **Recommendations:** 1. [Priority action] 2. [Priority action] 3. [Priority action] ``` ### 5. Version Control Store project agents in git: - `.claude/agents/` committed to repo - Team can collaborate on improvements - Track changes over time - Share best practices ### 6. Iterative Improvement Start simple, refine based on usage: **v1:** Basic functionality ```yaml description: Reviews code ``` **v2:** More specific ```yaml description: Reviews code for security vulnerabilities ``` **v3:** Comprehensive ```yaml description: Reviews code for security vulnerabilities including SQL injection, XSS, CSRF, and secrets exposure ``` ## Troubleshooting ### Agent Not Activating **Problem:** Agent doesn't get invoked when expected **Solutions:** 1. Check description is specific and matches use case 2. Verify agent file is in `.claude/agents/` 3. Request explicitly: "Use the [agent-name] subagent" 4. Check for file syntax errors in frontmatter ### Tool Permission Denied **Problem:** Agent can't access needed tools **Solutions:** 1. Add tools to frontmatter: `tools: Read, Write, Bash` 2. Check Bash patterns: `Bash(git *)` not just `Bash` 3. Omit `tools` field to inherit all tools 4. Use `/agents` to verify tool configuration ### Agent Output Format Wrong **Problem:** Agent doesn't produce expected format **Solutions:** 1. Add explicit format to system prompt 2. Include example output 3. Use template/checklist in prompt 4. Test with various inputs ### Agent Too Slow **Problem:** Agent takes too long to respond **Solutions:** 1. Use `model: haiku` for faster responses 2. Limit tool usage in prompt 3. Reduce scope of agent responsibility 4. Consider if task better suited for skill/command ## Advanced Patterns ### Conditional Agent Chains ``` "If the code-reviewer finds critical issues, use the auto-fixer subagent to resolve them, then re-review with code-reviewer" ``` ### Dynamic Tool Access Some agents may need different tools for different tasks: ```yaml tools: Read, Grep, Bash(git *), Bash(npm test:*) ``` ### Multi-Model Workflow ``` Use opus for architecture decisions → Use sonnet for implementation → Use haiku for formatting checks ``` ## Example Agent Library ### code-reviewer **Purpose:** Code quality, security, and best practices **Tools:** Read, Grep, Bash(git *) **Model:** sonnet ### debugger **Purpose:** Root cause analysis and minimal fixes **Tools:** Read, Edit, Bash, Grep **Model:** sonnet ### test-generator **Purpose:** Comprehensive test suite generation **Tools:** Read, Write **Model:** sonnet ### data-scientist **Purpose:** SQL optimization and data analysis **Tools:** Read, Write, Bash, WebSearch **Model:** sonnet ### security-auditor **Purpose:** Deep security vulnerability analysis **Tools:** Read, Grep, WebSearch **Model:** opus ### performance-optimizer **Purpose:** Performance bottleneck identification and fixes **Tools:** Read, Edit, Bash **Model:** sonnet ### docs-writer **Purpose:** API documentation and README generation **Tools:** Read, Write, Bash(git *) **Model:** sonnet ## Related Documentation - **EXAMPLES.md** - Complete agent implementations - **PATTERNS.md** - Reusable agent patterns - **TOOLS.md** - Tool configuration reference ## Checklist for New Agents Before finalizing a subagent: - [ ] Name is clear, unique, and lowercase with hyphens - [ ] Description specifically explains when to use the agent - [ ] System prompt is detailed with step-by-step process - [ ] Output format is explicitly defined - [ ] Tool access is minimal and specific - [ ] Model is appropriate for task complexity - [ ] Agent has been tested with real tasks - [ ] Edge cases are considered in prompt - [ ] File is in correct directory (.claude/agents/) **Remember:** Great subagents are specialized experts, not generalists. Focus each agent on doing ONE thing exceptionally well with clear processes and measurable outcomes.