agent-development

What this skill does

# Agent Development Skill

Guide to creating effective autonomous agents for Claude Code plugins.

## When to Use

Activate when:
- Creating new agents
- User asks about agent structure
- Designing specialized automation
- Questions about agent capabilities

## What Are Agents?

Agents are **autonomous specialized workers** that:
- Perform focused tasks independently
- Have specific domain expertise
- Work in background with limited tools
- Return results when complete

**When to use agents**:
- Focused analysis needed (code review, validation)
- Background processing (report generation)
- Specialized expertise (performance analysis, security audit)
- User wants autonomous work

**When NOT to use agents**:
- User needs interactive control → Use Commands
- Just providing guidance → Use Skills
- Event-driven automation → Use Hooks

## Agent Structure

### File Location

```
plugin-name/
└── agents/
    ├── analyzer.md
    ├── validator.md
    └── reviewer.md
```

### Basic Agent Format

```yaml
---
name: agent-name
description: Clear description of agent's specialized purpose
color: blue|green|orange|cyan|purple
tools: [Read, Grep, Glob]
---

# Agent Name

Detailed description of agent's role and expertise.

## Your Role

[Clear role definition for the agent]

## Process

[Step-by-step workflow the agent follows]

## Analysis

[What the agent analyzes and how]

## Output Format

[Expected output structure]

## Examples

[Concrete examples of agent's work]
```

## YAML Frontmatter

### Required Fields

```yaml
---
name: agent-name         # Must match filename
description: Brief desc  # What agent does
color: blue             # Visual identifier
tools: [Read, Grep]     # Available tools
---
```

### Agent Colors

**Purpose**: Visual identification in UI

**Available colors**:
- `blue` - General purpose, analysis
- `green` - Testing, validation, success-focused
- `orange` - Performance, optimization, warnings
- `cyan` - Style, formatting, documentation
- `purple` - Architecture, design, planning

**Examples**:
```yaml
color: blue      # code-analyzer
color: green     # test-validator
color: orange    # performance-reviewer
color: cyan      # style-checker
color: purple    # architecture-reviewer
```

### Tool Selection

**Read-only agents** (analysis, reporting):
```yaml
tools: [Read, Grep, Glob]
```

**Analysis with execution**:
```yaml
tools: [Read, Grep, Glob, Bash]
```

**Implementation agents** (rare, usually use commands instead):
```yaml
tools: [Read, Grep, Glob, Bash, Edit, Write]
```

**Available tools**:
- `Read` - Read files
- `Grep` - Search content
- `Glob` - Find files by pattern
- `Bash` - Execute commands
- `Edit` - Modify existing files
- `Write` - Create new files
- `Task` - Spawn subagents (advanced)

## Agent Patterns

### Analysis Agent

**Purpose**: Examine code and generate reports

```yaml
---
name: code-analyzer
description: Analyzes code quality and identifies issues
color: blue
tools: [Read, Grep, Glob]
---

# Code Analyzer Agent

Specialized agent for code quality analysis.

## Your Role

Analyze code for:
1. Code quality issues
2. Potential bugs
3. Anti-patterns
4. Improvement opportunities

## Process

1. **Find relevant files**:
   - Use Glob to find source files
   - Filter by language/framework

2. **Analyze each file**:
   - Read file contents
   - Check for common issues
   - Identify patterns

3. **Generate report**:
   - Categorize issues by severity
   - Provide specific locations
   - Suggest fixes

## Analysis

### Code Quality Checks

**Look for**:
- Overly complex functions (>50 lines)
- Deep nesting (>3 levels)
- Duplicate code
- Missing error handling
- Poor naming

### Example Analysis

For each issue found:
```markdown
### Issue: Complex Function
Location: src/utils.ts:45
Severity: Medium

Function `processData` is 120 lines.
Recommendation: Break into smaller functions
```

## Output Format

```markdown
# Code Analysis Report

## Summary
- Files analyzed: 25
- Issues found: 12
- Critical: 2
- Warnings: 10

## Critical Issues

### Issue 1: [Description]
Location: [file:line]
Problem: [What's wrong]
Fix: [How to fix]

## Warnings

[Similar format]

## Recommendations

1. [High-level suggestion]
2. [Another suggestion]
```
```

### Validation Agent

**Purpose**: Verify correctness and completeness

```yaml
---
name: spec-validator
description: Validates API specifications for completeness
color: green
tools: [Read, Grep, Glob, Bash]
---

# Spec Validator Agent

Validates OpenAPI/AsyncAPI specifications.

## Your Role

Ensure API specs are:
1. Syntactically valid
2. Complete and consistent
3. Following best practices
4. Ready for implementation

## Process

1. **Find spec files**:
   - Glob for `*.openapi.{yml,yaml,json}`
   - Glob for `*.asyncapi.{yml,yaml,json}`

2. **Validate syntax**:
   - Use validator tool (Bash)
   - Check YAML/JSON parsing
   - Verify spec version

3. **Check completeness**:
   - All endpoints documented
   - Request/response schemas defined
   - Authentication specified
   - Error responses included

4. **Verify consistency**:
   - Schema references valid
   - No duplicate operations
   - Consistent naming

## Validation Checks

### Syntax
- [ ] Valid YAML/JSON
- [ ] Correct OpenAPI/AsyncAPI version
- [ ] No parsing errors

### Completeness
- [ ] All paths have descriptions
- [ ] All parameters documented
- [ ] All responses defined
- [ ] Schemas have examples

### Best Practices
- [ ] Consistent naming
- [ ] Proper use of references
- [ ] Security schemes defined
- [ ] Version specified

## Output Format

```markdown
# Spec Validation Report

## File: api.openapi.yml

### Status: ⚠️ WARNINGS

### Syntax ✓
- Valid YAML
- OpenAPI 3.0.0
- No parsing errors

### Completeness Issues

#### Missing Response Schemas
- GET /users - 404 response not defined
- POST /users - 400 response missing

#### Missing Descriptions
- Parameter `limit` in GET /users
- Schema `UserResponse`

### Best Practice Violations

#### Inconsistent Naming
- `/users` vs `/user-orders` (use consistent pluralization)

## Recommendations

1. Add error response definitions (400, 404, 500)
2. Document all parameters and schemas
3. Use consistent naming convention
4. Add examples for complex schemas

## Next Steps

Fix the issues above, then run:
/spec:validate --strict
```
```

### Review Agent

**Purpose**: Provide expert feedback

```yaml
---
name: security-reviewer
description: Reviews code for security vulnerabilities
color: orange
tools: [Read, Grep, Glob]
---

# Security Reviewer Agent

Specialized security audit agent.

## Your Role

Identify security vulnerabilities:
1. Injection attacks (SQL, XSS, Command)
2. Authentication/authorization issues
3. Insecure dependencies
4. Data exposure
5. Cryptographic weaknesses

## Process

1. **Scan for vulnerability patterns**:
   - Grep for dangerous functions
   - Check input validation
   - Review authentication logic

2. **Analyze each finding**:
   - Determine severity
   - Assess exploitability
   - Suggest remediation

3. **Generate security report**:
   - Prioritize by risk
   - Provide specific fixes
   - Include references

## Detection Patterns

### SQL Injection
```
Search for:
- String concatenation in SQL queries
- Unparameterized queries
- Direct user input in SQL
```

### XSS
```
Search for:
- Unescaped user input in HTML
- innerHTML with dynamic content
- Unsafe DOM manipulation
```

### Command Injection
```
Search for:
- Shell commands with user input
- Unvalidated file paths
- Process execution with dynamic args
```

## Output Format

```markdown
# Security Review Report

## Summary
- Critical: 2
- High: 5
- Medium: 8
- Low: 3

## Critical Vulnerabilities

### SQL Injection in User Query
**Location**: src/database.ts:45
**Severity**: CRITICAL
**CWE**: CWE-89

**Vulnerable Code**:
```typescript
const query = `SELECT * FROM users WHERE id = ${userId}`;
db.execute(query);
```

**Exploitation**:
Attacker can inject SQL: `1 OR 1=1--`

**Fix**:
```typescript
con