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 files, or examples, then review against a checklist for triggers, length, and consistency.

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 operations are 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 when SKILL.md exceeds 100 lines, when content covers distinct domains, or when advanced features are rarely needed. Move detailed documentation to REFERENCE.md and examples to EXAMPLES.md, keeping references one level deep.

The description is the only text the agent sees when selecting skills, so vague descriptions cause mismatches. Include concrete trigger phrases like "Use when working with PDF files" so the agent can distinguish your skill from similar ones.