Skill Builder Playbook

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.