SKM-F04 · Error
Frontmatter parses, but isn't a mapping
The frontmatter must be a YAML mapping (`key: value` pairs) at the top level, not a list or a scalar.
What the rule is
The frontmatter parsed as valid YAML, but the result isn't a mapping (key: value pairs) at the top level — it parsed as a list, a single string, or an empty document instead.
`name` and `description` are read as top-level mapping keys. If the frontmatter's root isn't a mapping, there's nothing for a runtime to read those keys from, regardless of what content follows.
Where it comes from
- Agent Skills — SpecificationSpecification
Which runtimes enforce it
| Runtime | Effect | Note |
|---|---|---|
| Claude Code | Breaks the skill | `name` and `description` are read as top-level mapping keys — nothing resolves if the root isn't a mapping. |
| Codex | Breaks the skill | `name` and `description` are read as top-level mapping keys — nothing resolves if the root isn't a mapping. |
| Cursor | Breaks the skill | `name` and `description` are read as top-level mapping keys — nothing resolves if the root isn't a mapping. |
| OpenClaw | Breaks the skill | `name` and `description` are read as top-level mapping keys — nothing resolves if the root isn't a mapping. |
| Hermes Agent | Breaks the skill | `name` and `description` are read as top-level mapping keys — nothing resolves if the root isn't a mapping. |
How to fix it
- Rewrite the frontmatter as `key: value` pairs, one per line, with `name` and `description` as top-level keys — not a list (`- item`) and not a single scalar value.
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.