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 description is capped at 1,024 characters. 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.
`license`	No	Free text, usually an SPDX identifier such as `MIT`.
`compatibility`	No	Free text: which tools, runtimes or network access the skill needs.
`allowed-tools`	No	A list of tools the skill may run without asking. Host support varies; unknown keys are ignored, not rejected.
`metadata`	No	A map of your own keys (author, version) for tooling.

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 is also how you keep 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 skill is rejected. 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 editors change 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

Lint it

The free AsItIs plugin for Claude Code runs these checks and prints errors with line numbers:

/asitis:md-lint .claude/skills/pdf-export/SKILL.md

It also validates CLAUDE.md, AGENTS.md, Cursor rules and subagent files, estimates the context each one costs, and flags hidden instructions. It is read-only, runs locally and sends nothing. About the plugin.

In the AsItIs desktop app, the Files tab shows every steering file in a folder with the same validation inline, and saving never rewrites the parts you did not touch.