How to use the validator
- Paste the full contents of your
SKILL.md, including the---lines. - Type the skill's folder name if you want to check that it matches
name. - Press Validate. Errors must be fixed; warnings are suggestions.
The rules it checks
| Field | Rule |
|---|---|
| Frontmatter | The file starts with --- on the first line and the YAML block closes with --- |
name |
1–64 characters; lowercase letters, numbers and hyphens; no leading, trailing or double hyphens; same as the folder name |
description |
Required; up to 1,024 characters; says what the skill does and when to use it |
compatibility |
Optional; up to 500 characters |
metadata |
Optional; a map of keys to values |
These come from the open Agent Skills specification. The validator also knows the extra fields Claude Code reads, such as disable-model-invocation, user-invocable, allowed-tools, paths and context, and points out when you use them, because other agents may ignore them.
Claude Code has two limits worth knowing: it shows at most 1,536 characters of description plus when_to_use in its skill list, and it will not load a personal or project skill named synced or starting with anthropic-skills.
A good SKILL.md, briefly
- Description first. It is the only part Claude sees until the skill is needed. Name the task, the file types and the phrases a user would say.
- Short body, linked details. The whole file loads when the skill runs. Keep steps and examples in
SKILL.mdand move long reference material into separate files. - Steps, examples, edge cases. The specification recommends these three kinds of section.
Once it validates, follow the install guide to try it in Claude Code, or study how published skills are written in the directory. Anthropic's skill-creator can also test a skill for you.