claude-plugins/claude-code/skills/claude-subagents/SKILL.md

name, description

name	description
Claude Code Subagent Specialist	Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, descriptions, and performance. Use PROACTIVELY when improving existing subagents, debugging activation issues, optimizing delegation patterns, or 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 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
• Converting ad-hoc workflows to reusable subagents

Do NOT use this skill for:

• Initial creation - Use /agents command instead (interactive UI)
• Creating slash commands (use claude-command-expert skill)
• General Claude Code troubleshooting

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

Quick Reference: Subagent Structure

---
name: agent-name              # Lowercase, kebab-case
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.

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: Check description specificity

# ❌ Too vague (ignored)
---
description: Helper agent
---

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

Fix: Make description specific with trigger words + "PROACTIVELY" or "MUST BE USED"

Problem 2: Wrong Tool Access

Diagnosis: Check tool configuration

# ❌ Too permissive
---
name: security-analyzer
# (inherits all tools)
---

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

Tool Access Strategies:

• Inherit All: Omit tools field (full flexibility)
• Read-Only: tools: Read, Grep, Glob (analysis/review)
• Specific: tools: Read, Write, Edit, Bash(npm test:*) (implementation)
• No Files: tools: WebFetch, WebSearch (research only)

Problem 3: Poor Output Quality

Diagnosis: System prompt needs structure

# ❌ Vague
You review code for issues.

# ✓ Structured
You are a senior code reviewer specializing in production-ready code 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 system prompt patterns, see patterns.md

Description Best Practices

Template

description: [Action verb] [domain/task] [including capabilities]. Use [trigger]. PROACTIVELY when [scenario].

Examples

✓ Good:

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:

description: Helps with coding
description: Python utilities
description: Security checker

Model Selection Guide

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

Default: sonnet (best balance)

Testing Subagents

Test Plan Template

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

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

# Negative Tests (Should NOT Activate)
1. "Write unit tests for 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)

For complete testing strategies, see testing.md

System Prompt Structure

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

Optimization Patterns

Pattern 1: Role-Based Pipeline

Specialized agents for each workflow stage:

# Spec Agent (opus)
---
name: product-spec-writer
description: Create detailed product specifications from user requirements
tools: Read, Write, WebSearch
model: opus
---

# Architect Agent (opus)
---
name: solution-architect
description: Design system architecture from product specs
tools: Read, Write, Grep, Glob
model: opus
---

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

Pattern 2: Domain Specialists

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

For more patterns, see patterns.md

Debugging Checklist

When subagent doesn't work as expected:

- [ ] 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

❌ Generic Description

description: Helps with coding

Fix: Be specific about domain and triggers

❌ No Process Defined

You are a code reviewer. Review code.

Fix: Define step-by-step process

❌ All Tools Granted

# Omitting tools when only reads needed

Fix: Whitelist minimum required tools

❌ Verbose Prompt

You are an expert developer with 20 years of experience... [3000 words]

Fix: Be concise, focus on process and format

Migration: Ad-Hoc to Subagent

When to Migrate

• Used same prompt 3+ times
• Prompt has clear pattern/structure
• Task benefits from isolation
• Multiple team members need it

Process

Step 1: Extract Pattern

# Repeated prompts:
1. "Review auth.js for security issues"
2. "Check payment.js for vulnerabilities"
3. "Analyze api.js for security problems"

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

Step 2: Generalize

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

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

Resources

• Optimization Patterns - Advanced subagent patterns
• Testing Strategies - Comprehensive testing guide
• System Prompt Templates - Ready-to-use prompts
• Official Documentation

---

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