write-a-skill

Start with YAML frontmatter containing a name and description, then add a Markdown body with a quick start, workflows, and advanced features. Keep the file under 100 lines and split longer content into separate reference files.

A good description states 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 the skill covers distinct domains, or when advanced features are rarely needed. Reference files should stay one level deep from the main SKILL.md.

A skill can include a scripts directory for executable utilities, a references directory for detailed documentation, and an assets directory for stored documents. These resources are loaded on demand as directed by SKILL.md.