303 lines
7.5 KiB
Markdown
303 lines
7.5 KiB
Markdown
---
|
|
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.
|