SKILL.md
The required Markdown file that defines a skill's name, description and instructions.
- Published
- Sep 27, 2026
- Checked
- Sep 27, 2026
How far we checked this page
Signed by Ravalika Korthiwada, Sep 27, 2026. Passing one check says nothing about the next.
- FormatNot checkedThe file format was not checked for this page.
- InstallsNot checkedInstallation was not checked for this page.
- LoadsNot checkedLive loading was not checked for this page.
- HelpsNot checkedA with/without task comparison was not run.
SKILL.md is the one required file in an agent skill folder. Its top holds a YAML frontmatter block with name (1–64 characters, lowercase letters, digits and hyphens, matching the parent directory) and description (1–1,024 characters, non-empty). Optional standard fields include license, compatibility, metadata and the experimental allowed-tools. Everything below the frontmatter is the skill’s instructions, per the Agent Skills specification.
For example, our explain-error/SKILL.md opens with:
name: explain-error
description: Explains a pasted error message or stack trace and suggests one concrete fix. Use when someone shares an error, exception, stack trace, or traceback and asks what is wrong or how to fix it.followed by instructions to name the file and line, name the error type, and give one fix. We ran npx skills-ref validate (v0.1.5) against this file and it passed as a valid skill: a format check, not proof the instructions themselves are good, and not a check that a referenced file such as references/checklist.md actually exists.
SKILL.md is task-specific and loads on demand; AGENTS.md is repository-wide and loads up front. See SKILL.md vs AGENTS.md.
Related: Frontmatter, Agent skill, AGENTS.md.