frontmatter-not-mapping

What it catches#

Frontmatter is valid YAML but not a key: value mapping.

Frontmatter that parses as a list, a number or a plain string instead of key: value pairs. Every tool that reads frontmatter expects a mapping at the top level.

Why it matters#

Every tool expects a mapping. A list or a bare string gives no fields at all.

---
- name: lint-fix
- description: Fix lint errors in changed files.
---

---
name: lint-fix
description: Fix lint errors in changed files. Use after a lint failure or when asked to clean up warnings.
---

How to fix#

Remove the list markers so each field is key: value at the left margin. If the block holds a single word or sentence, it was probably meant to be the title; move it below the frontmatter and add real fields.

Suppress or configure#

For one finding, put a comment on the line above it. The reason after -- is optional but worth writing:

<!-- asitis-disable-next-line frontmatter-not-mapping -- why this one is fine -->

For a whole file:

<!-- asitis-disable-file frontmatter-not-mapping -- why this file is an exception -->

For every file, turn it off or change its severity in .asitisrc.json:

{ "rules": { "frontmatter-not-mapping": "off" } }

A .asitisrc.json overrides entry limits a change to some paths, and a baseline (asitis lint --format json --write-baseline) accepts today's findings so only new ones fail the build.

Source#

Agent Skills specification, read on 14 October 2026.