SKILL.md validator
Free, runs in your browser. Updated .
An agent skill is a folder with a SKILL.md file: YAML frontmatter with a name and description, then the instructions. Agents load every skill’s name and description at startup and the rest only when the skill triggers, so a bad name stops the skill loading and a vague description stops it being used. Paste a SKILL.md to check it against the Agent Skills specification, the Claude API’s extra rules and the fields Claude Code reads. Nothing you paste leaves your browser.
Paste the whole file, frontmatter included. It stays in this browser tab.
The folder that holds SKILL.md. The name must match it.
The 19 checks
Errors stop the skill loading in at least one agent or the Claude API. Warnings make it trigger less often, cost more context, or break on some systems.
| Check | Level | Why it matters |
|---|---|---|
| File starts with YAML frontmatter | Error | The frontmatter must open with --- on the first line and close with --- on a line of its own. Without it Claude Code reads the whole file as instructions, and the skill has no name or description to be found by. |
| Frontmatter is valid YAML | Error | When the YAML does not parse, agents drop the frontmatter. A colon inside an unquoted description is the usual cause; quote the value. |
| Skill has a name | Error | The Agent Skills specification and the Claude API require a name. Claude Code falls back to the folder name, but other agents and the API refuse the skill. |
| Name is lowercase letters, digits and single hyphens, up to 64 characters | Error | The specification allows a-z, 0-9 and hyphens, at most 64 of them, with no hyphen at the start or end and no two in a row. The Claude API refuses other names. |
| Name avoids reserved words | Error | The Claude API refuses skill names that contain claude or anthropic, and Claude Code will not load a skill named synced, which it keeps for skills synced from claude.ai. |
| Name matches the skill folder | Error | The specification requires the name to equal the folder that holds SKILL.md. Claude Code names the command after the frontmatter name, so a mismatch also gives the command a different name from its folder. |
| Skill has a description | Error | The description is the only text an agent reads before deciding to load the skill. Without one the skill is rarely or never used. |
| Description is at most 1,024 characters | Error | The specification and the Claude API cap the description at 1,024 characters. Everything in it is loaded at startup for every session, whether or not the skill runs. |
| Description has no XML tags | Error | The Claude API refuses descriptions that contain XML tags, and Claude Code shows angle brackets as < and > in its skill list. |
| Description says when to use the skill | Warning | Agents match requests against the description. One that says what the skill does but not when to use it, for example “Use when the user asks for…”, triggers less often than it should. |
| Description is written in the third person | Warning | The description is placed in the system prompt. “I can help…” or “You can use…” mixes points of view there; Anthropic’s authoring guide recommends the third person, such as “Extracts text from PDFs”. |
| Description and when_to_use fit Claude Code’s skill list | Warning | Claude Code joins description and when_to_use and cuts the result at 1,536 characters in the list Claude chooses skills from. |
| compatibility is 1 to 500 characters | Error | The specification limits compatibility to 500 characters. Most skills do not need the field at all. |
| metadata maps names to text | Warning | The specification defines metadata as string keys with string values. Quote numbers such as versions, or YAML reads 1.10 as the number 1.1. |
| Claude Code fields have values it accepts | Warning | Claude Code reads true or false (or yes, no, on, off, 1, 0) for its switches, only fork for context, and low, medium, high, xhigh or max for effort. Other values do not do what they look like. |
| Every field is one agents read | Warning | Agents silently ignore fields that are not in the specification or Claude Code’s list. Put your own values under metadata so they are kept and do not clash with future fields. |
| SKILL.md has instructions | Warning | The body after the frontmatter is what the agent follows once the skill triggers. Without it the skill loads and does nothing. |
| Body stays under 500 lines and about 5,000 tokens | Warning | The agent loads the whole SKILL.md when the skill triggers, and in Claude Code it stays in context for the rest of the session. Move reference material into separate files that load only when needed. |
| File paths use forward slashes | Warning | Paths such as scripts\fill.py fail on macOS and Linux. Forward slashes work on every system, Windows included. |
SKILL.md fields: the specification and Claude Code
The Agent Skills specification defines six fields that every compatible agent reads. Claude Code reads more, and other agents ignore them, so a skill written for several agents keeps to the first six.
| Field | Agent Skills specification | Claude Code |
|---|---|---|
name | Required. Up to 64 of a-z, 0-9 and -, matching the folder. | Optional; the folder name is used without it. Becomes the /command. |
description | Required. Up to 1,024 characters: what it does and when to use it. | Recommended. Without it the first line of the body is used. |
license | Optional. A license name or a bundled license file. | Accepted, not acted on. |
compatibility | Optional. Up to 500 characters of environment needs. | Accepted, not acted on. |
metadata | Optional. Your own keys, each with a text value. | Kept for your tooling; ignored. |
allowed-tools | Optional and experimental. Space-separated tools. | Pre-approves those tools while the skill runs. |
when_to_use | Not in the specification. | More trigger phrases, added to the description. |
disable-model-invocation | Not in the specification. | true: only the user can run it, with its /command. |
user-invocable | Not in the specification. | false: hidden from the / menu; only Claude runs it. |
context and agent | Not in the specification. | context: fork runs the skill in a subagent of the given agent type. |
paths | Not in the specification. | Globs that limit when the skill activates. |
A SKILL.md that passes
The description says what the skill does and when to use it, in the third person. The version sits under metadata as text, and the house style lives in a reference file that loads only when the agent needs it.
---
name: release-notes
description: Drafts release notes from merged pull requests and the commit log, grouped into features, fixes and breaking changes. Use when the user asks for release notes, a changelog entry or a summary of what shipped since the last tag.
license: MIT
metadata:
version: "1.2.0"
---
# Release notes
## Steps
1. Find the last release tag with `git describe --tags --abbrev=0`.
2. List the pull requests merged since that tag.
3. Group each change under Features, Fixes or Breaking changes.
4. Write one line per change in the past tense, linking its pull request.
For the house style and worked examples, see [references/style.md](references/style.md).
Questions
- Which fields does a SKILL.md need?
- name and description. The Agent Skills specification also defines license, compatibility, metadata and allowed-tools, all optional. Claude Code reads further optional fields such as when_to_use, disable-model-invocation, context and paths, and other agents ignore those.
- What makes a skill name valid?
- Up to 64 lowercase letters, digits and hyphens, with no hyphen at the start or end and no two in a row, and the same as the folder that holds SKILL.md. The Claude API also refuses names containing claude or anthropic.
- How long can the description be?
- Up to 1,024 characters, with no XML tags. Most good descriptions are one or two sentences: what the skill does, then when to use it, with the words a user would actually type.
- Why does my skill never trigger?
- Usually the description. The agent sees only the name and description when it decides which skill to load, so a description that says what the skill does but not when to use it, or that leaves out the words users type, is easy to skip. Add a sentence that starts “Use when”.
- How long should SKILL.md be?
- Under 500 lines, and under about 5,000 tokens. The whole file loads when the skill triggers, so move reference material, long examples and schemas into separate files that the agent reads only when it needs them, and link to them one level deep from SKILL.md.
- Is what I paste uploaded anywhere?
- No. The file is checked in this browser tab and nothing is kept after you leave the page.
Related
- Claude Code plugin.json generator: package skills as a plugin users install with /plugin install.
- Plugin pre-flight: check a plugin repository against the Claude, Codex and Cursor directory rules.
- MCP context cost calculator: what tool definitions and instructions cost in tokens and dollars on every request.
- What an agent skill is, and the other terms behind these checks.
- List your skill on HOL so people can find it and see what it ships before they install it.