Guide
SKILL.md format reference
One file, two parts: frontmatter that tells the agent when to load the skill, and a Markdown body that tells it what to do. This page lists every field and limit, then lets you validate your own file.
Frontmatter fields
These six fields come from the open Agent Skills specification, which Claude Code, Cursor, Codex and Gemini CLI all read.
| Field | Required | Limit and rules |
|---|---|---|
name | Yes | 1 to 64 characters. Lowercase letters, numbers and hyphens. No leading, trailing or double hyphens. Must match the folder name. |
description | Yes | 1 to 1,024 characters. Say what the skill does and when to use it, with the words a user would type. |
license | No | A license name or the name of a bundled license file. Keep it short. |
compatibility | No | Up to 500 characters. Environment needs such as a tool, a package or network access. Most skills omit it. |
metadata | No | A map of string keys to string values. The place for anything the spec does not define. |
allowed-tools | No | Space-separated tools the skill may use without asking. Marked experimental; support varies by agent. |
Individual tools add their own fields on top. Claude Code, for example, documents disable-model-invocation, paths and others, and ignores any field it does not know. Cursor documents paths and disable-model-invocation too. Check each tool's docs before you rely on one, and note that the scanner flags non-spec top-level keys as a portability risk.
Limits at a glance
| What | Limit | Why it matters |
|---|---|---|
| name | 64 characters | Longer names fail validation. |
| description | 1,024 characters | Claude Code's docs say the description text in its skill listing is cut at 1,536 characters, so put the trigger first. |
| Name and description together | About 100 tokens | Loaded for every skill at the start of a session, used or not. |
| SKILL.md body | Under 5,000 tokens and 500 lines | Loaded in full each time the skill triggers. |
| Reference files | No fixed limit | Read on demand. Keep each focused, one level below SKILL.md. |
Folder layout
skill-name/ ├── SKILL.md required: frontmatter and instructions ├── scripts/ optional: code the agent can run ├── references/ optional: documents read on demand └── assets/ optional: templates, images, data files
The folder name is the skill name. Only SKILL.md is required. Anything else is loaded when the body points to it, so name each file in SKILL.md and say when to open it.
A minimal valid skill, scored
This skill uses only the two required fields and a short body. The score below was computed from this exact text when the site was built.
--- name: commit-message description: "Use when the user asks for a commit message or says 'write the commit'. Writes a one-line summary under 72 characters and a short body from the staged diff." --- # Commit Message 1. Read the staged diff. 2. Write a summary line in the imperative mood, under 72 characters. 3. Add a body only if the why is not obvious from the diff. ## Output The message in a code block, nothing else.
Required fields only, a numbered workflow and an output line.
Spec 25 · Efficiency 15 · Clarity 20 · Security 25 (each out of 25)
Always loaded 43 tokens · on trigger 57 · on demand 0
eff/body-thinwarnThe body is very thin. A skill should carry knowledge the agent doesn't already have.clarity/exampleswarnNo examples or code blocks. One concrete input → output example improves consistency more than extra rules.
Common errors
| Error | Scanner rule | Fix |
|---|---|---|
| File does not start with --- | spec/frontmatter | Frontmatter must be the first line of the file. No blank line or comment before it. |
| Frontmatter never closed | spec/frontmatter | Add the closing --- on its own line. |
| Uppercase or spaces in name | spec/name-format | Use lowercase letters, numbers and single hyphens. |
| Folder and name differ | spec/name-folder | Rename one so they are identical. |
| Colon inside an unquoted description | spec/yaml | Wrap the value in double quotes. |
| Description over 1,024 characters | spec/description-length | Cut it. Move detail into the body. |
| Extra top-level keys | spec/non-portable-keys | Move them under metadata, or drop them. |
| Link to a file that is not there | spec/broken-ref | Add the file or fix the path. |
Validate your own
Paste a SKILL.md or drop a folder. It runs in your browser and nothing is uploaded.
Source
The field table follows the Agent Skills specification. Tool-specific fields come from each tool's own documentation.
Questions
- What is the SKILL.md format?
- A folder with a file named SKILL.md. The file starts with YAML frontmatter between two lines of three dashes, with a required name and description, then Markdown instructions. Optional folders such as scripts, references and assets sit beside it.
- Which frontmatter fields are required?
- Two: name and description. The open Agent Skills specification also defines license, compatibility, metadata and allowed-tools as optional.
- Can I add my own frontmatter fields?
- Claude Code ignores fields it does not recognise, and it supports a few of its own. But claude.ai and the Skills API can reject extra top-level fields, so put custom data under metadata if the skill should work everywhere. The scanner warns on non-spec keys for this reason.
- Does the folder name have to match the name field?
- The specification says name must match the parent directory. Cursor's docs say the same. Keep them identical and lowercase.
Keep reading
- Skill ScannerScore any skill in your browser. Nothing is uploaded.
- How to write a Claude skillSeven steps, a weak and a strong description, scored side by side.
- SKILL.md validatorCheck a skill against the spec, token budgets, clarity and security rules.
- All guidesEvery guide, grouped by what you are trying to do.
Paste a SKILL.md or drop a folder. It is scored in your browser and nothing is uploaded.
Want a skill that already passes? Start with a free one.