Best Practices
Follow these best practices to create high-quality AI agent skills that users will love.
Writing Clear Instructions
1
Be Specific
Clearly define what your skill does and what it does not do. Avoid vague descriptions.
2
Use Examples
Provide real-world examples of how to use your skill. Examples help users understand capabilities quickly.
3
Define Limitations
Be upfront about what your skill cannot do. This prevents user frustration.
Skill Design
- Focus on one specific task or domain
- Keep the SKILL.md concise but complete
- Use consistent formatting and structure
- Test your skill with multiple AI assistants
Common Mistakes to Avoid
- Overpromising capabilities
- Vague or unclear instructions
- Missing or incomplete examples
- Trying to do too many things at once
Quality Checklist
- Clear and descriptive title
- Comprehensive description
- At least 3 usage examples
- Documented limitations
- Tested with multiple AI assistants
- Proper Markdown formatting
Maintaining Your Skill
A good skill needs ongoing maintenance:
- Respond to user issues and feedback
- Update documentation based on user questions
- Keep examples current and relevant
- Test with new AI model releases