The Agent Skills format is an open standard originally created by Anthropic. A skill is a directory containing a required SKILL.md (YAML frontmatter + Markdown instructions) plus optional scripts/, references/ and assets/ folders. Agents load skills by progressive disclosure: metadata first, then the body, then resources. The official field rules are summarized below, cross-checked against the Agent Skills specification and the reference validator in the anthropics/skills repository.
What it checks
Error
Frontmatter structure
File must open with YAML frontmatter between --- lines; YAML must parse cleanly; only the six spec keys are allowed (name, description, license, compatibility, metadata, allowed-tools). Anything else belongs in metadata.
Error
Name rules
name is required: 1–64 chars, lowercase letters, numbers and single hyphens only, no leading or trailing hyphen. It must match the skill's parent directory name exactly.
Error
Description rules
description is required: 1–1024 characters, a single line of plain text — no newlines, no angle brackets. This is the text agents read to decide when the skill applies.
Warning
Types & limits
metadata must be a string-to-string map, allowed-tools a space-separated string (it's experimental), compatibility at most 500 characters. Body should start with an H1 and stay under ~500 lines.
Suggestion
Description quality
State both what the skill does and when to use it, in third person, with the trigger terms an agent would match on. This is the top cause of skills that validate but never fire.
Suggestion
Keep it portable
File links from SKILL.md should be one level deep, and resources should live under scripts/, references/ or assets/ for progressive disclosure.
Spec reference
| Field | Required | Rules |
|---|---|---|
name | Yes | 1–64 chars; lowercase a-z, 0-9, hyphens; no leading/trailing/consecutive hyphens; must match parent directory name |
description | Yes | 1–1024 chars; single line, plain text; states what the skill does and when to use it |
license | No | License name or reference to a bundled license file |
compatibility | No | ≤ 500 chars; environment requirements (product, packages, network access) |
metadata | No | Arbitrary string → string map for client-defined properties (e.g. version, author) |
allowed-tools | No | Experimental; space-separated list of pre-approved tools, e.g. "Bash(git:*) Read" |
FAQ
Why does my skill fail to upload with "invalid frontmatter"?
The most common cause is an unknown top-level key. The spec allows exactly six: name, description, license, compatibility, metadata and allowed-tools. Extras like version: or author: must move under metadata. The second most common cause is a YAML syntax error — an unquoted colon or a tab indent will break the whole block.
Why do I get "name doesn't match directory"?
The name field must exactly match the parent directory name. A skill named pdf-tools must live in a folder called pdf-tools — kebab-case, lowercase letters, numbers and single hyphens only, up to 64 characters.
What are the rules for the skill description?
Required, 1 to 1024 characters, a single line of plain text with no newlines or angle brackets. Write it in third person and cover both what the skill does and when to use it — this string is the sole trigger agents use to decide whether the skill applies. Also see the Claude Code skills documentation.
What is the allowed-tools field?
An experimental, optional field listing pre-approved tools as a space-separated string, for example "Bash(git:*) Read". Most skills should omit it; only use it when the skill should be restricted to specific tools.
Does this validator upload my SKILL.md anywhere?
No. Everything runs locally in your browser with JavaScript — nothing is sent to any server, and no account or signup is needed.