The SKILL.md Format Explained Simply — YAML, Markdown and the Entire Spec

SKILL.md is the simplest specification you will see in modern AI tooling. Two required fields. A markdown body. A few naming rules. Once you understand the format completely, you can read and write any skill in the ecosystem.

The most striking thing about the SKILL.md format is how little there is to learn. Most specifications for AI tooling involve protocols, transport mechanisms, message schemas and dozens of pages of documentation. SKILL.md fits comfortably on a single page.

The Anatomy of a SKILL.md File

Every SKILL.md file has two sections, separated by three dashes on a line by themselves:

---
name: my-skill-name
description: What this skill does and when the agent should use it.
---

# My Skill Name

## Instructions

Step-by-step guidance the agent follows when triggered.

The first section is YAML frontmatter — structured metadata the agent reads at startup. The second section is freeform Markdown — the instructions the agent reads when the skill is actually triggered.

The Two Required Fields

The name field must be lowercase letters, numbers and hyphens only, maximum 64 characters. By convention, skills use kebab-case: pdf-processing, weekly-report-builder, customer-research-agent. The folder containing SKILL.md must have the same name. If it does not match, the skill will be rejected at install time.

The description field is the most important field in the entire specification. It is the only information the agent has about your skill when deciding whether to use it for a given request. The constraints are loose — non-empty, maximum 1024 characters, no XML tags — but the quality of your description determines whether the skill ever gets used. A vague description means the skill is invisible to the agent. A specific description with concrete triggering contexts means the skill gets invoked reliably.

The Markdown Body

Below the closing dashes, the rest of SKILL.md is freeform Markdown. The specification has no format requirements at all — you can write whatever helps the agent perform the task effectively. That said, a consistent structure has emerged in the community and the official Anthropic reference skills follow it: a Title (level 1 header), an Instructions section (the bulk of the content), an Examples section (concrete cases), and a Guidelines section (constraints and best practices).

Optional Fields

Beyond the two required fields, several optional fields are commonly used: version for semantic versioning, license for SPDX identifiers like MIT or Apache-2.0, tags for marketplace discovery, and metadata for custom author or homepage information. None of these are required — the format is intentionally minimal — but they help when you publish skills publicly.

The Validation Rules

Six rules are enforced at install time. The folder name must match the name field. The name field follows the lowercase-hyphen rule. The description field is non-empty and under 1024 characters. The YAML frontmatter starts at line 1 with three dashes and ends with three dashes. The Markdown body stays under 5,000 tokens (larger content should go in separate REFERENCE.md or FORMS.md files). And SKILL.md must be at the root of the skill folder. That is the entire validation surface.