AXC-D022: SKILL.md frontmatter missing or invalid

SKILL.md has no YAML frontmatter, the YAML does not parse, or the required name or description is missing. An agent discovers a skill through these two fields. Without them, the skill may not load at all, or it loads with nothing an agent can choose it by.

What it checks

ax-check reads the start of each SKILL.md and checks that:

• the file starts with a --- line;
• the block is closed by a second --- line;
• the text between them parses as YAML and is a mapping of keys to values;
• name and description are both present, are text, and are not empty.

Why it matters

The Agent Skills specification makes name and description required frontmatter fields. Agents usually load only these two fields for every installed skill and read the body only when a skill looks relevant. So the frontmatter is the whole of a skill’s discovery surface. A missing block, a YAML syntax error (for example an unquoted colon in the description) or a missing field means the skill cannot be discovered the way its author intended.

Anthropic’s skill authoring guidance (vendor guidance) adds that the description “is injected into the system prompt”, which is why it must say what the skill does and when to use it.

How to fix

• Start SKILL.md with a YAML block between two --- lines.
• Set name to the skill’s folder name and description to one or two sentences of what it does and when to use it.
• Quote the description if it contains a colon followed by a space, or use a YAML block scalar.

Example

Before

# Invoice review

description: Checks draft invoices: totals, tax and due dates.

1. Open the draft invoice.
2. Compare the totals with the order.

After

---
name: invoice-review
description: "Checks a draft invoice before it is sent: totals, tax and due dates. Use this when asked to review or approve an invoice. Do not use it to create invoices."
---

# Invoice review

1. Open the draft invoice.
2. Compare the totals with the order.

How ax-check detects it

ax-check removes a leading byte order mark and converts Windows line endings first. The file must then begin with --- and a line break, and the block ends at the next line that starts with ---. The YAML in between is parsed with a standard YAML parser. A parse error is reported with the parser’s first line of explanation.

If the block parses, name and description must be non-empty strings. A description that YAML reads as a number or a list counts as missing. One finding names every missing field.

Interaction with other rules: for skills, a missing description is reported only by this rule, never also by AXC-D001 (missing description). AXC-D023 and AXC-D024 run only on fields that are present.

Known false positives: a file that begins with a blank line or a comment before --- is reported, because the block must be the very first thing in the file. If your skill loader accepts that, you can silence the rule.

If the finding does not apply, silence it with --disable AXC-D022.

Sources

• Specification: Agent Skills specification, agentskills.io, retrieved 2026-10-08. https://agentskills.io/specification. name and description are required frontmatter fields; the description is non-empty and “Describes what the skill does and when to use it.”
• Vendor guidance: Skill authoring best practices, Anthropic, retrieved 2026-10-08. https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices. “The description field enables Skill discovery”; “The description is injected into the system prompt.”

Related evidence

Records in the AX evidence register that share a pattern tag with this rule. A shared tag means the record is about the same pattern, not that it tests this rule. Read the evidence class before the number.

• EV-0019: Skill selection precision collapses as the skill pool grows (Preprint). A preprint reports that as the pool of available skills grew from 5 to 100, the precision with which agents actually used the right skill fell from 29.6% to 3.3%.
• EV-0013: FAQ blocks and structured data showed no citation effect within a domain (Preprint). An observational study of about 2 million AI-engine citations (preprint) found that FAQ blocks, structured data and Core Web Vitals had positive effects on citation in pooled data that reversed or fell to zero once domain fixed effects were applied.
• EV-0017: Injected skills lowered pass rates and raised token cost on average (Preprint). WebDev-Skills-Bench (preprint) found that injecting matched public skills reduced mean Pass@2 by 1.3% to 4.2% across four models and raised token cost by 72% to 394%, with gains in only 17% to 36% of skill-project pairs.
• EV-0018: Skill rules that name a command or path change what agents do (Preprint). A study of 3,159 skills (preprint) found that adding a checkable rule raised the rate at which four coding agents took the required action by +0.23 on average, with the gain coming mainly from rules naming a command or path the old skill did not mention.
• EV-0023: Hiding tools is not enforcing permissions (Preprint). Across 2,160 attempts with four frontier models (preprint), a server with only in-body permission checks exposed forbidden tools in 152 of 720 trials and permission-aware visibility cut that to 0 of 720, yet models named a hidden tool in up to 94% of settings when it was inferable from the prompt.
• EV-0027: A capable agent skipped the index and guessed the page (Preprint). A preregistered ablation on a 709-page Markdown wiki (preprint) found that a capable tool-using agent never loaded the compact catalogue index, inferring page paths from the question instead, while retrieval-based access kept answer quality non-inferior and cut cost by about a third to over half.

Related guides

• Write agent-readable documentation
• Agent tool catalogues need a pruning strategy
• Agentic Resource Discovery, implemented