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 / reference validator
- anthropics/claude-code #9716 — frontmatter rejected despite looking identicalVerified issue — open since October 2025
- skills-ref validate (official reference validator, v0.1.5)Specification / reference validator
Strict spec conformance
Non-conformant. The official reference validator (skills-ref) rejects this — tested directly, not inferred from severity.
This is a separate question from the severity above and from which runtimes enforce it below — a rule can be a real, working extension in its home runtime while the reference validator still rejects the file outright, or vice versa. Both facts are reported, never one inferred from the other.
Which runtimes enforce it
| Runtime | Effect | Note |
|---|---|---|
| Claude Code | Breaks the skill | Verified: frontmatter that failed to parse was reported as rejected, and the skill never appeared, until the block was retyped by hand. |
| Codex | Not documented | Not documented for this runtime — we hold no runtime-specific evidence either way. |
| Cursor | Not documented | Not documented for this runtime — we hold no runtime-specific evidence either way. |
| OpenClaw | Not documented | Not documented for this runtime — we hold no runtime-specific evidence either way. |
| Hermes Agent | Not documented | Not documented for this runtime — we hold no runtime-specific evidence either way. |
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.