SKILL.md Format Explained: Frontmatter, Fields and Limits

SKILL.md is the core of the open Agent Skills format, originally from Anthropic and now read by Claude, ChatGPT and Codex, Cursor, Gemini CLI, GitHub Copilot and others (spec).

Structure

A SKILL.md file has YAML frontmatter between --- lines, followed by Markdown instructions.

Required fields

Field	Rules
name	Lowercase letters, numbers, hyphens. Max 64 chars. Must match the folder name. No "anthropic" or "claude". No XML tags. (Claude Code alone treats it as optional and falls back to the folder name.)
description	Non-empty, max 1,024 chars, no XML tags. Say what it does and when to use it.

Optional fields

The open spec allows four more: license, allowed-tools, metadata and compatibility (max 500 characters). Uploading to claude.ai or the Skills API fails with an "Unexpected key(s)" error if you add anything else. Some tools read extra fields locally (Claude Code: when_to_use, disable-model-invocation, paths; Cursor: paths, disable-model-invocation), but for portability stick to the standard six.

Body

The body loads only when the skill triggers. Keep it focused and point to extra files (references/guide.md) for long material — "progressive disclosure". Use forward slashes in paths.

Common errors

• Name doesn't match folder — rename one of them.
• SKILL.md at zip root — zip the folder itself so entries start with my-skill/.
• Unexpected key — remove non-standard frontmatter keys.
• Description too vague — Claude won't know when to load it.

Want a valid file without memorising the rules? Generate one free.