frontmatter-not-line-1

What it catches#

Frontmatter does not start on line 1.

A --- block with key: value lines that starts after a blank line, a title or a comment. Claude Code, Cursor, Copilot and the Agent Skills validators all look for --- on line 1 and nowhere else. The block is still in the file, so it looks fine in an editor, but every tool treats it as body text.

Why it matters#

Agent tools only read YAML frontmatter that starts on the first line. Blank lines or text above it turn the whole block into body text, so name, description and paths are lost.

# Release notes skill

---
name: release-notes
description: Draft release notes from merged PRs. Use when asked for a changelog or release summary.
---

Collect merged PRs since the last tag...

---
name: release-notes
description: Draft release notes from merged PRs. Use when asked for a changelog or release summary.
---

# Release notes skill

Collect merged PRs since the last tag...

How to fix#

Delete everything above the opening ---, including blank lines, and move the title below the closing ---. If the first line is a <!-- comment -->, move it below too.

asitis can make this edit for you. asitis lint --fix-preview prints a unified diff that git apply accepts, and the suggest_fixes MCP tool returns the same diff; nothing is written to disk by either. The fix for this rule is marked safe: it does not change what the file says.

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-line-1 -- why this one is fine -->

For a whole file:

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

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

{ "rules": { "frontmatter-not-line-1": "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#

Claude Code docs: Skills, read on 14 October 2026.