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

Refinement for context size

Browse Source
This commit is contained in:
movq
2025-10-28 12:48:17 -05:00
parent 35d2069861
commit ddea00cb40
11 changed files with 1539 additions and 1196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
claude-code/skills/claude-subagents/SKILL.md
View File

@@ -1,6 +1,6 @@
---
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.
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
@@ -8,31 +8,30 @@ description: Refine and troubleshoot Claude Code subagents by optimizing prompts
## When to Use This Skill
Use this skill when:
- Refining existing subagent prompts for better performance
- Troubleshooting why a subagent isn't activating
- Refining existing subagent prompts
- Troubleshooting activation issues
- Optimizing tool access and permissions
- Improving subagent descriptions for better delegation
- Debugging context management issues
- Converting ad-hoc workflows to reusable subagents
- Improving delegation patterns
- Converting ad-hoc workflows to 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
- **Initial creation** - Use `/agents` command
- Creating slash commands (use claude-commands skill)
- General troubleshooting
**Important**: Always start with `/agents` to create subagents. Use this skill to refine them afterward.
**Important**: Always start with `/agents` to create subagents.
## Quick Reference: Subagent Structure
```yaml
---
name: agent-name # Lowercase, kebab-case
description: When to use # Triggers automatic delegation
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, and behavior.
System prompt defining role, capabilities, behavior.
```
**Locations**:
@@ -44,31 +43,29 @@ System prompt defining role, capabilities, and behavior.
### Problem 1: Subagent Never Activates
**Diagnosis**: Check description specificity
**Diagnosis**: Vague description
```yaml
# ❌ Too vague (ignored)
# ❌ Too vague
---
description: Helper agent
---
# ✓ Specific (works)
# ✓ 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**: Make description specific with trigger words + "PROACTIVELY" or "MUST BE USED"
**Fix**: Add specificity + "PROACTIVELY" or "MUST BE USED"
### Problem 2: Wrong Tool Access
**Diagnosis**: Check tool configuration
```yaml
# ❌ Too permissive
# ❌ Too permissive (inherits all)
---
name: security-analyzer
# (inherits all tools)
# (no tools field)
---
# ✓ Restricted to needs
@@ -79,21 +76,21 @@ 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)
- **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**: System prompt needs structure
**Diagnosis**: Needs structured prompt
```markdown
# ❌ Vague
You review code for issues.
# ✓ Structured
You are a senior code reviewer specializing in production-ready code quality.
You are a senior code reviewer specializing in production-ready quality.
## Your Responsibilities
1. **Logic & Correctness**: Verify algorithms, edge cases
@@ -113,13 +110,13 @@ For each issue:
- Focus on high-impact problems
```
For detailed system prompt patterns, see [patterns.md](patterns.md)
For detailed patterns, see [patterns.md](patterns.md)
## Description Best Practices
### Template
```yaml
description: [Action verb] [domain/task] [including capabilities]. Use [trigger]. PROACTIVELY when [scenario].
description: [Action] [domain] [including capabilities]. Use [trigger]. PROACTIVELY when [scenario].
```
### Examples
@@ -140,17 +137,15 @@ description: Python utilities
description: Security checker
```
## Model Selection Guide
## Model Selection
| 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) |
| 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 |
**Default**: sonnet (best balance)
## Testing Subagents
### Test Plan Template
@@ -161,25 +156,17 @@ description: Security checker
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)
Expected: Does not activate (different concern)
Actual: ___
## Results
- Precision: X% (correct activations / total activations)
- Recall: Y% (correct activations / should activate)
- Precision: X%
- Recall: Y%
```
For complete testing strategies, see [testing.md](testing.md)
For complete testing, see [testing.md](testing.md)
## System Prompt Structure
@@ -190,62 +177,25 @@ 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
### Domain Specialists
```yaml
# Frontend Specialist
@@ -255,7 +205,7 @@ description: React/TypeScript UI development and component design. Use PROACTIVE
tools: Read, Write, Edit, Grep, Bash(npm:*)
---
You are a React/TypeScript expert specializing in modern frontend development.
You are a React/TypeScript expert specializing in modern frontend.
## Tech Stack
- React 18+ with hooks
@@ -267,96 +217,86 @@ You are a React/TypeScript expert specializing in modern frontend development.
- Functional components only
- Custom hooks for logic reuse
- Accessibility (WCAG AA)
- Performance (lazy loading, memoization)
```
For more patterns, see [patterns.md](patterns.md)
### 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 as expected:
When subagent doesn't work:
```markdown
- [ ] Description is specific and includes trigger words
- [ ] Description includes "PROACTIVELY" or "MUST BE USED" if needed
- [ ] 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
- [ ] System prompt has examples
- [ ] Tools match required capabilities
- [ ] Tools follow least-privilege principle
- [ ] Model appropriate for task complexity
- [ ] File location correct (.claude/agents/)
- [ ] Model appropriate for complexity
- [ ] File in `.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
- [ ] Tested positive/negative scenarios
## Migration: Ad-Hoc to Subagent
### When to Migrate
- Used same prompt 3+ times
- Prompt has clear pattern/structure
- Prompt has clear pattern
- Task benefits from isolation
- Multiple team members need it
### Process
**Step 1: Extract Pattern**
```markdown
```
# Repeated prompts:
1. "Review auth.js for security issues"
1. "Review auth.js for security"
2. "Check payment.js for vulnerabilities"
3. "Analyze api.js for security problems"
3. "Analyze api.js for security"
# Common pattern: Review [file] for security [types]
# Pattern: Review [file] for security
```
**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.
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 manual prompts.
Test with previous use cases, refine until quality matches.
## Resources
## Additional Resources
**Need more?**
- [Optimization Patterns](patterns.md) - Advanced subagent patterns
- [Testing Strategies](testing.md) - Comprehensive testing guide
- [Testing Strategies](testing.md) - Comprehensive testing
- [System Prompt Templates](templates.md) - Ready-to-use prompts
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/sub-agents)
- [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**: Start with `/agents` for creation. Use this skill for refinement. Iterate based on real usage. Test thoroughly.
**Remember**: Use `/agents` to create. This skill refines. Specific descriptions trigger correctly. Test positive AND negative scenarios.