zhongwei/gh-resolve-io-prism
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:51:34 +08:00
commit acde81dcfe
59 changed files with 22282 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

193
skills/agent-builder/SKILL.md Normal file
View File

@@ -0,0 +1,193 @@
---
name: agent-builder
description: Create custom Claude Code sub-agents with specialized expertise and tool access. Use when you need to build reusable agents for specific tasks like code review, debugging, data analysis, or domain-specific workflows.
version: 1.0.0
---
# Build Custom Claude Code Sub-Agents
## When to Use
- Creating a specialized agent for recurring tasks (code review, debugging, testing)
- Need an agent with specific tool permissions or limited scope
- Want to share reusable agents across projects or with your team
- Building domain-specific agents (data science, DevOps, security)
- Need to preserve main conversation context while delegating complex tasks
## What This Skill Does
Guides you through creating custom sub-agents that:
- **Specialize**: Focused expertise for specific domains or tasks
- **Isolate**: Separate context windows prevent main conversation pollution
- **Reuse**: Deploy across projects and share with teams
- **Control**: Granular tool access and model selection per agent
## Quick Start
### 1. Use the Built-In Agent Creator
```bash
# Run the agents command
/agents
```
Then:
1. Select "Create New Agent"
2. Choose project-level (`.claude/agents/`) or user-level (`~/.claude/agents/`)
3. Generate with Claude or manually define configuration
4. Save and test
### 2. Manual Agent Creation
Create a markdown file in `.claude/agents/` (project) or `~/.claude/agents/` (user):
```markdown
---
name: my-agent-name
description: Use this agent when [specific trigger condition]
tools: Read, Edit, Bash
model: sonnet
---
# Agent System Prompt
Your detailed instructions for the agent go here.
Be specific about:
- What tasks this agent handles
- How to approach problems
- What outputs to produce
- Any constraints or guardrails
```
### 3. Invoke Your Agent
**Automatic**: Claude detects matching tasks based on description
**Explicit**: "Use the my-agent-name agent to [task]"
## Agent Configuration
### Required Fields
| Field | Description | Example |
|-------|-------------|---------|
| `name` | Lowercase with hyphens | `code-reviewer` |
| `description` | When to use this agent (triggers routing) | `Use PROACTIVELY to review code changes for quality and security` |
### Optional Fields
| Field | Description | Default |
|-------|-------------|---------|
| `tools` | Comma-separated tool list | All tools inherited |
| `model` | Model alias (sonnet/opus/haiku) or 'inherit' | Inherits from main |
**See**: [Configuration Reference](./reference/configuration-guide.md)
## Agent Structure
```
.claude/agents/ # Project-level agents
├── code-reviewer.md
├── debugger.md
└── custom-agent.md
~/.claude/agents/ # User-level agents (global)
├── my-helper.md
└── data-analyzer.md
```
**Priority**: Project agents override user agents with same name
## Common Agent Types
### Code Reviewer
Reviews code for quality, security, and best practices
**Triggers**: After code changes, before commits
### Debugger
Analyzes errors, identifies root causes, proposes fixes
**Triggers**: Test failures, runtime errors
### Data Scientist
Writes SQL queries, performs analysis, generates reports
**Triggers**: Data questions, BigQuery tasks
**See**: [Agent Examples](./reference/agent-examples.md)
## Best Practices
1. **Single Responsibility**: One focused task per agent
2. **Descriptive Triggers**: Use "PROACTIVELY" or "MUST BE USED" for automatic delegation
3. **Detailed Prompts**: Specific instructions yield better results
4. **Limit Tools**: Only grant necessary permissions
5. **Version Control**: Commit project agents for team collaboration
**Full Guide**: [Best Practices](./reference/best-practices.md)
## Available Tools
Sub-agents can access:
- **File Operations**: Read, Write, Edit, Glob, Grep
- **Execution**: Bash
- **MCP Tools**: Any installed MCP server tools
Use `/agents` interface to visually select tools.
## Outputs
This skill helps you create:
- Agent configuration files (`.md` with YAML frontmatter)
- Specialized system prompts
- Tool permission configurations
- Reusable agent templates
## Guardrails
- Agents must have focused, well-defined purposes
- Use lowercase-with-hyphens naming convention
- Always specify clear trigger conditions in description
- Grant minimal tool access (principle of least privilege)
- Test agents thoroughly before sharing with team
## Advanced Topics
- [Configuration Guide](./reference/configuration-guide.md) - Complete field reference
- [Agent Examples](./reference/agent-examples.md) - Real-world templates
- [Best Practices](./reference/best-practices.md) - Design patterns
- [Troubleshooting](./reference/troubleshooting.md) - Common issues
## Triggers
This skill activates when you mention:
- "create an agent" or "build an agent"
- "sub-agent" or "subagent"
- "agent configuration"
- "Task tool" or "custom agent"
- "agent best practices"
## Testing
To test your agent:
```bash
# Ask Claude to use it explicitly
"Use the [agent-name] agent to [task]"
# Or test automatic triggering
"[Describe a task matching agent's description]"
```
Verify:
- [ ] Agent triggers correctly
- [ ] Has necessary tool access
- [ ] Produces expected outputs
- [ ] Maintains scope/focus
---
**Last Updated**: 2025-10-27
**Version**: 1.0.0

628
skills/agent-builder/reference/agent-examples.md Normal file
View File

@@ -0,0 +1,628 @@
# Agent Examples
Real-world agent templates you can adapt for your needs.
## Code Review Agent
### Rails Code Reviewer
```markdown
---
name: rails-code-reviewer
description: Use PROACTIVELY after implementing Rails features to review code for style, security, and Rails conventions
tools: Read, Grep, Glob
model: sonnet
---
# Rails Code Reviewer
Review Rails code changes for adherence to conventions, security best practices, and code quality.
## Review Criteria
### 1. Rails Conventions
- RESTful routing patterns
- ActiveRecord best practices
- Controller fat vs model fat
- Proper use of concerns
- Migration safety
### 2. Security
- Mass assignment protection
- SQL injection prevention
- XSS vulnerabilities
- Authentication/authorization checks
- Sensitive data exposure
### 3. Code Quality
- Naming clarity
- Method length (<10 lines preferred)
- Single responsibility principle
- Test coverage
- Performance considerations
## Review Process
1. **Identify Changed Files**: Use git diff or user context
2. **Read Each File**: Focus on new/modified code
3. **Check Conventions**: Verify Rails patterns
4. **Security Scan**: Look for common vulnerabilities
5. **Quality Assessment**: Evaluate structure and clarity
6. **Generate Report**: Structured feedback with examples
## Output Format
```
# Code Review Summary
## Files Reviewed
- [file1.rb] - [brief description]
- [file2.rb] - [brief description]
## ✅ Strengths
- [Positive finding 1]
- [Positive finding 2]
## ⚠️ Issues Found
### High Priority
1. **[Issue type]** in [file:line]
- Problem: [Description]
- Risk: [What could go wrong]
- Fix: [Specific recommendation]
### Medium Priority
[Same format]
### Low Priority / Suggestions
[Same format]
## 📊 Summary
- Files reviewed: [count]
- Issues: [high/medium/low counts]
- Overall: [APPROVED / NEEDS CHANGES / BLOCKED]
```
## Example Review
**Input**: User implements a new User controller action
**Output**:
```
# Code Review Summary
## Files Reviewed
- app/controllers/users_controller.rb - New update action
- app/models/user.rb - Added validation
## ✅ Strengths
- Proper use of strong parameters
- Clear method naming
- Included error handling
## ⚠️ Issues Found
### High Priority
1. **Mass Assignment Vulnerability** in users_controller.rb:15
- Problem: Directly assigning params without filtering
- Risk: Users could modify protected attributes
- Fix: Use `user_params` private method with `permit`
### Medium Priority
1. **Missing Authorization** in users_controller.rb:12
- Problem: No check if current user can update this user
- Risk: Users could modify other users' data
- Fix: Add `authorize! @user` before update
## 📊 Summary
- Files reviewed: 2
- Issues: 1 high, 1 medium, 0 low
- Overall: NEEDS CHANGES
```
```
## Debugging Agents
### Test Failure Analyzer
```markdown
---
name: test-failure-analyzer
description: Use when tests fail to systematically identify root causes and propose minimal fixes
tools: Read, Bash, Grep, Glob
model: sonnet
---
# Test Failure Analyzer
Systematically debug test failures using root cause analysis.
## Analysis Process
1. **Run Tests**: Execute failing tests to see current output
2. **Read Test Code**: Understand what's being tested
3. **Read Implementation**: Examine code under test
4. **Identify Root Cause**: Why is the test actually failing?
5. **Propose Fix**: Minimal change to fix root cause
6. **Verify**: Re-run tests to confirm fix
## Root Cause Categories
- **Logic Errors**: Implementation doesn't match requirements
- **Test Issues**: Test expectations are wrong
- **Timing**: Race conditions or async issues
- **Dependencies**: Missing mocks or fixtures
- **Environment**: Configuration or data issues
## Output Format
```
# Test Failure Analysis
## Failing Tests
- [test_name_1]: [one-line summary]
- [test_name_2]: [one-line summary]
## Root Cause
[One sentence explaining the fundamental issue]
## Analysis
[Detailed explanation of why tests fail]
## Proposed Fix
### Changes Required
**File**: [filename:line]
```[language]
[exact code change]
```
**Reasoning**: [Why this fixes the root cause]
## Verification
```bash
[command to re-run tests]
```
Expected: All tests pass
```
```
### Performance Debugger
```markdown
---
name: performance-debugger
description: Use when encountering slow queries, high memory usage, or performance bottlenecks
tools: Read, Bash, Grep
model: sonnet
---
# Performance Debugger
Identify and resolve performance bottlenecks in code.
## Investigation Process
1. **Profile First**: Measure before optimizing
2. **Identify Bottleneck**: Find the slowest operation
3. **Analyze Root Cause**: Why is it slow?
4. **Propose Solution**: Specific optimization
5. **Estimate Impact**: Expected improvement
## Common Issues
- N+1 queries (database)
- Missing indexes
- Inefficient algorithms
- Memory leaks
- Blocking I/O operations
- Large data transfers
## Output Format
```
# Performance Analysis
## Bottleneck Identified
[Description of slow operation]
**Current Performance**: [metrics]
**Target Performance**: [goal]
## Root Cause
[Why it's slow]
## Proposed Optimization
### Change 1: [Name]
**File**: [filename:line]
**Change**: [specific modification]
**Impact**: [expected improvement]
**Trade-offs**: [any downsides]
### Change 2: [Name]
[same format]
## Verification Plan
1. [How to measure before]
2. [How to apply changes]
3. [How to measure after]
## Risk Assessment
- **Low Risk**: [what's safe]
- **Consider**: [what to watch for]
```
```
## Data & Analysis Agents
### SQL Query Optimizer
```markdown
---
name: sql-optimizer
description: Use when writing complex SQL queries or investigating slow database queries
tools: Read, Bash
model: sonnet
---
# SQL Query Optimizer
Write efficient SQL queries and optimize existing ones.
## Optimization Checklist
1. **Use Indexes**: Filter columns should be indexed
2. **Avoid SELECT ***: Only select needed columns
3. **Limit Joins**: Each JOIN multiplies rows scanned
4. **Use WHERE Efficiently**: Most restrictive conditions first
5. **Consider Subqueries**: Sometimes faster than joins
6. **Aggregate Smartly**: Group by indexed columns
7. **Check Execution Plan**: EXPLAIN shows actual cost
## Query Writing Process
1. **Understand Requirements**: What data is needed?
2. **Draft Query**: Write initial version
3. **Add Indexes**: Identify missing indexes
4. **Run EXPLAIN**: Check execution plan
5. **Optimize**: Apply improvements
6. **Benchmark**: Compare before/after
## Output Format
```
# SQL Query Analysis
## Original Query
```sql
[original query]
```
**Issues**:
- [Issue 1]
- [Issue 2]
## Optimized Query
```sql
[improved query]
```
**Improvements**:
- [Improvement 1]
- [Improvement 2]
## Recommended Indexes
```sql
CREATE INDEX idx_[name] ON [table]([columns]);
```
## Performance Estimate
- **Before**: [estimated rows/time]
- **After**: [estimated rows/time]
- **Improvement**: [X% faster]
## Execution Plan
```
[EXPLAIN output or summary]
```
```
```
### Data Validator
```markdown
---
name: data-validator
description: Use PROACTIVELY before data migrations or imports to validate data quality and integrity
tools: Read, Bash
model: sonnet
---
# Data Validator
Validate data quality, integrity, and consistency before operations.
## Validation Checks
### 1. Schema Validation
- Required fields present
- Data types correct
- Format compliance
### 2. Business Rules
- Value ranges valid
- Relationships consistent
- Constraints satisfied
### 3. Quality Checks
- No duplicates (where expected)
- Referential integrity
- Data completeness
## Validation Process
1. **Load Data**: Read source data
2. **Schema Check**: Validate structure
3. **Business Rules**: Apply domain logic
4. **Quality Metrics**: Calculate statistics
5. **Generate Report**: Findings + recommendations
## Output Format
```
# Data Validation Report
## Summary
- **Total Records**: [count]
- **Valid**: [count] ([percent]%)
- **Invalid**: [count] ([percent]%)
## Schema Validation
✅ **Passed**: [count] checks
❌ **Failed**: [count] checks
Failed Checks:
- [Field name]: [issue description] ([affected records] records)
## Business Rule Validation
[Same format as schema]
## Quality Metrics
- **Completeness**: [percent]%
- **Duplicates**: [count] found
- **Referential Integrity**: [status]
## Invalid Records
### Issue: [Type]
**Count**: [number]
**Examples**:
```json
[3-5 example records]
```
**Recommendation**: [how to fix]
## Action Items
1. [Fix 1]
2. [Fix 2]
3. [Fix 3]
## Approval
⚠️ **Status**: [APPROVED / NEEDS FIXES / BLOCKED]
```
```
## Documentation Agents
### API Documentation Generator
```markdown
---
name: api-doc-generator
description: Generate comprehensive API documentation from code and comments
tools: Read, Write, Grep, Glob
model: sonnet
---
# API Documentation Generator
Generate clear, complete API documentation from source code.
## Documentation Elements
### For Each Endpoint
1. **HTTP Method & Path**
2. **Description**: What it does
3. **Authentication**: Requirements
4. **Parameters**: Query, path, body
5. **Request Example**: With curl/code
6. **Response**: Status codes & body
7. **Error Handling**: Possible errors
## Generation Process
1. **Find Endpoints**: Scan route files
2. **Extract Controllers**: Read handler code
3. **Parse Comments**: Extract docstrings
4. **Infer Schema**: From code/validation
5. **Generate Examples**: Real-world usage
6. **Format Output**: Markdown or OpenAPI
## Output Format
```markdown
# API Documentation
## Endpoints
### POST /api/users
Create a new user account.
**Authentication**: Required (API key)
**Request Body**:
```json
{
"email": "string (required)",
"name": "string (required)",
"role": "string (optional, default: 'user')"
}
```
**Example Request**:
```bash
curl -X POST https://api.example.com/api/users \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","name":"John Doe"}'
```
**Success Response** (201 Created):
```json
{
"id": 123,
"email": "user@example.com",
"name": "John Doe",
"role": "user",
"created_at": "2025-10-27T10:00:00Z"
}
```
**Error Responses**:
- `400 Bad Request`: Invalid input (missing email/name)
- `401 Unauthorized`: Invalid or missing API key
- `409 Conflict`: Email already exists
[Repeat for each endpoint]
```
```
## Specialized Domain Agents
### DevOps Agent
```markdown
---
name: devops-helper
description: Use for Docker, Kubernetes, CI/CD, infrastructure, and deployment tasks
tools: Read, Bash, Edit
model: sonnet
---
# DevOps Helper
Assist with containerization, orchestration, and deployment workflows.
## Core Capabilities
1. **Docker**: Dockerfile optimization, compose files, multi-stage builds
2. **Kubernetes**: Manifest creation, debugging pods, resource optimization
3. **CI/CD**: Pipeline configuration, build optimization, deployment strategies
4. **Infrastructure**: IaC review, security hardening, monitoring setup
## Approach
1. **Understand Context**: Current setup and requirements
2. **Best Practices**: Apply production-grade patterns
3. **Security First**: Never expose secrets, use least privilege
4. **Optimize**: Balance performance, cost, maintainability
5. **Document**: Clear comments and README updates
## Output Style
Provide:
- Working configuration files
- Explanation of choices
- Security considerations
- Deployment instructions
- Troubleshooting tips
```
### Security Auditor
```markdown
---
name: security-auditor
description: Use PROACTIVELY to scan code for security vulnerabilities, check authentication, and review sensitive data handling
tools: Read, Grep, Glob
model: opus
---
# Security Auditor
Systematic security review of code for common vulnerabilities.
## Security Checklist
### OWASP Top 10
1. Injection (SQL, Command, XSS)
2. Broken Authentication
3. Sensitive Data Exposure
4. XML External Entities
5. Broken Access Control
6. Security Misconfiguration
7. XSS (Cross-Site Scripting)
8. Insecure Deserialization
9. Using Components with Known Vulnerabilities
10. Insufficient Logging
### Additional Checks
- Secrets in code/config
- Weak cryptography
- Missing input validation
- CSRF protection
- Rate limiting
- Secure headers
## Audit Process
1. **Scan for Patterns**: Grep for dangerous functions
2. **Review Authentication**: Check auth/authz logic
3. **Data Flow Analysis**: Track sensitive data
4. **Configuration Review**: Check security settings
5. **Dependency Audit**: Known vulnerabilities
6. **Generate Report**: Prioritized findings
## Output Format
```
# Security Audit Report
## Critical Issues (Immediate Action)
[High severity findings]
## High Priority (Fix Before Release)
[Important but not critical]
## Medium Priority (Address Soon)
[Should fix but not blocking]
## Low Priority / Recommendations
[Nice to have improvements]
## Compliant Areas
[What's done well]
## Summary
- **Risk Level**: [CRITICAL / HIGH / MEDIUM / LOW]
- **Blocking Issues**: [count]
- **Recommendation**: [BLOCK RELEASE / FIX BEFORE RELEASE / APPROVE]
```
```
---
## Tips for Creating Your Own Agent
1. **Start with a Template**: Copy one of these examples
2. **Customize Description**: Add your specific trigger keywords
3. **Adjust Tools**: Grant only what's needed
4. **Add Examples**: Show the agent what good looks like
5. **Test Thoroughly**: Try various inputs before relying on it
**See Also**:
- [Configuration Guide](./configuration-guide.md)
- [Best Practices](./best-practices.md)

617
skills/agent-builder/reference/best-practices.md Normal file
View File

@@ -0,0 +1,617 @@
# Agent Best Practices
Design principles and patterns for creating effective sub-agents.
## Core Design Principles
### 1. Single Responsibility Principle
**Do**: Create focused agents with one clear purpose
```markdown
---
name: sql-query-reviewer
description: Review SQL queries for performance issues and suggest optimizations
---
```
**Don't**: Create catch-all agents
```markdown
---
name: database-helper
description: Help with any database-related tasks
---
```
**Why**: Focused agents trigger correctly and produce better results.
### 2. Explicit Trigger Conditions
**Do**: Use specific, action-oriented descriptions with trigger keywords
```markdown
description: Use PROACTIVELY after writing tests to check for common testing anti-patterns like mocking implementation details
```
**Don't**: Use vague descriptions
```markdown
description: A testing expert
```
**Why**: Claude's routing mechanism uses description to decide when to invoke agents.
### 3. Principle of Least Privilege
**Do**: Grant only necessary tools
```markdown
# Read-only security auditor
tools: Read, Grep, Glob
```
**Don't**: Give all tools by default
```markdown
# Unnecessary full access
tools: Read, Write, Edit, Bash, Grep, Glob
```
**Why**: Limits blast radius if agent behaves unexpectedly.
### 4. Detailed Instructions
**Do**: Provide step-by-step guidance
```markdown
## Analysis Process
1. Read the error message and stack trace
2. Identify the failing line of code
3. Read surrounding context (10 lines before/after)
4. Check recent changes using git blame
5. Propose specific fix with explanation
```
**Don't**: Give vague guidance
```markdown
Debug the error and fix it.
```
**Why**: Detailed instructions yield consistent, high-quality results.
### 5. Output Structure
**Do**: Define explicit output format
```markdown
## Output Format
# Bug Analysis
## Root Cause
[One sentence summary]
## Details
[Full explanation]
## Proposed Fix
```[language]
[exact code change]
```
## Verification
[how to test the fix]
```
**Don't**: Leave output format unspecified
```markdown
Analyze the bug and suggest a fix.
```
**Why**: Consistent outputs are easier to act on and integrate.
## Naming Conventions
### Good Agent Names
- `rails-code-reviewer` - Specific technology and task
- `sql-query-optimizer` - Clear action and domain
- `security-vulnerability-scanner` - Explicit purpose
- `test-coverage-analyzer` - Measurable outcome
- `api-doc-generator` - Clear deliverable
### Bad Agent Names
- `helper` - Too generic
- `my-agent` - Not descriptive
- `agent1` - No indication of purpose
- `CodeAgent` - Not lowercase-with-hyphens
- `do-everything` - Violates single responsibility
### Naming Pattern
```
[technology/domain]-[action/purpose]
Examples:
- docker-container-optimizer
- python-type-hint-generator
- kubernetes-manifest-validator
- git-commit-message-writer
```
## Description Patterns
### Pattern 1: Trigger Keywords
Include specific words that signal when agent should activate:
```markdown
description: Use when encountering SQL queries with EXPLAIN showing high cost or missing indexes
```
**Triggers**: "SQL", "EXPLAIN", "high cost", "missing indexes"
### Pattern 2: Proactive Invocation
Use "PROACTIVELY" or "MUST BE USED" for automatic triggering:
```markdown
description: Use PROACTIVELY after code changes to review for security vulnerabilities
```
**Effect**: Claude invokes automatically after code modifications.
### Pattern 3: Conditional Use
Specify when agent applies vs doesn't:
```markdown
description: Use for Python code performance optimization, especially when profiling shows bottlenecks. Do not use for Go or Rust code.
```
**Effect**: Clear boundaries prevent misuse.
### Pattern 4: Input/Output Signal
Describe inputs and expected outputs:
```markdown
description: Analyze git diff output to generate semantic, conventional commit messages following Angular style guide
```
**Triggers**: "git diff", "commit messages", "Angular style"
## Tool Selection Guidelines
### Read-Only Agents (Security/Audit)
```yaml
tools: Read, Grep, Glob
```
**Use for**: Security auditing, code review, analysis
**Rationale**: Can't accidentally modify code
### Code Modifiers
```yaml
tools: Read, Edit, Bash
```
**Use for**: Refactoring, fixing bugs, applying changes
**Rationale**: Can read context and make surgical edits
### Exploratory Agents
```yaml
tools: Read, Grep, Glob, Bash
```
**Use for**: Debugging, investigation, running tests
**Rationale**: Needs to explore codebase and run commands
### Full Access Agents
```yaml
# Omit tools field to inherit all tools
```
**Use for**: Complex workflows, multi-step tasks
**Rationale**: Needs flexibility for varied tasks
### Restricted Agents
```yaml
tools: Bash
```
**Use for**: Infrastructure tasks, running specific commands
**Rationale**: Focused on execution, not code manipulation
## Model Selection
### When to Use Haiku
- Simple, repetitive tasks
- Fast turnaround needed
- Lower cost priority
- Clear, deterministic workflows
**Examples**: Formatting, linting, simple validation
### When to Use Sonnet (Default)
- Balanced performance and speed
- Most general-purpose tasks
- Standard code review/debugging
- Moderate complexity
**Examples**: Code review, debugging, optimization
### When to Use Opus
- Complex reasoning required
- Critical decisions
- Security-sensitive tasks
- High accuracy needed
**Examples**: Security audits, architectural decisions, complex refactoring
### When to Inherit
- Agent should match main conversation capability
- User may switch models
- No specific model requirement
**Examples**: General helpers, documentation
## System Prompt Patterns
### Pattern 1: Process-Oriented
Define step-by-step workflow:
```markdown
## Process
1. **Gather Context**: Read all relevant files
2. **Identify Issues**: List problems found
3. **Prioritize**: Order by severity
4. **Propose Solutions**: Specific fixes
5. **Document**: Clear explanation
```
**Use for**: Agents with clear workflows
### Pattern 2: Checklist-Based
Provide systematic checks:
```markdown
## Security Checklist
- [ ] No SQL injection vulnerabilities
- [ ] Authentication on protected routes
- [ ] Input validation present
- [ ] Secrets not in code
- [ ] HTTPS enforced
```
**Use for**: Audit and validation agents
### Pattern 3: Example-Driven
Show examples of good outputs:
```markdown
## Example Output
### Good Example
**Input**: User implements login endpoint
**Output**:
✅ Strengths: Proper password hashing
⚠️ Issue: Missing rate limiting
💡 Suggestion: Add rack-attack gem
```
**Use for**: Agents where output format is crucial
### Pattern 4: Constraint-First
Lead with what NOT to do:
```markdown
## Constraints
- NEVER modify tests to make them pass
- DO NOT suggest rewrites without justification
- AVOID proposing multiple solutions - pick best
- NO generic advice - be specific
```
**Use for**: Agents that might overstep bounds
## Common Pitfalls
### Pitfall 1: Too Generic
**Problem**: Agent never triggers or triggers too often
**Solution**: Add specific trigger keywords and domain constraints
### Pitfall 2: Unclear Output
**Problem**: Agent responses are inconsistent
**Solution**: Define explicit output format with examples
### Pitfall 3: Scope Creep
**Problem**: Agent tries to do too much
**Solution**: Split into multiple focused agents
### Pitfall 4: Missing Context
**Problem**: Agent doesn't have enough information
**Solution**: Specify what context to gather first
### Pitfall 5: Over-Engineering
**Problem**: Agent is too complex
**Solution**: Start simple, add complexity only when needed
## Testing Your Agent
### Test Cases to Cover
1. **Happy Path**: Agent works as expected
2. **Edge Cases**: Unusual but valid inputs
3. **Error Handling**: Invalid or missing inputs
4. **Scope Boundaries**: When agent should NOT trigger
5. **Tool Limitations**: Agent lacks necessary permissions
### Testing Checklist
- [ ] Test with explicit invocation: "Use [agent-name] to..."
- [ ] Test with implicit trigger: Describe task without naming agent
- [ ] Test with minimal input
- [ ] Test with complex input
- [ ] Test when agent shouldn't trigger
- [ ] Test with insufficient permissions (if tools limited)
- [ ] Verify output format matches specification
- [ ] Check output quality and usefulness
### Iteration Process
1. **Initial Test**: Try basic functionality
2. **Identify Gaps**: What doesn't work?
3. **Refine Prompt**: Add missing instructions
4. **Add Examples**: Show what good looks like
5. **Test Again**: Verify improvements
6. **Repeat**: Until agent is reliable
## Documentation Standards
### Minimum Documentation
Every agent should include:
```markdown
---
name: agent-name
description: When to use this agent
---
# Agent Purpose
[What it does]
## Core Responsibilities
[Main tasks]
## Approach
[How it works]
## Output Format
[What it produces]
## Constraints
[What it won't do]
```
### Enhanced Documentation
For complex agents, add:
- Input validation rules
- Error handling approach
- Edge case handling
- Examples (good and bad)
- Troubleshooting tips
- Related agents
- Version history
## Performance Considerations
### Context Window Management
- Agents start with fresh context
- May need to re-read files
- Consider token costs for large codebases
**Optimization**: Provide clear file paths in description
### Token Efficiency
- Concise system prompts are faster
- But clarity > brevity
- Use examples judiciously
**Balance**: Detailed enough to work, concise enough to load quickly
### Caching Benefits
- Repeated invocations may benefit from caching
- System prompt is cacheable
- Frequently accessed files may be cached
**Note**: Implementation-specific, but generally beneficial
## Version Control Best Practices
### Project Agents
✅ **Do Commit**:
- `.claude/agents/*.md` - All project agents
- Document in README when to use each agent
❌ **Don't Commit**:
- User-specific agents from `~/.claude/agents/`
- API keys or secrets (should be in env vars)
### User Agents
- Keep in `~/.claude/agents/` for personal use
- Back up separately (not in project repos)
- Share via documentation/templates if useful to others
## Sharing Agents
### With Your Team
1. Commit to `.claude/agents/` in project
2. Document in project README
3. Add trigger examples
4. Provide test cases
### With Community
1. Create template repository
2. Include:
- Agent file with clear comments
- README with usage examples
- Test cases or fixtures
- License information
3. Share on forums/communities
## Maintenance
### When to Update
- Agent triggers incorrectly (too often/rarely)
- Output format changes
- New tool becomes available
- Domain knowledge evolves
- Team feedback indicates issues
### Update Checklist
- [ ] Update description/triggers
- [ ] Revise system prompt
- [ ] Add new examples
- [ ] Update tool permissions
- [ ] Test thoroughly
- [ ] Document changes
- [ ] Notify team (if shared)
### Deprecation
When agent is no longer needed:
1. Add deprecation notice to file
2. Suggest replacement agent (if any)
3. Set sunset date
4. Remove after team transitions
5. Archive for reference
## Advanced Patterns
### Chained Agents
Design agents that work in sequence:
1. `code-analyzer` → identifies issues
2. `code-fixer` → applies fixes
3. `test-runner` → verifies fixes
**Use for**: Complex multi-step workflows
### Specialized + General
Pair specific and general agents:
- `rails-code-reviewer` (specific)
- `code-reviewer` (general fallback)
**Use for**: Covering multiple domains
### Hierarchical Agents
Create parent-child relationships:
- `security-auditor` (parent)
- `sql-injection-scanner` (child)
- `xss-scanner` (child)
- `auth-checker` (child)
**Use for**: Breaking down complex domains
---
## Quick Reference
### Agent Creation Checklist
- [ ] Name: lowercase-with-hyphens, descriptive
- [ ] Description: specific triggers, action-oriented
- [ ] Tools: minimal necessary permissions
- [ ] Model: appropriate for task complexity
- [ ] System prompt: detailed, structured
- [ ] Examples: show good outputs
- [ ] Constraints: explicit boundaries
- [ ] Output format: clearly defined
- [ ] Tested: multiple scenarios
- [ ] Documented: usage and purpose
### Common Patterns
| Pattern | When to Use |
|---------|-------------|
| Process-oriented | Clear workflow steps |
| Checklist-based | Systematic validation |
| Example-driven | Output format matters |
| Constraint-first | Agent might overstep |
### Tool Combinations
| Combination | Use Case |
|-------------|----------|
| Read, Grep, Glob | Analysis/audit only |
| Read, Edit | Surgical code changes |
| Read, Edit, Bash | Refactoring + testing |
| Bash | Infrastructure/ops |
| All tools (inherited) | Complex workflows |
---
**See Also**:
- [Configuration Guide](./configuration-guide.md)
- [Agent Examples](./agent-examples.md)
- [Troubleshooting](./troubleshooting.md)

371
skills/agent-builder/reference/configuration-guide.md Normal file
View File

@@ -0,0 +1,371 @@
# Agent Configuration Guide
Complete reference for configuring Claude Code sub-agents.
## File Format
Agents are markdown files with YAML frontmatter:
```markdown
---
name: agent-name
description: When to use this agent
tools: Read, Edit, Bash
model: sonnet
---
# System Prompt
Agent instructions here...
```
## Configuration Fields
### name (Required)
**Type**: String
**Format**: Lowercase with hyphens
**Example**: `code-reviewer`, `sql-analyst`, `bug-hunter`
**Rules**:
- Use descriptive, action-oriented names
- Avoid generic names like "helper" or "assistant"
- Must be unique within scope (project or user)
**Good Examples**:
- `rails-code-reviewer`
- `security-auditor`
- `performance-analyzer`
**Bad Examples**:
- `MyAgent` (not lowercase-with-hyphens)
- `helper` (too generic)
- `agent1` (not descriptive)
### description (Required)
**Type**: String
**Purpose**: Tells Claude when to invoke this agent
**Best Practices**:
- Start with action phrase: "Use this agent when...", "Analyze X to Y", "Review Z for..."
- Include specific trigger keywords
- Use "PROACTIVELY" or "MUST BE USED" for automatic invocation
- Describe the task, not the agent
**Examples**:
```yaml
# Good: Specific triggers
description: Use PROACTIVELY to review Rails code changes for style violations, security issues, and performance problems
# Good: Clear use case
description: Analyze SQL queries for performance bottlenecks and suggest optimizations using EXPLAIN plans
# Bad: Too generic
description: A helpful agent for code tasks
# Bad: Describes agent, not task
description: An expert programmer who knows many languages
```
### tools (Optional)
**Type**: Comma-separated string
**Default**: Inherits all tools from main conversation
**Available Tools**:
- `Read` - Read files
- `Write` - Create new files
- `Edit` - Modify existing files
- `Bash` - Execute shell commands
- `Grep` - Search file contents
- `Glob` - Find files by pattern
- MCP server tools (if installed)
**Examples**:
```yaml
# Read-only agent
tools: Read, Grep, Glob
# Code modifier
tools: Read, Edit, Bash
# Full access
tools: Read, Write, Edit, Bash, Grep, Glob
# No tools specified = inherit all
# (omit the tools field)
```
**When to Limit Tools**:
- Security-sensitive agents (e.g., only Read for auditing)
- Prevent accidental modifications (exclude Write/Edit)
- Focused agents (e.g., only Grep for searching)
### model (Optional)
**Type**: String
**Default**: `inherit` (uses main conversation model)
**Options**:
- `sonnet` - Claude Sonnet (balanced performance)
- `opus` - Claude Opus (highest capability)
- `haiku` - Claude Haiku (fastest, most economical)
- `inherit` - Use main conversation's model
**Examples**:
```yaml
# Use faster model for simple tasks
model: haiku
# Use most capable model for complex analysis
model: opus
# Default to main conversation model
model: inherit
# Omit field to inherit
# (no model field = inherit)
```
**When to Specify**:
- Use `haiku` for simple, repetitive tasks (fast + cheap)
- Use `opus` for complex reasoning or critical decisions
- Use `sonnet` for balanced performance (default recommended)
## System Prompt Guidelines
The markdown body after frontmatter is the agent's system prompt.
### Structure
```markdown
---
name: my-agent
description: Agent description here
---
# Agent Purpose
High-level overview of what this agent does.
## Core Responsibilities
1. Responsibility 1
2. Responsibility 2
3. Responsibility 3
## Approach
How the agent should approach tasks:
- Step 1: What to do first
- Step 2: How to analyze
- Step 3: What to output
## Output Format
Expected output structure:
- Format specifications
- Required sections
- Example outputs
## Constraints
What the agent should NOT do:
- Constraint 1
- Constraint 2
## Examples
### Example 1: [Scenario]
**Input**: [Example input]
**Output**: [Expected output]
### Example 2: [Another scenario]
...
```
### Best Practices
1. **Be Specific**: Detailed instructions yield better results
2. **Include Examples**: Show the agent what good outputs look like
3. **Set Constraints**: Explicitly state what NOT to do
4. **Define Output Format**: Specify structure and style
5. **Break Down Steps**: Guide the agent's reasoning process
### Good System Prompt Example
```markdown
---
name: test-failure-analyzer
description: Use when tests fail to identify root cause and suggest fixes
tools: Read, Grep, Bash
model: sonnet
---
# Test Failure Analyzer
Systematically analyze test failures to identify root causes and propose fixes.
## Core Responsibilities
1. Read test output to identify failing tests
2. Examine test code and implementation
3. Identify the root cause (not just symptoms)
4. Propose specific, minimal fixes
5. Suggest additional test cases if needed
## Analysis Approach
### Step 1: Gather Context
- Read the full test output
- Identify all failing test names
- Note error messages and stack traces
### Step 2: Examine Code
- Read failing test file
- Read implementation being tested
- Identify the assertion that failed
### Step 3: Root Cause Analysis
- Determine if it's a test issue or implementation bug
- Check for timing issues, environment dependencies
- Look for recent changes that might have caused it
### Step 4: Propose Fix
- Suggest minimal code change
- Explain why this fixes the root cause
- Note any side effects or risks
## Output Format
```
## Test Failure Analysis
**Failing Tests**: [List of test names]
**Root Cause**: [One-sentence summary]
**Details**: [Explanation of why tests are failing]
**Proposed Fix**:
[Specific code changes]
**Reasoning**: [Why this fix addresses root cause]
**Risks**: [Any potential side effects]
```
## Constraints
- DO NOT modify tests to make them pass if implementation is wrong
- DO NOT propose fixes without understanding root cause
- DO NOT suggest multiple approaches - pick the best one
- DO NOT rewrite large sections - minimal changes only
## Examples
### Example 1: Assertion Failure
**Input**: Test output showing "Expected 5, got 4"
**Analysis**:
1. Read test to see what's being tested
2. Check implementation logic
3. Identify off-by-one error in loop
4. Propose boundary fix
**Output**:
```
Root Cause: Off-by-one error in loop condition
Fix: Change `i < length` to `i <= length` in file.py:42
Reasoning: Loop exits one iteration early
```
```
### Bad System Prompt Example
```markdown
---
name: helper
description: Helps with tasks
---
You are a helpful assistant. Do whatever the user asks.
```
**Problems**:
- Generic name and description won't trigger correctly
- No specific guidance on approach
- No constraints or output format
- No examples
## File Locations
### Project Agents
**Path**: `.claude/agents/` (in project root)
**Scope**: Available only in this project
**Version Control**: Commit to share with team
### User Agents
**Path**: `~/.claude/agents/` (in home directory)
**Scope**: Available in all projects
**Version Control**: Personal, not shared
### Priority
Project agents override user agents with the same name.
## Validation Checklist
Before deploying your agent, verify:
- [ ] Name is lowercase-with-hyphens
- [ ] Name is descriptive (not generic)
- [ ] Description includes specific trigger conditions
- [ ] Description uses action-oriented language
- [ ] Tools are limited to what's needed (or omitted for full access)
- [ ] Model is appropriate for task complexity (or omitted to inherit)
- [ ] System prompt is detailed and specific
- [ ] Output format is clearly defined
- [ ] Examples are included
- [ ] Constraints are explicit
- [ ] File is in correct location (.claude/agents/ or ~/.claude/agents/)
- [ ] YAML frontmatter is valid
## Common Issues
### Agent Never Triggers
- Description too generic
- Missing trigger keywords
- Name conflicts with another agent
**Fix**: Add specific keywords to description, use "PROACTIVELY" or "MUST BE USED"
### Agent Has Wrong Permissions
- Tools not specified correctly
- Typo in tool names
**Fix**: Check available tool names, use comma-separated list
### Agent Produces Wrong Outputs
- System prompt too vague
- Missing examples
- No output format specified
**Fix**: Add detailed instructions, examples, and explicit output format
### Agent Not Found
- Wrong file location
- File naming issue
**Fix**: Ensure file is in `.claude/agents/` (project) or `~/.claude/agents/` (user)
---
**Related**:
- [Agent Examples](./agent-examples.md)
- [Best Practices](./best-practices.md)
- [Troubleshooting](./troubleshooting.md)

711
skills/agent-builder/reference/prism-agent-strategy.md Normal file
View File

@@ -0,0 +1,711 @@
# PRISM Agent Strategy: Artifact-Centric Development
## Core Insight: Shared Artifacts as Single Source of Truth
In PRISM, each agent (SM, Dev, QA, PO, Architect) works on the **same shared artifacts**:
- [docs/prd.md](docs/prd.md) and [docs/prd/](docs/prd/) shards
- [docs/architecture.md](docs/architecture.md) and [docs/architecture/](docs/architecture/) shards
- [docs/stories/](docs/stories/) - individual story files
- [docs/qa/assessments/](docs/qa/assessments/) - quality reports
- [docs/qa/gates/](docs/qa/gates/) - gate decisions
This creates a unique opportunity: **sub-agents can be artifact-specialized rather than role-specialized**.
## The Paradigm Shift
### Traditional Approach (Role-Based)
- Create agents per role: `code-reviewer`, `test-analyzer`, `bug-fixer`
- Agent knows its job but not the workflow context
- Must explain PRISM workflow each time
### PRISM Approach (Artifact-Based)
- Create agents per artifact type: `story-implementer`, `prd-validator`, `gate-manager`
- Agent understands BOTH its job AND the artifact structure
- Knows where to read/write, what format to use
- Pre-configured for PRISM workflow
## Agent Architecture for PRISM
### 1. Story-Focused Agents
These agents work directly with story files in `docs/stories/`:
#### story-implementer
```markdown
---
name: story-implementer
description: Use PROACTIVELY when implementing any story from docs/stories/. Reads story file, implements all tasks sequentially, updates File List and Change Log sections.
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
---
# Story Implementation Agent
You are a specialized developer agent that implements PRISM stories following exact structure.
## Story File Structure You Work With
Every story in `docs/stories/` has this structure:
```markdown
# Story: [Title]
## Status: [Draft|Approved|InProgress|Done]
## Story
As a [user] I want [feature] So that [benefit]
## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
## Tasks
- [ ] Task 1
- [ ] Task 2
## Dev Notes
[Implementation guidance]
## Dev Agent Record
### Completion Notes
[You fill this]
### File List
[You maintain this - ALL modified files]
### Change Log
[You document all changes]
## QA Results
[QA agent fills this]
```
## Your Process
1. **Read Story**: Load story file from `docs/stories/`
2. **Verify Status**: Must be "Approved" or "InProgress"
3. **Update Status**: Change to "InProgress" if was "Approved"
4. **Execute Tasks**:
- Work through tasks sequentially
- Mark each task complete: `- [x] Task name`
- Follow Dev Notes for guidance
- Check Acceptance Criteria frequently
5. **Maintain File List**:
- Add EVERY file you create/modify
- Group by category (src, tests, docs)
- Keep updated in real-time
6. **Document Changes**:
- Update Change Log with what you did
- Explain WHY for non-obvious changes
- Note any deviations from plan
7. **Mark Complete**:
- Verify all tasks checked
- Verify all acceptance criteria met
- Update Status to "Review"
- Fill Completion Notes
## Critical Rules
- NEVER skip tasks
- ALWAYS update File List
- ALWAYS document changes
- NEVER mark story "Done" (only QA can)
- Status flow: Approved → InProgress → Review
- Reference [docs/architecture/](docs/architecture/) for patterns
- Follow coding standards from architecture
## Output Format
After implementation, story file should have:
- All tasks checked
- Complete File List
- Detailed Change Log
- Completion Notes summary
- Status = "Review"
```
#### story-validator
```markdown
---
name: story-validator
description: Use PROACTIVELY when SM creates new story drafts. Validates story against PRD epics, architecture constraints, and PRISM story structure.
tools: Read, Grep, Glob
model: sonnet
---
# Story Validation Agent
Validate story drafts for completeness, alignment, and proper structure.
## What You Validate
### 1. Structure Compliance
Story must have ALL sections:
- Status (must be "Draft" for new stories)
- Story (As a/I want/So that format)
- Acceptance Criteria (3-7 measurable criteria)
- Tasks (broken down, 1-3 day chunks)
- Dev Notes (implementation guidance)
- Dev Agent Record (template present)
- QA Results (empty section)
### 2. PRD Alignment
Read corresponding epic from `docs/prd/`:
- Story implements epic requirements
- All epic acceptance criteria covered
- No scope creep beyond epic
- References correct epic number
### 3. Architecture Alignment
Check against `docs/architecture/`:
- Follows established patterns
- Uses correct tech stack
- Respects system boundaries
- No architectural violations
### 4. Task Quality
Tasks must be:
- Specific and actionable
- Properly sized (1-3 day work)
- Include testing requirements
- Have clear completion criteria
- Sequential and logical order
### 5. Acceptance Criteria Quality
Criteria must be:
- Measurable/testable
- User-focused outcomes
- Complete (cover full story)
- Achievable within story
- Not just technical tasks
## Validation Process
1. **Load Story**: Read story file from `docs/stories/`
2. **Load Epic**: Read corresponding epic from `docs/prd/`
3. **Load Architecture**: Read relevant sections from `docs/architecture/`
4. **Check Structure**: Verify all sections present
5. **Validate Content**: Check each section quality
6. **Cross-Reference**: Ensure alignment across artifacts
7. **Generate Report**: Detailed validation results
## Output Format
```
# Story Validation Report
**Story**: [filename]
**Epic**: [epic reference]
**Date**: [date]
## Structure Check
✅/❌ All required sections present
✅/❌ Proper markdown formatting
✅/❌ Status is "Draft"
## PRD Alignment
✅/❌ Implements epic requirements
✅/❌ Covers epic acceptance criteria
✅/❌ No scope creep
**Issues**: [specific problems]
## Architecture Alignment
✅/❌ Follows patterns
✅/❌ Uses correct stack
✅/❌ Respects boundaries
**Issues**: [specific problems]
## Task Quality
✅/❌ Tasks are specific
✅/❌ Tasks properly sized
✅/❌ Testing included
**Issues**: [specific problems]
## Acceptance Criteria Quality
✅/❌ Measurable
✅/❌ User-focused
✅/❌ Complete
**Issues**: [specific problems]
## Recommendation
[APPROVE / NEEDS REVISION]
## Required Changes
1. [Specific change needed]
2. [Specific change needed]
```
```
### 2. Quality Gate Agents
#### qa-gate-manager
```markdown
---
name: qa-gate-manager
description: Use when QA review is complete to create or update quality gate files in docs/qa/gates/. Manages PASS/CONCERNS/FAIL decisions.
tools: Read, Write, Edit, Grep, Glob
model: sonnet
---
# QA Gate Manager
Create and manage quality gate decisions for stories.
## Gate File Structure
Location: `docs/qa/gates/epic-{n}.story-{n}-gate.yml`
Format:
```yaml
story: story-name
epic: epic-name
date: YYYY-MM-DD
reviewer: QA Agent
status: PASS # PASS, CONCERNS, FAIL
findings:
- "Finding 1"
- "Finding 2"
recommendations:
- "Recommendation 1"
- "Recommendation 2"
decision: |
Detailed explanation of gate decision
and reasoning.
next_steps:
- "Action 1"
- "Action 2"
```
## Your Process
1. **Read Assessment**: Load assessment from `docs/qa/assessments/`
2. **Read Story**: Load story file to understand implementation
3. **Determine Status**:
- **PASS**: All criteria met, high quality, ready for production
- **CONCERNS**: Minor issues but acceptable, document concerns
- **FAIL**: Significant issues, must return to development
4. **Document Findings**: List all important observations
5. **Make Recommendations**: Suggest improvements (even for PASS)
6. **Write Decision**: Explain reasoning clearly
7. **Define Next Steps**: What happens next (merge, fix, etc.)
8. **Create Gate File**: Write to correct path with proper naming
## Status Criteria
### PASS
- All acceptance criteria met
- All tests passing
- Code quality meets standards
- No critical/high issues
- Documentation complete
- Follows architecture
### CONCERNS
- All acceptance criteria met
- Minor quality issues
- Technical debt acceptable
- Low priority improvements noted
- Can ship with tracking
### FAIL
- Acceptance criteria missing
- Tests failing
- Critical/high issues present
- Architecture violations
- Incomplete implementation
- Security/performance problems
## Critical Rules
- Gate status is final for that review
- FAIL requires dev to address issues
- CONCERNS requires issue tracking
- PASS allows story to be marked "Done"
- Always explain reasoning
- Reference assessment file
- Use proper YAML syntax
## Output
After creating gate:
1. Confirm file created at correct path
2. Display gate decision
3. Update story status if PASS
4. List next steps clearly
```
### 3. Artifact Maintenance Agents
#### file-list-auditor
```markdown
---
name: file-list-auditor
description: Use before marking story complete to verify File List section matches actual git changes. Ensures nothing is missing.
tools: Read, Bash, Grep, Glob
model: haiku
---
# File List Auditor
Audit story File List against actual file changes.
## Your Process
1. **Read Story**: Load story from `docs/stories/`
2. **Extract File List**: Get files from Dev Agent Record → File List
3. **Check Git**: Run `git diff --name-only` for actual changes
4. **Compare**: Match story list to git changes
5. **Identify Discrepancies**:
- Files in git but not in story
- Files in story but not in git
6. **Verify Categories**: Check grouping makes sense
7. **Report**: Clear audit results
## Output Format
```
# File List Audit
**Story**: [filename]
**Date**: [date]
## Story File List
[List from story]
## Git Changes
[List from git]
## Discrepancies
### Missing from Story
- [file1] - Found in git, not in story
- [file2]
### Missing from Git
- [file3] - Listed in story, not changed in git
- [file4]
### Incorrectly Categorized
- [file5] - Listed as src, actually test
## Status
✅/❌ File List accurate
✅/❌ All changes documented
## Recommendation
[APPROVE / UPDATE REQUIRED]
## Suggested Updates
[Exact File List section content to use]
```
```
### 4. Cross-Artifact Agents
#### requirements-tracer
```markdown
---
name: requirements-tracer
description: Use to trace requirements from PRD → Epic → Story → Implementation → Tests. Ensures complete traceability.
tools: Read, Grep, Glob
model: sonnet
---
# Requirements Traceability Agent
Trace requirements through entire PRISM artifact chain.
## Traceability Chain
```
PRD (docs/prd.md)
↓
Epic (docs/prd/epic-n.md)
↓
Story (docs/stories/epic-n/story-n.md)
↓
Implementation (source files)
↓
Tests (test files)
```
## Your Process
1. **Start with Story**: Read story file
2. **Find Epic**: Read corresponding epic from docs/prd/
3. **Find PRD Section**: Identify which PRD section epic implements
4. **Find Implementation**: Read files from story File List
5. **Find Tests**: Locate test files for implementation
6. **Trace Forward**: PRD → Epic → Story → Code
7. **Trace Backward**: Tests → Code → Story → Epic → PRD
8. **Verify Coverage**: All requirements have tests
## Output Format
```
# Requirements Traceability Report
**Story**: [filename]
**Epic**: [epic reference]
**PRD Section**: [section reference]
## Forward Trace
### PRD Requirement
[Requirement text from PRD]
### Epic Acceptance Criteria
- [Epic criterion 1]
- [Epic criterion 2]
### Story Acceptance Criteria
- [Story criterion 1]
- [Story criterion 2]
### Implementation
- [file1.ts:123] - Implements criterion 1
- [file2.ts:456] - Implements criterion 2
### Tests
- [file1.test.ts:78] - Tests criterion 1
- [file2.test.ts:90] - Tests criterion 2
## Coverage Analysis
✅/❌ All PRD requirements covered by epic
✅/❌ All epic criteria covered by story
✅/❌ All story criteria implemented
✅/❌ All implementation has tests
## Gaps Identified
[Any missing coverage]
## Recommendation
[COMPLETE / GAPS REQUIRE ATTENTION]
```
```
## Agent Invocation Strategy
### When to Use Which Agent
#### During Story Creation (SM Phase)
- **story-validator**: Validate new story draft before user approval
#### During Development (Dev Phase)
- **story-implementer**: Primary implementation agent
- **file-list-auditor**: Before marking story "Review"
#### During QA Phase
- **requirements-tracer**: Verify complete traceability
- **qa-gate-manager**: Create final gate decision
#### Ad-Hoc Maintenance
- Any agent when specific artifact needs attention
### Invocation Examples
**Story Creation Workflow**:
```
1. SM creates story draft
2. "Use story-validator to check this draft"
3. Fix issues identified
4. User approves → Status: Approved
```
**Development Workflow**:
```
1. "Use story-implementer to develop story-003"
2. Agent implements all tasks
3. "Use file-list-auditor to verify completeness"
4. Fix any discrepancies
5. Status → Review
```
**QA Workflow**:
```
1. QA performs manual review
2. "Use requirements-tracer for story-003"
3. QA creates assessment in docs/qa/assessments/
4. "Use qa-gate-manager to create gate decision"
5. Gate status determines next action
```
## Benefits of Artifact-Centric Agents
### 1. Pre-Configured Knowledge
- Agent knows exact file paths
- Understands artifact structure
- Follows PRISM conventions automatically
### 2. Workflow Integration
- Agents fit naturally into SM → Dev → QA cycle
- Clear handoff points
- Consistent artifact updates
### 3. Reduced Context Pollution
- Each agent has narrow, clear scope
- Main conversation stays focused on decisions
- Agents handle mechanical artifact management
### 4. Reusability Across Stories
- Same agents work for every story
- No reconfiguration needed
- Consistent quality across project
### 5. Traceability
- requirements-tracer ensures nothing lost
- Clear audit trail through artifacts
- Easy to verify completeness
## Implementation Guidelines
### Creating PRISM-Specific Agents
**DO**:
- Reference exact artifact paths (docs/stories/, docs/prd/, etc.)
- Include complete artifact structure in system prompt
- Specify exact format for updates
- Define clear status transitions
- Reference related artifacts
**DON'T**:
- Create generic "helper" agents
- Assume user will explain PRISM structure
- Leave artifact paths ambiguous
- Allow status transitions not in workflow
### Testing Your Agents
1. **Structure Test**: Agent reads artifact correctly
2. **Update Test**: Agent modifies artifact properly
3. **Cross-Reference Test**: Agent finds related artifacts
4. **Format Test**: Agent output matches standard
5. **Workflow Test**: Agent fits in SM/Dev/QA cycle
### Maintaining Agents
- Update when artifact structure changes
- Keep in sync with workflow changes
- Version control with `.claude/agents/`
- Document agent interactions
- Test after PRISM updates
## Advanced Patterns
### Agent Chaining
```
story-validator (check structure)
↓
story-implementer (implement)
↓
file-list-auditor (verify files)
↓
requirements-tracer (check coverage)
↓
qa-gate-manager (final decision)
```
### Parallel Agents
During development:
- story-implementer (primary work)
- file-list-auditor (periodic checks)
During QA:
- requirements-tracer (coverage check)
- qa-gate-manager (decision making)
### Agent Specialization Levels
**L1 - Single Artifact**: Works on one file type
- story-implementer (only stories)
- qa-gate-manager (only gates)
**L2 - Related Artifacts**: Works across artifact chain
- requirements-tracer (PRD → Epic → Story → Code → Tests)
**L3 - Workflow Orchestration**: Manages complete cycles
- (Consider if complexity justifies)
## Integration with Existing PRISM Skills
### How This Complements Current Structure
**Current PRISM Skills** (`skills/sm/`, `skills/dev/`, `skills/qa/`):
- Define ROLE behavior and workflow
- Loaded as primary agent for each phase
- Provide human-facing interface
**New Sub-Agents** (`.claude/agents/`):
- Handle SPECIFIC artifact operations
- Invoked by main agent or user
- Pre-configured for artifact structure
### Workflow Integration
```
User → /sm (loads SM skill)
↓
SM creates story draft
↓
User: "Use story-validator"
↓
story-validator agent checks draft
↓
User approves story
↓
User → /dev (loads Dev skill)
↓
User: "Use story-implementer for story-003"
↓
story-implementer executes tasks
↓
User: "Use file-list-auditor"
↓
file-list-auditor verifies completeness
↓
User → /qa (loads QA skill)
↓
QA reviews manually
↓
User: "Use requirements-tracer"
↓
requirements-tracer verifies coverage
↓
User: "Use qa-gate-manager"
↓
qa-gate-manager creates gate decision
```
## Conclusion
**Key Insight**: In PRISM, artifacts are the shared language. By creating agents that deeply understand artifact structure, we:
1. **Reduce Friction**: Agents know where everything is
2. **Ensure Consistency**: All agents follow same conventions
3. **Enable Automation**: Mechanical tasks handled by agents
4. **Preserve Context**: Main conversation stays high-level
5. **Scale Naturally**: Same agents work for all stories
**Next Steps**:
1. Create agents for your most frequent artifact operations
2. Test with one story end-to-end
3. Refine based on real usage
4. Add agents as needs emerge
5. Share successful patterns with team
---
**Remember**: These agents are PRISM-specific. They understand your workflow, your artifacts, and your structure. Use them to make the PRISM workflow even more efficient.

789
skills/agent-builder/reference/troubleshooting.md Normal file
View File

@@ -0,0 +1,789 @@
# Agent Troubleshooting Guide
Common issues and solutions when working with Claude Code sub-agents.
## Issue: Agent Never Triggers
### Symptoms
- Agent doesn't activate when expected
- Claude doesn't recognize when to use agent
- Manual invocation works, automatic doesn't
### Diagnosis
1. **Check description specificity**:
```bash
# Read your agent file
head -20 .claude/agents/my-agent.md
```
Look for:
- Is description too generic?
- Missing trigger keywords?
- No action-oriented language?
2. **Test with explicit invocation**:
```
"Use the my-agent agent to [task]"
```
If this works, problem is in description/triggers.
### Solutions
**Solution 1: Add Specific Triggers**
❌ **Before**:
```yaml
description: Helps with code tasks
```
✅ **After**:
```yaml
description: Use PROACTIVELY after writing Rails controllers to review for RESTful patterns, security issues, and performance problems
```
**Solution 2: Use Trigger Keywords**
Add words like:
- `PROACTIVELY`
- `MUST BE USED`
- Specific technologies: "Rails", "SQL", "Docker"
- Specific actions: "review", "analyze", "debug"
- Specific contexts: "after writing", "when encountering", "before deploying"
**Solution 3: Add Conditional Language**
```yaml
description: Use when SQL queries are slow or EXPLAIN shows missing indexes. Do not use for application code optimization.
```
### Verification
Test automatic triggering:
```
# Don't name the agent, describe the task
"I just wrote a new Rails controller action. Can you review it?"
```
If agent triggers, issue is resolved.
---
## Issue: Agent Triggers Too Often
### Symptoms
- Agent activates for irrelevant tasks
- Wrong agent chosen for task
- Agent interferes with main conversation
### Diagnosis
Description is too broad or missing constraints.
### Solutions
**Solution 1: Narrow Scope**
❌ **Before**:
```yaml
description: Use for code review
```
✅ **After**:
```yaml
description: Use for Rails code review ONLY. Do not use for JavaScript, Python, or other languages.
```
**Solution 2: Add Exclusions**
```yaml
description: Use when debugging test failures in RSpec. Do not use for Jest, pytest, or other test frameworks.
```
**Solution 3: Make Prerequisites Explicit**
```yaml
description: Use when performance profiling shows database bottlenecks (slow queries, N+1 problems). Requires existing performance data.
```
### Verification
Test with edge cases:
- Tasks that should NOT trigger agent
- Similar but different domains
- Related but out-of-scope work
---
## Issue: Agent Has Wrong Permissions
### Symptoms
- "Tool not available" errors
- Agent can't complete task
- Agent attempts actions but fails
### Diagnosis
1. **Check tool configuration**:
```yaml
tools: Read, Grep, Glob
```
2. **Identify what agent tried to do**:
- Tried to edit files? (needs `Edit`)
- Tried to run commands? (needs `Bash`)
- Tried to create files? (needs `Write`)
### Solutions
**Solution 1: Grant Required Tools**
For code review (read-only):
```yaml
tools: Read, Grep, Glob
```
For debugging (read + execute):
```yaml
tools: Read, Bash, Grep, Glob
```
For code fixing (read + modify + execute):
```yaml
tools: Read, Edit, Bash, Grep, Glob
```
For creating new files:
```yaml
tools: Read, Write, Edit, Bash, Grep, Glob
```
**Solution 2: Grant All Tools**
If agent needs flexibility, omit tools field:
```yaml
---
name: my-agent
description: Agent description
# No tools field = inherits all tools
---
```
**Solution 3: Split Agent**
If one agent needs different permissions for different tasks:
Create two agents:
- `code-analyzer` (read-only)
- `code-fixer` (read + edit)
### Verification
Test all expected actions:
- [ ] Agent can read files
- [ ] Agent can search (if needed)
- [ ] Agent can edit (if needed)
- [ ] Agent can run commands (if needed)
---
## Issue: Agent Produces Wrong Output
### Symptoms
- Output format inconsistent
- Missing required information
- Wrong analysis or suggestions
- Output style doesn't match expectations
### Diagnosis
System prompt lacks specificity or examples.
### Solutions
**Solution 1: Define Explicit Output Format**
Add to system prompt:
```markdown
## Output Format
Use this exact structure:
# Analysis Result
## Summary
[One sentence]
## Details
- Point 1
- Point 2
## Recommendation
[Specific action]
```
**Solution 2: Add Examples**
```markdown
## Example Output
**Input**: SQL query with missing index
**Output**:
```
# Query Optimization
## Issue
Query scans full table (1M rows)
## Root Cause
Missing index on `user_id` column
## Recommendation
```sql
CREATE INDEX idx_orders_user_id ON orders(user_id);
```
## Expected Impact
Query time: 2.5s → 50ms (98% faster)
```
```
**Solution 3: Add Constraints**
```markdown
## Constraints
- ALWAYS include specific file paths and line numbers
- NEVER suggest vague improvements like "optimize this"
- DO NOT provide multiple options - pick the best one
- MUST include before/after examples
```
**Solution 4: Improve Instructions**
Break down the process:
```markdown
## Analysis Process
1. Read the error message carefully
2. Identify the exact line that failed
3. Read 10 lines before and after for context
4. Check git blame for recent changes
5. Formulate hypothesis about root cause
6. Propose minimal fix with explanation
```
### Verification
Test with multiple inputs:
- [ ] Output follows format consistently
- [ ] All required sections present
- [ ] Quality meets expectations
- [ ] Style is appropriate
---
## Issue: Agent Not Found
### Symptoms
- "Agent not found" error
- Agent file exists but isn't recognized
- Manual attempts to invoke fail
### Diagnosis
1. **Check file location**:
```bash
# Project agents
ls -la .claude/agents/
# User agents
ls -la ~/.claude/agents/
```
2. **Check file naming**:
- Must end in `.md`
- Name should match YAML `name` field
- Lowercase with hyphens
### Solutions
**Solution 1: Correct File Location**
Move to correct directory:
```bash
# For project agent
mv my-agent.md .claude/agents/my-agent.md
# For user agent
mv my-agent.md ~/.claude/agents/my-agent.md
```
**Solution 2: Fix File Name**
Ensure consistency:
```yaml
# In my-agent.md
---
name: my-agent # Must match filename (without .md)
---
```
**Solution 3: Create Directory**
If directory doesn't exist:
```bash
# Project agents
mkdir -p .claude/agents
# User agents
mkdir -p ~/.claude/agents
```
**Solution 4: Check YAML Syntax**
Validate frontmatter:
```yaml
---
name: agent-name
description: Description here
tools: Read, Edit
model: sonnet
---
```
Common YAML errors:
- Missing opening `---`
- Missing closing `---`
- Incorrect indentation
- Missing quotes around special characters
### Verification
```bash
# List all agents Claude can see
/agents
# Try explicit invocation
"Use the my-agent agent to test"
```
---
## Issue: Agent Runs But Produces No Output
### Symptoms
- Agent starts successfully
- No errors reported
- But no useful output or response
### Diagnosis
Agent completed but didn't communicate results.
### Solutions
**Solution 1: Add Output Instructions**
```markdown
## Final Output
After completing analysis, ALWAYS provide a summary using this format:
[format specification]
Do not end without providing output.
```
**Solution 2: Check for Silent Failures**
Add error handling instructions:
```markdown
## Error Handling
If you encounter errors:
1. Clearly state what failed
2. Explain why it failed
3. Suggest workaround or next steps
Never fail silently.
```
**Solution 3: Require Summary**
```markdown
## Completion Requirement
You must always end with:
# Summary
- [What was done]
- [What was found]
- [What to do next]
```
### Verification
Test edge cases:
- Agent with no findings
- Agent that encounters errors
- Agent with partial results
All should produce output.
---
## Issue: Agent Takes Too Long
### Symptoms
- Agent runs but is very slow
- Times out or seems stuck
- Uses many tokens
### Diagnosis
Agent may be:
- Reading too many files
- Running expensive operations
- Lacking clear stopping criteria
### Solutions
**Solution 1: Add Scope Limits**
```markdown
## Scope
Analyze only:
- Files in `app/` directory
- Maximum 10 files
- Skip `node_modules/`, `vendor/`
```
**Solution 2: Prioritize Efficiently**
```markdown
## Process
1. Check git diff for changed files (start here)
2. Read only files with relevant patterns
3. Stop after finding 5 issues
4. Report findings incrementally
```
**Solution 3: Use Faster Model**
```yaml
model: haiku # Faster for simple tasks
```
**Solution 4: Break Into Smaller Agents**
Instead of one "complete-analyzer":
- `quick-scanner` (initial pass)
- `deep-analyzer` (detailed review)
- `fix-applier` (apply changes)
### Verification
Measure performance:
- Time to completion
- Token usage
- Files accessed
Optimize as needed.
---
## Issue: Agent Conflicts With Main Conversation
### Symptoms
- Main Claude and agent give conflicting advice
- Confusion about which entity is responding
- Agent overrides main conversation decisions
### Diagnosis
Agent is too broadly scoped or triggers too easily.
### Solutions
**Solution 1: Narrow Agent Scope**
Make agent highly specific:
```yaml
description: Use ONLY for Rails model validations. Do not use for controllers, views, or other components.
```
**Solution 2: Add Deference Rule**
```markdown
## Priority
If main conversation has already addressed this:
- Acknowledge their approach
- Only add value if you have specific domain expertise
- Don't repeat what's already been said
```
**Solution 3: Use Manual Invocation**
Remove automatic trigger words:
```yaml
# Before (automatic)
description: Use PROACTIVELY for code review
# After (manual only)
description: Review code for style and security issues when explicitly invoked
```
### Verification
- [ ] Agent only responds when appropriate
- [ ] No conflicts with main Claude
- [ ] Agent adds value, doesn't duplicate
---
## Issue: YAML Parsing Errors
### Symptoms
- "Invalid YAML" error
- Agent file not loaded
- Frontmatter not recognized
### Common YAML Mistakes
**Mistake 1: Missing Delimiters**
❌ **Wrong**:
```
name: my-agent
description: Agent description
# System Prompt
```
✅ **Correct**:
```yaml
---
name: my-agent
description: Agent description
---
# System Prompt
```
**Mistake 2: Unquoted Special Characters**
❌ **Wrong**:
```yaml
description: Use for code: review & testing
```
✅ **Correct**:
```yaml
description: "Use for code: review & testing"
```
**Mistake 3: Multiline Without Pipe**
❌ **Wrong**:
```yaml
description: This is a very long description
that spans multiple lines
```
✅ **Correct**:
```yaml
description: |
This is a very long description
that spans multiple lines
```
Or:
```yaml
description: "This is a very long description that spans multiple lines"
```
**Mistake 4: Incorrect Indentation**
❌ **Wrong**:
```yaml
name: my-agent
description: Agent description # Extra space
```
✅ **Correct**:
```yaml
name: my-agent
description: Agent description
```
### Validation
Use YAML validator:
```bash
# Install yq if needed
brew install yq
# Validate YAML
yq eval '.claude/agents/my-agent.md'
# Or use online validator
# https://www.yamllint.com/
```
---
## Issue: Agent Works Locally But Not for Team
### Symptoms
- Agent works for you
- Teammates report agent not found
- Inconsistent behavior across machines
### Diagnosis
Agent in wrong location or not committed.
### Solutions
**Solution 1: Move to Project Location**
```bash
# Move from user agents to project agents
mv ~/.claude/agents/my-agent.md .claude/agents/my-agent.md
# Commit to version control
git add .claude/agents/my-agent.md
git commit -m "Add my-agent for team use"
git push
```
**Solution 2: Document in README**
```markdown
## Available Agents
### my-agent
Use for: [description]
Invoke with: "Use my-agent to [task]"
```
**Solution 3: Share User Agent Template**
If keeping as user agent:
1. Create template in docs/
2. Team members copy to ~/.claude/agents/
3. Customize as needed
### Verification
Have teammate:
1. Pull latest code
2. Check `.claude/agents/` exists
3. Try invoking agent
---
## Debugging Tips
### Enable Verbose Output
Request detailed reasoning:
```
"Use the my-agent agent to [task]. Please explain your reasoning step by step."
```
### Check Agent Configuration
```bash
# View agent file
cat .claude/agents/my-agent.md
# Check YAML is valid
head -10 .claude/agents/my-agent.md
```
### Test Incrementally
1. Test with minimal input
2. Test with complex input
3. Test edge cases
4. Test error conditions
### Compare With Working Agent
If you have a working agent:
1. Compare configuration
2. Compare system prompt structure
3. Identify differences
4. Apply successful patterns
### Simplify and Rebuild
If agent is complex and broken:
1. Start with minimal version
2. Test basic functionality
3. Add features incrementally
4. Test after each addition
---
## Getting Help
### Information to Provide
When asking for help, include:
1. **Agent File**:
```bash
cat .claude/agents/my-agent.md
```
2. **What You're Trying**:
- Exact command or request
- Expected behavior
- Actual behavior
3. **Error Messages**:
- Full error text
- When it occurs
4. **Environment**:
- Project type (Rails, Node, etc.)
- Agent location (project vs user)
- Claude Code version
### Where to Ask
- Claude Code documentation
- Project team (for project agents)
- Claude Code community forums
- GitHub issues (if applicable)
---
## Prevention Checklist
Avoid issues by following this checklist when creating agents:
- [ ] Name is lowercase-with-hyphens
- [ ] YAML frontmatter is valid
- [ ] Description is specific and action-oriented
- [ ] Tools are appropriate for task
- [ ] System prompt is detailed
- [ ] Output format is defined
- [ ] Examples are included
- [ ] Constraints are explicit
- [ ] File is in correct location
- [ ] Tested with multiple inputs
- [ ] Documented for team (if shared)
---
**See Also**:
- [Configuration Guide](./configuration-guide.md)
- [Best Practices](./best-practices.md)
- [Agent Examples](./agent-examples.md)