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

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

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

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

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

Description Best Practices

Template

description: [Action] [domain] [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

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

# 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

System Prompt Structure

# 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

# 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

# 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

---
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 - Advanced subagent patterns
• Testing Strategies - Comprehensive testing
• System Prompt Templates - Ready-to-use prompts
• Official Docs

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