movq/claude-plugins
2
0
Fork 0
Code Issues Pull Requests Actions Releases Activity

Skill refresh

Browse Source
This commit is contained in:
movq
2025-10-28 12:28:48 -05:00
parent 7911d90995
commit 35d2069861
26 changed files with 3837 additions and 4143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

362
claude-code/skills/claude-subagents/SKILL.md Normal file
View File

@@ -0,0 +1,362 @@
---
name: Claude Code Subagent Specialist
description: 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
```yaml
---
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
```yaml
# ❌ 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
```yaml
# ❌ 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
```markdown
# ❌ 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](patterns.md)
## Description Best Practices
### Template
```yaml
description: [Action verb] [domain/task] [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 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
```markdown
# 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](testing.md)
## 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]
```
## Optimization Patterns
### Pattern 1: Role-Based Pipeline
Specialized agents for each workflow stage:
```yaml
# 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
```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)
```
For more patterns, see [patterns.md](patterns.md)
## 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
### ❌ Generic Description
```yaml
description: Helps with coding
```
**Fix**: Be specific about domain and triggers
### ❌ No Process Defined
```markdown
You are a code reviewer. Review code.
```
**Fix**: Define step-by-step process
### ❌ All Tools Granted
```yaml
# Omitting tools when only reads needed
```
**Fix**: Whitelist minimum required tools
### ❌ Verbose Prompt
```markdown
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**
```markdown
# 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**
```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
---
```
**Step 3: Test & Refine**
Test with previous use cases, refine until quality matches manual prompts.
## Resources
- [Optimization Patterns](patterns.md) - Advanced subagent patterns
- [Testing Strategies](testing.md) - Comprehensive testing guide
- [System Prompt Templates](templates.md) - Ready-to-use prompts
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/sub-agents)
---
**Remember**: Start with `/agents` for creation. Use this skill for refinement. Iterate based on real usage. Test thoroughly.