write-a-skill

Create a directory containing a SKILL.md file with YAML frontmatter defining a name and description, followed by markdown instructions. Optionally add scripts, REFERENCE.md, or EXAMPLES.md for deterministic operations or detailed documentation.

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, written in third person, so the agent can match it to user requests.

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 keywords, exceeding 100 lines in SKILL.md, including time-sensitive information, inconsistent terminology, and missing concrete examples. The review checklist in the skill catches these issues.