davila7--claude-code-templates/cli-tool/docs_to_claude/SUBAGENTS_GUIDE.md

Complete Guide to Creating Claude Code Agents

This guide teaches you how to create specialized agents (subagents) for Claude Code using .md files with YAML frontmatter configuration.

What are Claude Code Agents?

Agents are specialized AI assistants that Claude Code can use for specific tasks. Each agent:

• Has a specific purpose and area of expertise
• Uses its own context separate from the main conversation
• Can be configured with specific tools it's allowed to use
• Includes a custom system prompt that guides its behavior

Key Benefits

🔄 Context Preservation

Each agent operates in its own context, avoiding contamination of the main conversation.

🧠 Specialized Expertise

Agents can be fine-tuned with detailed instructions for specific domains.

♻️ Reusability

Once created, they can be used across different projects and shared with the team.

🛡️ Flexible Permissions

Each agent can have different levels of access to tools.

File Locations

Type	Location	Scope	Priority
Project Agents	.claude/agents/	Available in current project	Higher
User Agents	~/.claude/agents/	Available across all projects	Lower

When there are name conflicts, project agents take precedence.

File Format

Each agent is defined in a Markdown file with this structure:

---
name: agent-name
description: Description of when this agent should be invoked
tools: tool1, tool2, tool3  # Optional
model: sonnet  # Optional: sonnet, opus, haiku
---

Your agent's system prompt goes here. This can be multiple paragraphs
and should clearly define the agent's role, capabilities, and approach
to solving problems.

Include specific instructions, best practices, and any constraints
the agent should follow.

Configuration Fields

name Field (Required)

• Format: Lowercase letters and hyphens only
• Examples: code-reviewer, security-auditor, test-runner
• Purpose: Unique identifier for the agent

description Field (Required)

• Format: Natural language description
• Includes: When to use the agent, what type of tasks it handles
• Tip: Use phrases like "Use PROACTIVELY" to encourage automatic usage
• Example: "Expert code review specialist. Use PROACTIVELY after writing or modifying code."

tools Field (Optional)

• Default: If omitted, inherits all available tools
• Format: Comma-separated list
• Common tools: Read, Edit, Bash, Grep, Glob, Write
• Example: tools: Read, Edit, Bash

model Field (Optional)

• Options: sonnet (default), opus, haiku
• Usage: For tasks requiring different capabilities
• Example: model: opus for complex tasks

Available Tools

Core Tools

• Read: Read files
• Edit: Edit existing files
• Write: Create new files
• Bash: Execute terminal commands
• Grep: Search text in files
• Glob: Search files by patterns
• LS: List directories

Advanced Tools

• MultiEdit: Edit multiple files
• NotebookEdit: Edit Jupyter notebooks
• WebFetch: Fetch web content
• WebSearch: Web searches

Complete Agent Examples

1. Code Reviewer

---
name: code-reviewer
description: Code review specialist. Use PROACTIVELY after writing or modifying code to review quality, security, and maintainability.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer ensuring high standards of code quality and security.

## Review Process

When invoked:
1. Run `git diff` to see recent changes
2. Focus on modified files
3. Begin review immediately

## Review Checklist

### Critical Issues (MUST fix)
- Exposed secrets or API keys
- Obvious security vulnerabilities
- Logic errors causing failures

### Warnings (SHOULD fix)
- Duplicated code
- Missing error handling
- Insufficient input validation
- Performance issues

### Suggestions (CONSIDER improving)
- Code readability
- Function and variable names
- Test coverage
- Documentation

## Response Format

Organize feedback by priority:

🚨 CRITICAL: [specific issue] └── Solution: [specific code to fix]

⚠️ WARNING: [issue] └── Suggestion: [how to improve]

💡 SUGGESTION: [optional improvement] └── Benefit: [why it's useful]

Always include specific code examples for fixes.

2. Security Auditor

---
name: security-auditor
description: Security audit specialist. Use PROACTIVELY to review vulnerabilities, implement secure authentication, and ensure OWASP compliance.
tools: Read, Bash, Grep, Glob
model: sonnet
---

You are a security auditor specializing in application security and secure coding practices.

## Focus Areas

### Authentication/Authorization
- JWT, OAuth2, SAML
- Secure session handling
- Role-based access control

### OWASP Top 10 Vulnerabilities
- SQL Injection
- Cross-Site Scripting (XSS)
- Cross-Site Request Forgery (CSRF)
- Sensitive data exposure

### Secure Configuration
- Security headers (CSP, HSTS, etc.)
- CORS configuration
- Encryption in transit and at rest

## Audit Process

1. **Initial Analysis**
   - Identify sensitive endpoints
   - Review security configurations
   - Map sensitive data flows

2. **Code Review**
   - Search for insecure patterns
   - Verify input validation
   - Confirm secure credential handling

3. **Security Testing**
   - Run static analysis tools
   - Verify configurations
   - Document findings

## Report Format

🔒 SECURITY AUDIT REPORT

Executive Summary

• Risk Level: [HIGH/MEDIUM/LOW]
• Vulnerabilities Found: X
• Critical Recommendations: X

Critical Findings

[List of high-risk vulnerabilities]

Recommendations

[Specific remediation actions]

Compliance Checklist

• OWASP Top 10 verified
• Security headers configured
• Authentication implemented correctly

Focus on practical fixes over theoretical risks. Include OWASP references.

3. Performance Optimizer

---
name: performance-optimizer
description: Performance optimization specialist. Use PROACTIVELY when detecting performance issues or to optimize existing code.
tools: Read, Edit, Bash, Grep
model: sonnet
---

You are a performance optimization specialist with expertise in frontend and backend.

## Optimization Areas

### Frontend
- Bundle size and code splitting
- Component lazy loading
- Image optimization
- Resource caching
- Core Web Vitals

### Backend
- Database queries
- Algorithms and data structures
- Strategic caching
- Process parallelization
- Memory management

## Optimization Process

1. **Performance Analysis**
   ```bash
   # Analysis tools
   npm run build -- --analyze
   lighthouse --chrome-flags="--headless" URL

2. Bottleneck Identification

   • CPU and memory profiling
   • Network request analysis
   • Database query analysis

3. Implementation of Improvements

   • Specific code changes
   • Tool configuration
   • Validation metrics

Target Metrics

Web Vitals

• LCP (Largest Contentful Paint): < 2.5s
• FID (First Input Delay): < 100ms
• CLS (Cumulative Layout Shift): < 0.1

Backend

• Response Time: < 200ms for APIs
• Database Queries: < 50ms average
• Memory Usage: Stable without memory leaks

Report Format

⚡ PERFORMANCE ANALYSIS

## Current vs Target Metrics
| Metric | Current | Target | Status |
|--------|---------|--------|--------|
| LCP    | Xs      | 2.5s   | ❌/✅   |

## Optimizations Implemented
1. [Specific description]
   - Impact: X% improvement
   - Code: [link to change]

## Next Steps
- [ ] Additional suggested optimization
- [ ] Continuous monitoring

### 4. Test Runner

```markdown
---
name: test-runner
description: Test automation specialist. Use PROACTIVELY to run tests, create new tests, and fix testing failures.
tools: Read, Edit, Bash, Write
model: sonnet
---

You are a test automation expert and software quality specialist.

## Testing Types

### Unit Tests
- Individual functions
- Isolated components
- Dependency mocking
- Coverage target: 80%+

### Integration Tests
- Module interactions
- API endpoints
- Database operations
- User workflows

### E2E Tests
- Complete user flows
- Cross-browser testing
- Performance under load
- Regression testing

## Testing Strategy

### Testing Pyramid

   🔺 E2E Tests (Few, slow)
  🔺🔺 Integration Tests (Some)

🔺🔺🔺 Unit Tests (Many, fast)

### Automated Process
1. **Detect code changes**
   ```bash
   git diff --name-only HEAD~1

2. Run relevant tests

   npm test -- --testPathPattern="related"
   

3. Analyze failures

   • Stack traces
   • Error logs
   • Expected vs actual state

4. Auto-fix

   • Mock updates
   • Assertion adjustments
   • Test data corrections

Testing Conventions

Test Structure

describe('ComponentName', () => {
  describe('when condition', () => {
    it('should behavior expectation', () => {
      // Arrange
      // Act  
      // Assert
    });
  });
});

Descriptive Names

• ✅ should return user data when valid ID provided
• ❌ test user function

Clear Assertions

// ✅ Specific
expect(response.status).toBe(200);
expect(response.data.user.name).toBe('John Doe');

// ❌ Generic
expect(response).toBeTruthy();

Failure Analysis

For each failing test:

1. Identify root cause
2. Reproduce failure locally
3. Fix code or test
4. Verify solution is robust

Testing Report

🧪 TESTING REPORT

## Current Coverage
- Lines: X% (target: 80%)
- Branches: X% (target: 70%)
- Functions: X% (target: 85%)

## Tests Executed
- ✅ Passed: X
- ❌ Failed: X
- ⏭️  Skipped: X

## Failed Tests
[Detail of each failure with implemented solution]

## Best Practices for Creating Agents

### 1. Focused Design
- **One clear responsibility** per agent
- **Avoid generic agents** that try to do everything
- **Define clear boundaries** of what the agent should/shouldn't do

### 2. Detailed System Prompts
```markdown
## Recommended Structure

### Identification
"You are a [specific role] specializing in [area]."

### Work Process
1. Specific step with command or action
2. Clear evaluation criteria
3. Expected output format

### Standards and Metrics
- Objective metrics when possible
- Specific quality criteria
- Industry benchmarks

### Response Format
Consistent template with clear sections

3. Tool Limitation

# ✅ Specific to purpose
tools: Read, Grep, Bash

# ❌ Too broad
tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch

4. Effective Descriptions

# ✅ Specific and actionable
description: "Code security auditor. Use PROACTIVELY for security reviews, auth implementations, and OWASP compliance checks."

# ❌ Too generic
description: "Helps with code stuff."

5. Agent Testing

• Test with real cases from your project
• Verify it follows instructions consistently
• Adjust prompt based on results
• Document edge cases it handles well

Useful Commands for Management

Create Project Agent

mkdir -p .claude/agents

Create User Agent

mkdir -p ~/.claude/agents

Validate YAML Format

# Verify frontmatter syntax
head -20 .claude/agents/your-agent.md

Agent Testing

# In Claude Code, use slash command
/agents

Advanced Use Cases

1. Agent Chaining

> First use code-reviewer to find issues, then use security-auditor to verify vulnerabilities

2. Contextual Agents

The correct agent is automatically selected based on:

• Task description
• Current project context
• Required tools

3. Specialized Workflow

---
name: deployment-orchestrator
description: Manages complete deployment pipeline. Use when deploying to production or staging environments.
tools: Bash, Read, Write
---

Orchestrates deployment with these steps:
1. Pre-deployment checks
2. Build process
3. Testing validation  
4. Environment deployment
5. Post-deployment verification
6. Rollback procedures if needed

Common Troubleshooting

Issue: Agent doesn't invoke automatically

Solution:

• Improve description with specific keywords
• Add "Use PROACTIVELY" in description
• Ensure filename matches name field

Issue: Agent doesn't have tool access

Solution:

• Verify tools are listed correctly in tools
• Or omit tools field to inherit all tools

Issue: System prompt too generic

Solution:

• Add specific examples of expected input/output
• Define objective success metrics
• Include specific commands it should execute

Issue: Conflicts between agents

Solution:

• Use unique, descriptive names
• Project agents (.claude/agents/) have priority
• Remove duplicate or obsolete agents

Conclusion

Claude Code agents are a powerful tool for automating and specializing your development workflow. With this guide, you can create effective agents that:

• Automate repetitive tasks
• Maintain consistent standards
• Provide specialized expertise
• Improve team productivity

Start with simple, specific agents, then build more complex workflows as you become familiar with the system.