What is SKILL.md?

The Agent Skills specification defines a skill as a directory that contains, at minimum, a SKILL.md file. The file starts with YAML frontmatter and continues with free-form markdown. The body has no format restrictions, though the spec suggests step-by-step instructions, input and output examples, and common edge cases.

Two frontmatter fields are required. The name must be 1 to 64 characters of lowercase letters, numbers and hyphens, may not begin or end with a hyphen or contain consecutive hyphens, and must match the parent directory name. The description must be 1 to 1024 characters and should cover the skill's purpose and the situations that call for it. Optional fields are license, compatibility, metadata and an experimental allowed-tools list.

A skill directory may also hold scripts, references and assets folders. The spec describes progressive disclosure: only the name and description are loaded at startup, the full SKILL.md is read when the skill is activated, and other files load when needed. It recommends keeping SKILL.md under 500 lines and moving long reference material into separate files.

The spec ships a reference library, skills-ref, that can validate a skill's frontmatter and naming. The allowed-tools field is marked experimental, and the spec notes that support for it may vary between agent implementations.