---
name: Claude Code Subagent Specialist
description: Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, descriptions, and performance. Use PROACTIVELY immediately AFTER creating subagent with /agents command to optimize configuration, when subagent doesn't activate as expected, when users mention "subagent not working", "agent won't trigger", or "refine agent". 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
- Troubleshooting activation issues
- Optimizing tool access and permissions
- Improving delegation patterns
- Converting ad-hoc workflows to subagents

Do NOT use this skill for:
- **Initial creation** - Use `/agents` command
- Creating slash commands (use claude-commands skill)
- General troubleshooting

**Important**: Always start with `/agents` to create subagents.

## Quick Reference: Subagent Structure

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

System prompt defining role, capabilities, behavior.
```

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

## Common Problems (Quick Solutions)

### Problem 1: Subagent Never Activates

**Diagnosis**: Vague description

```yaml
# ❌ Too vague
---
description: Helper agent
---

# ✓ Specific with triggers
---
description: Analyze code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY when reviewing code for security issues.
---
```

**Fix**: Add specificity + "PROACTIVELY" or "MUST BE USED"

### Problem 2: Wrong Tool Access

```yaml
# ❌ Too permissive (inherits all)
---
name: security-analyzer
# (no tools field)
---

# ✓ Restricted to needs
---
name: security-analyzer
tools: Read, Grep, Glob
---
```

**Tool Access Strategies**:
- **Inherit All**: Omit `tools` field
- **Read-Only**: `tools: Read, Grep, Glob`
- **Specific**: `tools: Read, Write, Edit, Bash(npm test:*)`
- **Research**: `tools: WebFetch, WebSearch`

### Problem 3: Poor Output Quality

**Diagnosis**: Needs structured prompt

```markdown
# ❌ Vague
You review code for issues.

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

## Your Responsibilities
1. **Logic & Correctness**: Verify algorithms, edge cases
2. **Code Quality**: SRP, DRY, meaningful naming
3. **Security**: Injection vulnerabilities, auth checks
4. **Performance**: O(n²) algorithms, resource cleanup

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

## Constraints
- Only actionable issues
- Focus on high-impact problems
```

For detailed patterns, see [patterns.md](patterns.md)

## Description Best Practices

### Template
```yaml
description: [Action] [domain] [including capabilities]. Use [trigger]. PROACTIVELY when [scenario].
```

### Examples

**✓ Good**:
```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.
```

**❌ Avoid**:
```yaml
description: Helps with coding
description: Python utilities
description: Security checker
```

## Model Selection

| Model | Use For | Avoid For |
|-------|---------|-----------|
| haiku | Simple transforms, quick checks | Complex reasoning |
| sonnet | General tasks (default) | When opus needed |
| opus | Complex architecture, creative work | Simple tasks (costly) |
| inherit | Task matches main thread | Need different capability |

## Testing Subagents

### Test Plan Template

```markdown
# Positive Tests (Should Activate)
1. "Create REST endpoint for user auth"
   Expected: Activates
   Actual: ___

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

## Results
- Precision: X%
- Recall: Y%
```

For complete testing, see [testing.md](testing.md)

## System Prompt Structure

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

## Responsibilities
1. [Primary responsibility]
2. [Secondary responsibility]

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

## Output Format
[Specific structure required]

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

## Constraints
- [Important limitation]
```

## Optimization Patterns

### 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.

## 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)
```

### Role-Based Pipeline

```yaml
# Architect Agent (opus)
---
name: solution-architect
description: Design system architecture from requirements
tools: Read, Write, WebSearch
model: opus
---

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

## Debugging Checklist

When subagent doesn't work:

- [ ] Description is specific with trigger words
- [ ] Description includes "PROACTIVELY" if needed
- [ ] System prompt defines role clearly
- [ ] System prompt includes process/steps
- [ ] System prompt specifies output format
- [ ] Tools match required capabilities
- [ ] Model appropriate for complexity
- [ ] File in `.claude/agents/`
- [ ] YAML frontmatter valid
- [ ] Name uses kebab-case
- [ ] Tested positive/negative scenarios

## Migration: Ad-Hoc to Subagent

### When to Migrate
- Used same prompt 3+ times
- Prompt has clear pattern
- Task benefits from isolation
- Multiple team members need it

### Process

**Step 1: Extract Pattern**
```
# Repeated prompts:
1. "Review auth.js for security"
2. "Check payment.js for vulnerabilities"
3. "Analyze api.js for security"

# Pattern: Review [file] for security
```

**Step 2: Generalize**
```yaml
---
name: security-reviewer
description: Review code for security vulnerabilities. Use PROACTIVELY for security reviews.
tools: Read, Grep, Glob
---
```

**Step 3: Test & Refine**
Test with previous use cases, refine until quality matches.

## Additional Resources

**Need more?**
- [Optimization Patterns](patterns.md) - Advanced subagent patterns
- [Testing Strategies](testing.md) - Comprehensive testing
- [System Prompt Templates](templates.md) - Ready-to-use prompts
- [Official Docs](https://docs.claude.com/en/docs/claude-code/sub-agents)

💡 **Tip**: Start with `/agents`, then refine. Iterate based on real usage. Test thoroughly.

---

**Remember**: Use `/agents` to create. This skill refines. Specific descriptions trigger correctly. Test positive AND negative scenarios.