Frontmatter fields
Two fields are required and the rest are optional. The constraints below are the ones a validator enforces, which is why skills fail for reasons that look cosmetic, such as a capital letter in a name.
| Field | Required | Constraint |
|---|---|---|
name | Required | 1 to 64 characters. Lowercase a-z, 0-9 and hyphens only. No leading or trailing hyphen, no consecutive hyphens. Must match the parent directory name. |
description | Required | 1 to 1024 characters. Must say what the skill does and when to use it, with keywords an agent can match against a task. |
license | Optional | A license name, or the name of a bundled license file. Recommended to keep it short. |
compatibility | Optional | Up to 500 characters. Only include it when the skill has real environment requirements, such as a target product, system packages or network access. |
metadata | Optional | A map of string keys to string values for anything the spec does not define. Use distinctive key names to avoid collisions. |
allowed-tools Experimental | Optional | A space separated string of pre-approved tools, for example Bash(git:*) Read. Support varies between agent implementations. |
Directory layout
Only SKILL.md is required. The other directories are conventions, and they exist so that big material can stay out of the agent's context until it is needed.
| Path | Required | Purpose |
|---|---|---|
SKILL.md | Required | Frontmatter plus the instructions themselves. |
scripts/ | Optional | Executable code the agent can run. |
references/ | Optional | Documentation loaded on demand, not up front. |
assets/ | Optional | Templates, images, data files. |
Progressive disclosure and the context budget
Skills load in three stages. This is the part that decides whether a large skill library is usable, because the first stage is paid for every installed skill on every session.
| Stage | Cost | Loaded | Contains |
|---|---|---|---|
| Metadata | around 100 tokens | Loaded at startup for every installed skill | name and description only |
| Instructions | under 5,000 tokens recommended | Loaded when the skill is activated | the whole SKILL.md body |
| Resources | as needed | Loaded only when the task requires them | files under scripts/, references/ and assets/ |
Rules worth memorising
- Keep SKILL.md under 500 lines and move detail into references/.
- Keep file references one level deep from SKILL.md.
- The name must match the directory name, so renaming a skill means renaming both.
- Most skills do not need compatibility. Add it only when the environment really matters.
Validate before you publish
The reference library checks frontmatter and naming conventions, which catches the errors that otherwise show up as a skill that silently never loads.
skills-ref validate ./my-skillSources
All constraints on this page come from the published specification, read on the date shown. Check the source before relying on a field in production.
Agent Skills specification Last reviewed: 2026-08-05