write-a-skill

Start by gathering requirements about the task domain and use cases, then draft a SKILL.md with YAML frontmatter containing a name and description. Add reference files or scripts only when content exceeds length thresholds or deterministic operations are needed.

A skill description should state what the skill does in the first sentence and when to trigger it in the second, using specific keywords and contexts. Keep it under 1024 characters, write in third person, and avoid vague phrases like "helps with documents."

Add utility scripts when an operation is deterministic, such as validation or formatting, when the same code would be generated repeatedly, or when errors need explicit handling. Scripts save tokens and improve reliability over generated code.

Split content into separate files like REFERENCE.md or EXAMPLES.md when SKILL.md exceeds 100 lines, when content covers distinct domains, or when advanced features are rarely needed. Keep references one level deep.

Common mistakes include vague descriptions without trigger phrases, SKILL.md files over 100 lines, time-sensitive information, inconsistent terminology, and missing concrete examples. Use the review checklist to catch these before finalizing.