SKM-F03 · Error
Frontmatter does not parse as YAML
The block between the `---` delimiters is not valid YAML.
What the rule is
The text between the two `---` delimiters was found and closed, but it doesn't parse as valid YAML. This is one of the most reported causes of a skill silently not working, because malformed YAML often looks completely normal — a frontmatter block copied straight from documentation was rejected in one verified report, and the reporter described the eventual working rewrite as 'identical to my eyes' to the original.
Common causes: a colon inside an unquoted value (`description: Use when: something happens`), inconsistent indentation on a multi-line value, or a stray tab character mixed into otherwise-correct spacing.
Where it comes from
- Agent Skills — SpecificationSpecification
- anthropics/claude-code #9716 — frontmatter rejected despite looking identicalVerified issue — open since October 2025
Which runtimes enforce it
| Runtime | Effect | Note |
|---|---|---|
| Claude Code | Breaks the skill | Reported as frontmatter that looked correct to the eye but was rejected by every parser that read it — see the source issue. |
| Codex | Breaks the skill | Reported as frontmatter that looked correct to the eye but was rejected by every parser that read it — see the source issue. |
| Cursor | Breaks the skill | Reported as frontmatter that looked correct to the eye but was rejected by every parser that read it — see the source issue. |
| OpenClaw | Breaks the skill | Reported as frontmatter that looked correct to the eye but was rejected by every parser that read it — see the source issue. |
| Hermes Agent | Breaks the skill | Reported as frontmatter that looked correct to the eye but was rejected by every parser that read it — see the source issue. |
How to fix it
- Read the parse error's line and column, and check that line for an unquoted colon, inconsistent indentation, or a tab character.
- If the error location doesn't make the problem obvious, retype the frontmatter block by hand rather than trying to fix the existing text — several verified reports of this exact symptom were resolved that way.
Elsewhere
- SKILL.md, the formatThe full frontmatter field table this rule is drawn from.
- Agent Skills Not WorkingThe diagnostic reference this rule’s portability and failure evidence comes from.
- All rulesEvery check the validator runs, grouped by class.