Initial commit
This commit is contained in:
Zhongwei Li
628
skills/agent-builder/reference/agent-examples.md
Normal file
628
skills/agent-builder/reference/agent-examples.md
Normal 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
617
skills/agent-builder/reference/best-practices.md
Normal 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
371
skills/agent-builder/reference/configuration-guide.md
Normal 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
711
skills/agent-builder/reference/prism-agent-strategy.md
Normal 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
789
skills/agent-builder/reference/troubleshooting.md
Normal 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)
|
||||
Reference in New Issue
Block a user