Follow the sections in order, then adapt commands to your current environment.
Best Practices Guide
Follow these guidelines to create Agent Skills that work reliably across all platforms.
Skill Design
Single Responsibility
Each skill should do one thing well. Avoid "Fullstack Developer" skills; instead, create react-expert, postgres-architect, and devops-specialist.
Clear Boundaries
Define when the skill should not be used. This prevents the agent from applying specialized knowledge to unrelated tasks.
Writing Instructions
Specific & Actionable
- Weak: "Help the user write better tests."
- Strong: "When writing tests, always use the AAA pattern (Arrange, Act, Assert) and ensure 100% coverage for edge cases."
Include Examples
Provide code snippets or step-by-step workflows in the SKILL.md to guide the agent's output format.
Technical Tips
Use Relative Paths
Always reference scripts and assets using relative paths (scripts/tool.sh). This ensures the skill folder can be moved or renamed without breaking.
Cross-Platform Scripts
- Use Python or Node.js for scripts intended to run on both Windows and macOS/Linux.
- If using Shell scripts, stick to POSIX-compliant syntax.
Progressive Disclosure
Keep the description concise. Put detailed documentation and edge cases in the body or references/ folder.
Version Management
Use semantic versioning in metadata to help teams manage updates and breaking changes.