---
name: Claude Code Subagent Specialist
description: Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, descriptions, and performance. Use when improving existing subagents, debugging activation issues, or optimizing delegation patterns. NOT for initial creation - use /agents command first.
---

# Claude Code Subagent Refinement & Troubleshooting

## When to Use This Skill

Use this skill when:
- Refining existing subagent prompts for better performance
- Troubleshooting why a subagent isn't activating
- Optimizing tool access and permissions
- Improving subagent descriptions for better delegation
- Debugging context management issues
- Testing and validating subagent behavior
- Converting ad-hoc workflows to reusable subagents

Do NOT use this skill for:
- **Initial creation** - Use `/agents` command instead (it provides interactive UI)
- Creating slash commands (use claude-code-slash-commands skill)
- General Claude Code troubleshooting

**Important**: Always start with `/agents` to create subagents. Use this skill to refine them afterward.

## Quick Reference: Subagent Structure

```yaml
---
name: agent-name              # Lowercase, kebab-case identifier
description: When to use      # Triggers automatic delegation
tools: Tool1, Tool2          # Optional: omit to inherit all
model: sonnet                # Optional: sonnet/opus/haiku/inherit
---

System prompt defining role, capabilities, and behavior.
Include specific instructions, constraints, and examples.
```

**File Locations**:
- Project: `.claude/agents/` (highest priority)
- User: `~/.claude/agents/` (shared across projects)
- Plugin: `agents/` in plugin directory

## Common Problems & Solutions

### Problem 1: Subagent Never Activates

**Symptoms**: Claude doesn't delegate to your subagent

**Diagnose**:
```yaml
# Check your description field
---
description: Helper agent  # ❌ Too vague
---
```

**Fix - Make Description Specific**:
```yaml
# Before (vague)
---
description: Helps with security
---

# After (specific)
---
description: Analyze code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY when reviewing code for security issues.
---
```

**Best Practices for Descriptions**:
- Include specific trigger words and scenarios
- Add "use PROACTIVELY" or "MUST BE USED" for automatic activation
- Mention the domain/context clearly
- List key capabilities or checks

### Problem 2: Subagent Has Wrong Tools

**Symptoms**: Subagent can't complete tasks or has too many permissions

**Diagnose**:
```bash
# Check current tool configuration
cat .claude/agents/my-agent.md | grep "tools:"
```

**Fix - Whitelist Specific Tools**:
```yaml
# Inherits all tools (may be too permissive)
---
name: security-analyzer
description: Security analysis
---

# Restricted to read-only tools (better)
---
name: security-analyzer
description: Security analysis
tools: Read, Grep, Glob
---
```

**Tool Access Strategies**:

**1. Inherit All (Default)**:
```yaml
# Omit 'tools' field entirely
---
name: general-helper
description: General assistance
---
```
Use when: Agent needs full flexibility

**2. Read-Only Access**:
```yaml
---
tools: Read, Grep, Glob, Bash(git log:*), Bash(git diff:*)
---
```
Use when: Analysis, review, documentation

**3. Specific Permissions**:
```yaml
---
tools: Read, Write, Edit, Bash(npm test:*)
---
```
Use when: Implementation with validation

**4. No File Access**:
```yaml
---
tools: WebFetch, WebSearch, Bash
---
```
Use when: Research, external data gathering

### Problem 3: Poor Quality Output

**Symptoms**: Subagent completes tasks but results are inconsistent or low-quality

**Diagnose**: Check system prompt specificity

**Fix - Enhance System Prompt**:

```markdown
# Before (vague)
---
name: code-reviewer
---

You review code for issues.
```

```markdown
# After (specific)
---
name: code-reviewer
---

You are a senior code reviewer specializing in production-ready code quality.

## Your Responsibilities

1. **Logic & Correctness**
   - Verify algorithm correctness
   - Check edge case handling
   - Validate error conditions

2. **Code Quality**
   - Ensure single responsibility principle
   - Check for code duplication (DRY)
   - Verify meaningful naming

3. **Security**
   - Identify injection vulnerabilities
   - Check authentication/authorization
   - Flag hardcoded secrets

4. **Performance**
   - Spot O(n²) or worse algorithms
   - Identify unnecessary loops
   - Check resource cleanup

## Output Format

For each issue found:
- **Severity**: Critical/High/Medium/Low
- **Location**: file:line
- **Issue**: Clear description
- **Fix**: Specific code example

## Constraints

- Only report actionable issues
- Provide code examples for fixes
- Focus on high-impact problems first
- No nitpicking style issues unless severe
```

**System Prompt Best Practices**:
- Define role and expertise level
- List specific responsibilities
- Include output format requirements
- Add examples of good/bad cases
- Specify constraints and boundaries
- Use headings for scannability

### Problem 4: Context Pollution

**Symptoms**: Main conversation gets cluttered with subagent details

**Understand**: Subagents have isolated context windows - only their final output returns

**Fix - Structure Output Properly**:

```markdown
# System prompt guidance
---
name: research-agent
---

Research [topic] and return ONLY:
1. Key findings (3-5 bullet points)
2. Relevant URLs
3. Recommendation

Do NOT include:
- Full article text
- Research methodology
- Intermediate thoughts
```

**Best Practices**:
- Explicitly tell subagent what to return
- Request summaries, not full details
- Have subagent filter before returning
- Use structured output formats

### Problem 5: Activation Too Broad/Narrow

**Symptoms**: Subagent activates for wrong tasks OR misses relevant tasks

**Diagnose - Test Trigger Scenarios**:

```markdown
# Test cases for a "security-analyzer" subagent

Should Activate:
- "Review this auth code for vulnerabilities"
- "Check if we're handling passwords securely"
- "Scan for SQL injection risks"

Should NOT Activate:
- "Write unit tests" (different concern)
- "Refactor this function" (not security-focused)
- "Add logging" (different task)
```

**Fix - Refine Description**:

```yaml
# Too narrow
---
description: Checks for SQL injection only
---

# Too broad
---
description: Helps with code
---

# Just right
---
description: Analyze code for security vulnerabilities including SQL injection, XSS, CSRF, authentication issues, and secrets exposure. Use when reviewing code for security concerns or compliance requirements.
---
```

### Problem 6: Model Selection Issues

**Symptoms**: Subagent too slow/expensive OR too simple for task

**Fix - Choose Right Model**:

```yaml
# Fast, simple tasks (formatting, linting)
---
model: haiku
---

# Complex reasoning (architecture, design)
---
model: opus
---

# Balanced (most cases)
---
model: sonnet
---

# Same as main conversation
---
model: inherit
---
```

**Model Selection Guide**:

| Model | Use For | Avoid For |
|-------|---------|-----------|
| haiku | Simple transforms, quick checks | Complex reasoning, creativity |
| sonnet | General tasks, balanced quality | When opus is specifically needed |
| opus | Complex architecture, creative work | Simple/repetitive tasks (cost) |
| inherit | Task complexity matches main thread | When you need different capability |

## Optimization Patterns

### Pattern 1: Role-Based Pipeline

Create specialized agents for each workflow stage:

```yaml
# 1. Spec Agent
---
name: product-spec-writer
description: Create detailed product specifications from user requirements
tools: Read, Write, WebSearch
model: opus
---

You convert user requirements into detailed product specs.

[Detailed prompt...]
```

```yaml
# 2. Architect Agent
---
name: solution-architect
description: Design system architecture from product specs
tools: Read, Write, Grep, Glob
model: opus
---

You design scalable system architectures.

[Detailed prompt...]
```

```yaml
# 3. Implementer Agent
---
name: code-implementer
description: Implement features from architectural designs
tools: Read, Write, Edit, Bash(npm test:*)
model: sonnet
---

You implement features following architectural guidelines.

[Detailed prompt...]
```

**Usage**: Chain with hooks or explicit handoffs

### Pattern 2: Domain Specialists

```yaml
# Frontend Specialist
---
name: frontend-specialist
description: React/TypeScript UI development and component design. Use PROACTIVELY for frontend work.
tools: Read, Write, Edit, Grep, Bash(npm:*)
---

You are a React/TypeScript expert specializing in modern frontend development.

## Tech Stack
- React 18+ with hooks
- TypeScript (strict mode)
- Tailwind CSS
- Component-driven architecture

## Principles
- Functional components only
- Custom hooks for logic reuse
- Accessibility (WCAG AA)
- Performance (lazy loading, memoization)

[More specific guidance...]
```

```yaml
# Backend Specialist
---
name: backend-specialist
description: Node.js/Express API development, database design, and server architecture. Use PROACTIVELY for backend work.
tools: Read, Write, Edit, Grep, Bash(npm:*), Bash(docker:*)
---

You are a Node.js backend expert.

[Similar detailed structure...]
```

### Pattern 3: Security-First Architecture

```yaml
# Security Analyzer (Read-Only)
---
name: security-analyzer
description: Analyze code for security vulnerabilities before allowing modifications. MUST BE USED before code changes in sensitive areas.
tools: Read, Grep, Glob, Bash(git diff:*)
---

You are a security analyst. Review code for vulnerabilities BEFORE changes are made.

## Security Checks
1. Authentication/Authorization
2. Input validation
3. SQL injection
4. XSS vulnerabilities
5. CSRF protection
6. Secrets management

## Output
Return ONLY:
- Security score (1-10)
- Critical issues (block changes)
- Warnings (allow with caution)
```

### Pattern 4: Test-Driven Subagent

```yaml
---
name: test-first-developer
description: Write comprehensive tests before implementing features. Use PROACTIVELY for TDD workflows.
tools: Read, Write, Bash(npm test:*)
model: sonnet
---

You are a TDD expert. For every feature request:

1. **Analyze Requirements**
   - Extract testable behaviors
   - Identify edge cases

2. **Write Tests FIRST**
   - Unit tests for logic
   - Integration tests for workflows
   - Edge case coverage

3. **Run Tests** (they should fail)
   ```bash
   npm test
   ```

4. **Implement ONLY Enough** to pass tests

5. **Refactor** while keeping tests green

## Test Structure
```javascript
describe('Feature', () => {
  it('handles happy path', () => {})
  it('handles edge case 1', () => {})
  it('throws on invalid input', () => {})
})
```

Never implement before tests exist.
```

## Testing & Validation

### 1. Test Trigger Accuracy

Create test scenarios:

```markdown
# Test Plan for "api-developer" subagent

## Positive Tests (Should Activate)
1. "Create a REST endpoint for user authentication"
   - Expected: Activates
   - Actual: ___

2. "Add GraphQL mutation for updating profile"
   - Expected: Activates
   - Actual: ___

## Negative Tests (Should NOT Activate)
1. "Write unit tests for the API"
   - Expected: Does not activate (testing concern)
   - Actual: ___

2. "Review API security"
   - Expected: Does not activate (security concern)
   - Actual: ___

## Results
- Precision: X% (correct activations / total activations)
- Recall: Y% (correct activations / should activate)
```

### 2. Test Output Quality

```markdown
# Quality Checklist

Task: "Review auth.js for security issues"

Subagent Output Should Include:
- [ ] Specific vulnerabilities identified
- [ ] File:line locations
- [ ] Severity ratings
- [ ] Concrete fix suggestions
- [ ] Code examples for fixes

Should NOT Include:
- [ ] Generic advice
- [ ] Full file listings
- [ ] Unrelated issues
- [ ] Style nitpicks
```

### 3. Test Tool Access

```bash
# Verify tool restrictions work
# Give subagent a task requiring forbidden tool

# Example: Read-only subagent shouldn't be able to edit
# Test by asking it to "fix the security issue"
# Should fail or request permission
```

### 4. Performance Testing

```markdown
# Performance Metrics

Task: "Generate API documentation"

Metrics:
- Time to complete: ___
- Tokens used: ___
- Quality score (1-10): ___
- Required follow-ups: ___

Optimization targets:
- < 30 seconds for docs
- < 5000 tokens
- Quality >= 8
- 0 follow-ups needed
```

## Refinement Workflow

### Step 1: Baseline Performance

```bash
# Document current behavior
echo "Task: [Specific task]
Expected: [What should happen]
Actual: [What actually happens]
Issues: [Problems observed]
" > .claude/agents/refinement-notes.md
```

### Step 2: Identify Root Cause

Common causes:
- Description too vague → Won't activate
- Prompt lacks specificity → Poor output
- Wrong tools → Can't complete task
- Wrong model → Too slow/simple
- Output not filtered → Context pollution

### Step 3: Make Targeted Changes

**Only change ONE thing at a time**:
1. Update description OR
2. Refine prompt OR
3. Adjust tools OR
4. Change model

### Step 4: Test Changes

```bash
# Test with same scenarios
# Compare before/after results
# Document improvements
```

### Step 5: Iterate

Repeat until subagent meets quality bar.

## Best Practices Summary

### Description Writing

```yaml
# Template
description: [Action verb] [domain/task] [including specific capabilities]. Use [trigger condition]. PROACTIVELY when [scenario].
```

**Examples**:
```yaml
description: Analyze Python code for performance bottlenecks including O(n²) algorithms, memory leaks, and inefficient database queries. Use PROACTIVELY when optimizing Python applications.

description: Generate comprehensive API documentation from code including endpoints, parameters, responses, and examples. Use when documenting REST or GraphQL APIs.

description: Review frontend code for accessibility issues following WCAG 2.1 AA standards. MUST BE USED for all UI component changes.
```

### System Prompt Structure

```markdown
# Role Definition
You are a [role] specializing in [domain].

## Responsibilities
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities]

## Process
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Output Format
[Specific structure required]

## Examples

### Good Example
[Show what good looks like]

### Bad Example
[Show what to avoid]

## Constraints
- [Important limitation]
- [Another constraint]
```

### Tool Selection Strategy

```markdown
Decision Tree:

1. Does it need to modify files?
   No → Read, Grep, Glob only
   Yes → Continue

2. Does it need to run tests/builds?
   No → Read, Write, Edit only
   Yes → Add Bash(test:*), Bash(build:*)

3. Does it need external data?
   Yes → Add WebFetch, WebSearch
   No → Continue

4. Does it need git operations?
   Yes → Add Bash(git:*) with specific commands
   No → Done
```

### Model Selection

```markdown
Choose model based on:

1. Task complexity
   - Simple transforms → haiku
   - Standard coding → sonnet
   - Complex reasoning → opus

2. Cost sensitivity
   - High volume, simple → haiku
   - Balanced → sonnet
   - Quality critical → opus

3. Speed requirements
   - Real-time needed → haiku
   - Standard → sonnet
   - Can wait → opus

Default: sonnet (best balance)
```

## Debugging Checklist

When subagent doesn't work as expected:

```markdown
- [ ] Description is specific and includes trigger words
- [ ] Description includes "PROACTIVELY" or "MUST BE USED" if needed
- [ ] System prompt defines role clearly
- [ ] System prompt includes process/steps
- [ ] System prompt specifies output format
- [ ] System prompt has examples
- [ ] Tools match required capabilities
- [ ] Tools follow least-privilege principle
- [ ] Model appropriate for task complexity
- [ ] File location correct (.claude/agents/)
- [ ] YAML frontmatter valid
- [ ] Name uses kebab-case
- [ ] Tested with positive/negative scenarios
```

## Common Anti-Patterns

### ❌ Anti-Pattern 1: Generic Description

```yaml
---
description: Helps with coding
---
```

**Why Bad**: Won't trigger reliably

**Fix**: Be specific about domain and triggers

### ❌ Anti-Pattern 2: No Process Defined

```markdown
You are a code reviewer. Review code.
```

**Why Bad**: Inconsistent results

**Fix**: Define step-by-step process

### ❌ Anti-Pattern 3: All Tools Granted

```yaml
---
# Omitting tools when only reads needed
---
```

**Why Bad**: Unnecessary permissions, security risk

**Fix**: Whitelist minimum required tools

### ❌ Anti-Pattern 4: Verbose System Prompt

```markdown
You are an expert developer with 20 years of experience who has worked on numerous projects across different industries... [3000 words]
```

**Why Bad**: Token waste, slower activation

**Fix**: Be concise, focus on process and format

### ❌ Anti-Pattern 5: No Output Structure

```markdown
Review the code and tell me about issues.
```

**Why Bad**: Inconsistent format, hard to parse

**Fix**: Define exact output format

## Advanced Techniques

### Technique 1: Chained Subagents

Use hooks or explicit handoffs:

```json
// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Please use security-analyzer subagent to review this file' && exit 0"
          }
        ]
      }
    ]
  }
}
```

### Technique 2: Context Injection

```yaml
---
name: context-aware-developer
---

Before starting any task:
1. Read PROJECT_CONTEXT.md
2. Review ARCHITECTURE.md
3. Check CODING_STANDARDS.md

Then proceed with development following documented patterns.
```

### Technique 3: Quality Gates

```yaml
---
name: pr-ready-checker
description: Verify code is PR-ready before submitting. MUST BE USED before creating pull requests.
tools: Read, Grep, Bash(npm test:*), Bash(npm run lint:*)
---

Verify PR readiness:

1. **Tests Pass**
   ```bash
   npm test
   ```
   All tests must pass.

2. **Linting Clean**
   ```bash
   npm run lint
   ```
   Zero warnings or errors.

3. **Coverage Adequate**
   - New code > 80% covered
   - Overall coverage not decreased

4. **Documentation Updated**
   - README if public API changed
   - Inline comments for complex logic

5. **No Debug Code**
   - No console.log
   - No debugger statements
   - No commented code

Return: "PR Ready: Yes/No" + blockers list
```

### Technique 4: Iterative Refinement Prompt

```yaml
---
name: iterative-implementer
---

When implementation fails or produces errors:

1. **Analyze Failure**
   - What was the error?
   - Why did it happen?
   - What was I trying to achieve?

2. **Adjust Approach**
   - How should I do it differently?
   - What did I learn?

3. **Re-implement**
   - Apply new approach
   - Test immediately

4. **Verify**
   - Did it work?
   - If not, repeat from step 1

Never give up after one failure. Iterate until success.
```

## Migration: Ad-Hoc to Subagent

### When to Migrate

Migrate repetitive prompts to subagents when:
- You've used the same prompt 3+ times
- Prompt has clear pattern/structure
- Task benefits from isolation
- Multiple team members need it

### Migration Process

**Step 1: Extract Pattern**

```markdown
# Repeated prompts you've used:

1. "Review auth.js for security issues including SQL injection, XSS, and auth flaws"
2. "Check payment.js for security vulnerabilities like injection and secrets"
3. "Analyze api.js for security problems including validation and auth"

# Common pattern:
Review [file] for security [vulnerability types]
```

**Step 2: Generalize**

```yaml
---
name: security-reviewer
description: Review code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY for security reviews.
tools: Read, Grep, Glob
---

Review provided files for security vulnerabilities:

[Extract common structure from your prompts]
```

**Step 3: Test & Refine**

Test with previous use cases, refine until quality matches or exceeds manual prompts.

## Resources

- [Official Subagents Documentation](https://docs.claude.com/en/docs/claude-code/sub-agents)
- [Claude Code Plugins](../claude-code-plugins/SKILL.md) - For packaging subagents
- [Slash Commands](../claude-code-slash-commands/SKILL.md) - Alternative for simpler patterns
- [Hooks](../claude-code-hooks/SKILL.md) - For automating subagent workflows

---

**Remember**: Start with `/agents` command for creation. Use this skill for refinement. Iterate based on real usage. Test thoroughly. Document learnings.