SKILL.md frontmatter errors: what each one means and the fix
A SKILL.md has to open with a frontmatter block: a line of three hyphens, a name and a description, and a second line of three hyphens. Each error below is one way that block goes wrong. For each one: what it means, what usually causes it, the fix, and, where the crawl measured it, how many public SKILL.md files on GitHub have the same problem.
| Problem | SKILL.md files | Share |
|---|---|---|
| No frontmatter block it could read | 794 | 1.3% |
| No name in the frontmatter | 1,263 | 2.1% |
| No description in the frontmatter | 1,093 | 1.8% |
What does "Skill markdown does not contain frontmatter" mean?
Your SKILL.md does not open with a frontmatter block, so its name and description could not be read. The file must begin with a line of three hyphens, then name and description, then a second line of three hyphens. Codex reports the same problem as "missing YAML frontmatter delimited by ---".
--- name: my-skill description: What the skill does, and when to use it. ---
The usual causes: anything above the first ---, even a blank line; a block that is empty or never closed; or a file not named SKILL.md. In the registry's crawl, 794 of 61,170 public SKILL.md files (1.3%) open with no block it could read. To test a file on GitHub, paste its link into the check.
What does "invalid YAML" mean in SKILL.md frontmatter?
The block between the two lines of hyphens was found, but it could not be read as YAML. Codex prints "invalid YAML:" followed by the reason its YAML reader gave. Three causes are common. A line is indented with a tab. A quote is opened and never closed. Or a line is not a key, a colon, a space and a value: a bare sentence, or a line that starts with a dash. Write one field per line.
Here a quote is opened and never closed, so everything after it is read as one unfinished value:
--- name: release-notes description: "Drafts release notes from merged pull requests. ---
Close the quote, or drop it. A description that itself holds a colon followed by a space, as in Release notes: drafts them, is not valid YAML without quotes, and some tools reject it. Codex's parser retries such a line with the value quoted, but other tools may not, so quote it yourself:
--- name: release-notes description: "Release notes: drafts them from merged pull requests." ---
Indent with spaces only, since YAML does not allow tabs there. The registry's own reader skips lines it cannot read instead of failing, so its crawl has no count for this error.
What does "missing field description" mean?
The block was read, but a required field is absent or empty. Every SKILL.md needs a name, in lowercase letters, numbers and hyphens and equal to its folder's name, and a description of what the skill does and when to use it. Codex words it as "missing field `description`".
An empty value counts as missing, so description: with nothing after it fails the same way. Write what the skill does and when an agent should use it, in one or two sentences. Codex does not stop when the name is missing: its parser falls back to a default name. The Agent Skills specification still requires a name, so add one.
In the registry's crawl of 60,844 SKILL.md files inside a skill folder, 1,244 had no name and 979 no description. The figure above counts all 61,170 public SKILL.md files, including those outside a skill folder. Every rule for both fields: the SKILL.md format guide.
What does "invalid name: exceeds maximum length of 64 characters" mean?
The name in your frontmatter is longer than 64 characters, the most the Agent Skills specification allows, and Codex prints this message for any name over that length. Shorten it. A valid name is 1 to 64 lowercase letters, digits and hyphens. It has no hyphen at the start or the end, and never two in a row. It equals the name of the skill's folder.
| Name | Valid? | Why |
|---|---|---|
pdf-helper | Yes | Lowercase letters and one hyphen, and the folder is pdf-helper |
PDF Helper | No | Capital letters and a space |
pdf_helper | No | An underscore |
-pdf-helper | No | Starts with a hyphen |
pdf--helper | No | Two hyphens in a row |
Codex's parser checks only the length; the other rules are the specification's. The crawl counts both kinds of mistake. Of 60,844 SKILL.md files inside a skill folder, 1,327 (2.2%) have a name with characters or hyphens the specification does not allow, or one over 64 characters. And 3,858 (6.3%) have a name that does not match their folder.
How do I check a SKILL.md for frontmatter errors before I publish it?
Read the first lines of the file. The very first line must be three hyphens and nothing else, then name and description, then a closing line of three hyphens, and the name must equal the folder's name. For a file already on GitHub, paste its link into the registry's check, which reports whether it found the block, a name and a description.
$ head -n 4 skills/pdf-helper/SKILL.md --- name: pdf-helper description: Fills in and merges PDF forms. Use when the user asks to edit a PDF. ---
If the first line looks right and a tool still finds no frontmatter, the file may start with an invisible byte order mark, which some Windows editors add. Run head -c 3 SKILL.md | od -An -tx1: it prints 2d 2d 2d for three hyphens, and ef bb bf when the mark is there. Save the file as UTF-8 without it. To test a published file, paste its GitHub link into the check; the same checks run on every SKILL.md the registry holds.
Sources
Read next
- SKILL.md format: the required frontmatter fields
- Check a SKILL.md on GitHub
- Every SKILL.md skill in the registry, most starred first
Try it
npx modelranch add anthropics/skills/pdf