Best Practices
Guidelines for creating effective, maintainable Agent Skills.
Overview
Well-designed skills are the difference between a helpful AI assistant and a frustrating one. Follow these best practices to create skills that work reliably.
Core Principles
1. Be Specific, Not Vague
Good:
"Use sentence case for headings. Capitalize only the first word and proper nouns."
Bad:
"Use appropriate capitalization."
2. Provide Examples
Show, don't just tell. Include concrete examples of expected behavior.
Good:
When formatting dates:
- Write: "January 15, 2024"
- Don't write: "01/15/24" or "15 Jan 2024"
3. Define Scope Clearly
Explicitly state what the skill covers and what it doesn't.
Good:
This skill covers:
- React component design
- State management
- Performance optimization
This skill does NOT cover:
- Backend API design
- Database schema
- DevOps/deployment
4. Use Consistent Structure
Organize content predictably so the AI can find information quickly.
Recommended sections:
- Context/Overview
- Guidelines
- Do's and Don'ts
- Examples
- References
5. Keep It Focused
One skill = one domain. Don't try to cover everything.
Good: "React Component Guidelines" Bad: "Complete Web Development Guide"
Common Mistakes
Over-Engineering
Don't add complexity that doesn't provide value:
- Too many rules that contradict each other
- Edge cases that rarely occur
- Redundant information
Under-Specifying
Don't leave important details ambiguous:
- Missing examples for key concepts
- Vague language like "as appropriate"
- No guidance on edge cases
Conflicting Instructions
Ensure your guidelines don't contradict each other:
Problem:
"Keep responses concise" and "Provide detailed explanations"
Solution:
"Keep responses concise. For complex topics, provide detailed explanations in expandable sections."
Documentation
- Writing Descriptions - Craft effective skill descriptions
- Testing Strategy - Verify your skill works correctly
Related
- Create Skills - Step-by-step creation guide
- Examples - Learn from existing skills