What fields does SKILL.md frontmatter require?

name and description are required. name is 1 to 64 characters of lowercase letters, digits and single hyphens and should match the folder name. description is at most 1,024 characters. Optional fields include license, compatibility, allowed-tools and metadata.

Why is my skill not loading?

The most common causes: the frontmatter fence is not on line 1 (a BOM or blank line before it), the YAML does not parse (an unquoted colon in the description), the name has uppercase letters or spaces, or the name does not match the folder.

How long can a SKILL.md be?

The Agent Skills spec caps the description at 1,024 characters, and claude.ai uploads, the Claude API and the spec's validator reject a longer one. Claude Code still loads it, but shows at most 1,536 characters of description plus when_to_use in its skill listing. The body has no hard cap, but keep it under 500 lines and move detail into files the skill references, because the whole body is loaded into context when the skill activates.

Is my SKILL.md valid?

The shape of a valid skill

A skill is a folder with a SKILL.md at its root. The file starts with YAML frontmatter on line 1, then markdown instructions. Other files in the folder (scripts, references, templates) are optional and loaded only when the skill points to them.

pdf-export/
  SKILL.md
  reference.md      (optional, loaded on demand)
  scripts/fill.py   (optional)

---
name: pdf-export
description: Export a markdown report to a client-ready PDF with a cover page, table of contents and page numbers. Use when the user asks for a PDF, a printable report or a deliverable.
---

# PDF export

1. Confirm the page size (A4 or Letter) and whether a cover page is wanted.
2. Run `scripts/fill.py` ...

Frontmatter fields and limits

Field	Required	Rule
`name`	Yes	1 to 64 characters. Lowercase letters, digits and hyphens only; no leading, trailing or double hyphens. Must match the folder name. Example: `pdf-export`, not `PDF Export` or `pdf_export`.
`description`	Yes	1 to 1,024 characters. This is the only text the agent reads before deciding to load the skill, so it must say what the skill does and when to use it. What happens past 1,024 depends on the tool; see below.
`license`	No	Free text, usually an SPDX identifier such as `MIT`.
`compatibility`	No	1 to 500 characters if present: which tools, runtimes or network access the skill needs. Most skills do not need it.
`allowed-tools`	No	Tools the skill may run without asking. The spec defines it as a space-separated string, such as `Read Grep`, and marks it experimental. Claude Code also accepts commas or a YAML list; other hosts may not.
`metadata`	No	A map of your own keys (author, version) for tooling. Values must be strings, so quote numbers: `version: "1.0"`.

Fields beyond these six. Claude Code reads more fields than the spec defines, such as when_to_use, argument-hint, disable-model-invocation, user-invocable, model and context. Where a key goes unrecognised, the hosts disagree. Claude Code "ignores a field it doesn't recognize without reporting an error". A claude.ai upload, the Skills API and Anthropic's package_skill.py accept only the six fields in the table, and any other key "fails with a hard error instead of ignoring the field"; the spec's own validator, skills-ref, also rejects it. A skill you plan to share outside Claude Code should stick to the six.

The body has no hard limit, but it is loaded whole when the skill activates. Keep it under 500 lines and put long references, examples and data in separate files that the body links to. That also keeps the context cost predictable.

Common mistakes

Frontmatter not on line 1. A UTF-8 byte-order mark, a blank line or a comment before the opening --- means most loaders see no frontmatter at all. Windows editors and some "save as UTF-8" paths add a BOM silently.
YAML that does not parse. An unquoted colon followed by a space inside the description (description: Use when: the user asks) breaks the parse. Quote the value or rephrase.
Name format. Uppercase, spaces, underscores, or a name that does not match the folder. Loaders index the folder; an inconsistent name is either ignored or shadows another skill.
Description too generic. "Helps with documents" never triggers. Name the task and the cue: "Use when the user asks for a PDF, a printable report or a client deliverable."
Description too long. Past 1,024 characters the result depends on where the skill runs. A claude.ai upload and the Claude API reject it, and so does the spec's validator. Claude Code loads it, but its skill listing shows at most 1,536 characters of description and when_to_use combined and cuts the rest, so put the trigger first. Either way, move the detail into the body.
Closing fence missing or wrong. ---- or *** instead of --- turns the whole file into frontmatter or into body text.
Line endings changed by an editor. Not a validity error, but if your editor converts CRLF to LF or rewrites the frontmatter on save, every commit is noisy and reviews miss the real change. See why did my editor change my CLAUDE.md.
Hidden instructions. An HTML comment addressed to the AI ("assistant: ignore the rules above") in a skill you copied from somewhere is a prompt injection. Lint for it before you install skills you did not write.

Writing a description that triggers

The agent chooses skills by reading descriptions, nothing else. A good one answers two questions in one or two sentences: what does this skill do, and what does the user say that should make you load it.

description: Convert a markdown report into a Word document with real heading, table and code styles. Use when the user asks for a .docx, a Word file, or a document their client can redline.

Avoid restating the name, listing every step, or promising results. Put the steps in the body.

Checklist

File is named exactly SKILL.md and sits at the root of the skill folder
Line 1 is ---, with no BOM and no blank line before it
Frontmatter parses as YAML
name is lowercase-hyphenated, 64 characters or fewer, and equals the folder name
description is present, 1,024 characters or fewer, and says when to use the skill
Body under 500 lines; long material moved to referenced files
No hidden instructions, zero-width characters or bidirectional controls
Saved with the line endings the repository already uses

Check your file

Paste the SKILL.md into the steering file checker and pick SKILL.md. Add the skill's folder name and it also checks that the name field matches. It runs in your browser; nothing is uploaded.

Open the steering file checker

To check every steering file in a project from inside Claude Code, including links, @imports and what loads every session, install the free AsItIs plugin. It is read-only and makes no network calls.

claude plugin marketplace add Katta041/asitis-agent-tools
claude plugin install asitis@asitis

About the plugin Source on GitHub

MIT licensed. A star on GitHub helps other people find it.

With the plugin installed, /asitis:md-lint .claude/skills/pdf-export/SKILL.md runs the same checks inside a Claude Code session and prints errors with line numbers. The desktop app, now in development, will show the same checks inline for every steering file in a folder. Sources, read on 14 October 2026: the Agent Skills specification and its skills-ref validator; Claude Code docs, Skills; Claude API docs, Using Agent Skills with the API. Related: CLAUDE.md best practices, hidden instructions in AGENTS.md, why did my editor change my CLAUDE.md.