7.5 KiB
7.5 KiB
Agent Skill Reference Template
Template for adding skill references to agent prompts.
Standard Format
---
name: [agent-name]
role: [Role description]
model: sonnet
tools: [Read, Write, Bash, Grep, Edit, Task]
---
# [Agent Name] Agent
[Agent description and purpose]
## Mission
[Primary goal of this agent]
## Workflow
[Step-by-step workflow]
## Relevant Skills
You have access to these specialized skills when [agent task]:
- **[skill-name]**: [One-line description of guidance provided]
- **[skill-name]**: [One-line description of guidance provided]
- **[skill-name]**: [One-line description of guidance provided]
**Note**: Skills load automatically based on task keywords. Consult skills for detailed guidance on specific patterns.
## Quality Standards
[Agent-specific quality standards]
## Output Format
See **agent-output-formats** skill for standardized output format.
[Additional agent content...]
Example: implementer Agent
---
name: implementer
role: Code implementation specialist
model: sonnet
tools: [Read, Write, Bash, Grep, Edit, Task]
---
# Implementer Agent
Production-quality code implementation following architecture plans.
## Mission
Write production-quality code following the architecture plan. Make tests pass if they exist.
## Workflow
1. **Review Plan**: Read architecture plan, identify what to build and where
2. **Find Patterns**: Use Grep/Glob to find similar code, match existing style
3. **Implement**: Write code following the plan, handle errors, use clear names
4. **Validate**: Run tests (if exist), verify code works
## Relevant Skills
You have access to these specialized skills when implementing features:
- **python-standards**: Code style, type hints, docstring conventions
- **api-design**: API implementation patterns and error handling
- **database-design**: Database interaction patterns and query optimization
- **testing-guide**: Writing tests alongside implementation (TDD)
- **security-patterns**: Input validation, secure coding practices
- **observability**: Logging, metrics, tracing
- **error-handling-patterns**: Standardized error handling and recovery
**Note**: Skills load automatically based on task keywords. Consult skills for detailed guidance on specific patterns.
## Quality Standards
- Follow existing patterns (consistency matters)
- Write self-documenting code (clear names, simple logic)
- Handle errors explicitly (don't silently fail)
- Add comments only for complex logic
## Output Format
See **agent-output-formats** skill for standardized output format.
## Efficiency Guidelines
**Read selectively**:
- Read ONLY files mentioned in the plan
- Don't explore the entire codebase
- Trust the plan's guidance
**Implement focused**:
- Implement ONE component at a time
- Test after each component
- Stop when tests pass (don't over-engineer)
## Summary
Trust your judgment to write clean, maintainable code that solves the problem effectively.
Benefits of This Format
Concise (~150 tokens)
## Relevant Skills
You have access to these specialized skills when implementing features:
- **python-standards**: Code style, type hints, docstring conventions
- **api-design**: API implementation patterns and error handling
- **testing-guide**: Writing tests alongside implementation (TDD)
**Note**: Skills load automatically based on task keywords.
Token count: ~100 tokens
Vs Verbose Inline Guidance (~500 tokens)
## Relevant Skills
### Python Code Style
- Use black for formatting
- Add type hints to all functions
- Write Google-style docstrings
- Follow PEP 8 conventions
- [... 200 more words ...]
### API Design Patterns
- Use REST conventions (GET, POST, PUT, DELETE)
- Return appropriate status codes (200, 201, 400, 404, 500)
- [... 200 more words ...]
### Testing Best Practices
- Use pytest for all tests
- Follow Arrange-Act-Assert pattern
- [... 200 more words ...]
Token count: ~500 tokens
Savings: 400 tokens (80% reduction)
Template Variations
Research-Heavy Agent
## Relevant Skills
You have access to these specialized skills when researching:
- **research-patterns**: Web research methodology, source evaluation
- **documentation-guide**: Documentation standards for research findings
**Note**: Skills load automatically based on task keywords.
Security-Focused Agent
## Relevant Skills
You have access to these specialized skills when auditing security:
- **security-patterns**: OWASP Top 10, common vulnerabilities
- **python-standards**: Secure coding practices in Python
- **testing-guide**: Security testing patterns
**Note**: Skills load automatically based on task keywords.
Documentation Agent
## Relevant Skills
You have access to these specialized skills when updating documentation:
- **documentation-guide**: Documentation standards, structure, best practices
- **consistency-enforcement**: Maintaining documentation consistency
- **git-workflow**: Commit messages for documentation changes
- **cross-reference-validation**: Validating internal documentation links
**Note**: Skills load automatically based on task keywords.
Anti-Patterns to Avoid
❌ Bad: Listing All Skills
## Relevant Skills
- **python-standards**
- **api-design**
- **database-design**
- **testing-guide**
- **security-patterns**
- **git-workflow**
- **github-workflow**
- **documentation-guide**
- **observability**
- **error-handling-patterns**
- **architecture-patterns**
- **code-review**
- **research-patterns**
- **semantic-validation**
[... 7 more skills ...]
Problems:
- Redundant (all skills already discoverable)
- Bloats context (~300 tokens)
- Doesn't help agent prioritize
❌ Bad: Duplicating Skill Content
## Relevant Skills
### Python Standards
Use black for formatting:
```bash
black src/
Add type hints to all functions:
def process(data: List[str]) -> Dict[str, int]:
pass
Write Google-style docstrings:
def calculate(x: int, y: int) -> int:
"""Calculate sum of two integers.
Args:
x: First integer
y: Second integer
Returns:
Sum of x and y
"""
return x + y
[... 400 more words ...]
**Problems:**
- Duplicates python-standards skill content
- Wastes ~500 tokens
- Conflicting guidance risk
- Maintenance burden (update skill AND agent)
### ✅ Good: Concise Skill References
```markdown
## Relevant Skills
You have access to these specialized skills when implementing features:
- **python-standards**: Code style, type hints, docstring conventions
- **testing-guide**: Pytest patterns, TDD workflow
- **security-patterns**: Input validation, secure coding
**Note**: Skills load automatically based on task keywords.
Benefits:
- Concise (~100 tokens)
- No duplication
- Clear what's available
- Progressive disclosure handles details
Integration Checklist
When adding skill references to an agent:
- List 3-7 most relevant skills (not all 21)
- Keep each skill description to one line
- Add progressive disclosure note
- Remove inline skill content duplication
- Use consistent skill names (match SKILL.md)
- Verify token reduction (~300-500 tokens saved)
- Test that skills activate correctly
Summary
Use this template to add efficient skill references to agent prompts:
- Concise: 3-7 relevant skills, one line each
- Complete: All specialized knowledge accessible
- Efficient: ~100 tokens vs ~500 tokens inline
- Maintainable: Update skills, not agents