Anatomy of a SKILL.md

A skill is a folder whose entry point is SKILL.md: a YAML frontmatter block followed by Markdown instructions. Get the frontmatter right and the agent loads it at the right moment; get it wrong and it silently never loads.

---
name: repro-first-debugging
description: Use when investigating a bug or failing test. Reproduce the
  failure with a minimal case before changing any code, then prove the fix
  against that same repro.
---

# Repro-first debugging

1. Reproduce the reported failure locally with the smallest possible case…

The frontmatter that matters

• name — lowercase, hyphenated, no spaces or reserved words. This is the handle the agent matches against.
• description — the single most important line. It's when to use this, not what it is. The agent reads only the description to decide whether to load the body, so it must name the trigger conditions concretely.

The body

Plain Markdown instructions. Keep it focused and under a few thousand tokens — a skill is a procedure, not a manual. Put supporting material (long references, scripts) in references/ and scripts/ so the body stays lean and loads fast.

Write one with the skill

skill-author is itself a skill: install it and it walks your agent through producing a spec-valid SKILL.md, then checks the result. It's part of the free set.

Next

• Validate a skill — the checker that catches the frontmatter and naming mistakes that make ~1 in 5 public skills fail to load.