Skill Builder Playbook

Create a high-quality skill by following a short workflow and pulling details from the references.

Quick Start

1. Clarify the goal and use cases. See references/planning-design.md.
2. Decide if this is standalone or MCP-enhanced. See references/fundamentals.md.
3. Define structure and frontmatter. See references/structure-and-frontmatter.md.
4. Write the description field. See references/description-field.md.
5. Write concise instructions and examples. See references/instruction-writing.md.
6. Add references for details and variants. See references/progressive-disclosure.md.
7. Test and iterate. See references/testing-iteration.md.
8. Package and share. See references/distribution-sharing.md.

Guidance

• Keep SKILL.md short and link out to references.
• Be specific and actionable; include error handling.
• Avoid extra files (README/CHANGELOG) inside the skill folder unless explicitly requested.

When To Read References

• Use references/fundamentals.md for what skills are, progressive disclosure, and MCP + skills.
• Use references/planning-design.md for use cases, categories, and success criteria.
• Use references/structure-and-frontmatter.md for file layout, naming rules, and frontmatter requirements.
• Use references/description-field.md for description structure and good/bad examples.
• Use references/instruction-writing.md for instruction templates, best practices, and error handling.
• Use references/progressive-disclosure.md to split content into references without bloating SKILL.md.
• Use references/testing-iteration.md for testing modes, test cases, and iteration signals.
• Use references/distribution-sharing.md for packaging, API usage, and distribution guidance.
• Use references/patterns-troubleshooting.md for design patterns and debugging common issues.
• Use references/checklists.md for preflight and post-upload checks.
• Use references/resources-references.md for official docs, examples, and support.