You wrote the skill. You dropped it in the folder. Your agent ignores it — and says nothing.

There is a specific, annoying failure mode in AI coding agents. You spend an hour writing a detailed instruction file, install it, and the agent either never fires it, fires it at the wrong moment, or half-follows it and improvises the rest.

Nine times out of ten it isn’t the model. It’s the file. A SKILL.md is executed by a language model reading it, so its reliability is decided by how precisely it’s written — and how cleanly it parses. I’ve built dozens of these packages for Claude Code, Cursor, Codex CLI, OpenCode and OpenClaw, and the same eight breakages show up again and again. Here they are, plus the thirty-second check that catches all of them.

What a SKILL.md actually is

Strip away the branding and a skill is just a folder:

my-skill/
├── SKILL.md          # YAML frontmatter + the instructions
├── reference.md      # optional: docs the skill loads on demand
├── scripts/          # optional: helper scripts the agent may call
└── examples.md       # optional: worked examples

The part most people miss: your agent reads the frontmatter description and decides from it whether to use the skill at all. Everything in the body is wasted if the description doesn’t match the moment the user is in — and none of it loads if the YAML above it doesn’t parse.

Which is why most “my skill doesn’t work” reports are really YAML bugs.

The eight breakages

1. An unquoted colon inside a value

name: my-skill
description: A validator: checks SKILL.md files   # ❌ second colon breaks it

YAML throws a parse error — and here is the part that hurts: when the frontmatter doesn’t parse, the agent drops the entire block. Your skill loads with no name, no description, and no trigger. Almost every “the agent ignores my skill” report traces back to this one line.

description: "A validator: checks SKILL.md files"   # ✅ quoted

Rule: if a value contains :, #, or starts with a special character, quote it.

2. A value that parses as the wrong type

metadata:
  version: 1.10        # ❌ YAML reads this as the float 1.1

YAML guesses types for you. Unquoted, 1.10 becomes the float 1.1, and bare yes / no / on become booleans — so a value you meant as text silently changes shape. If it should stay a string, quote it. (metadata is the spec’s sanctioned free-form map for exactly this kind of data.)

metadata:
  version: "1.10"      # ✅ the string you actually wrote

3. Trailing commas in inline lists

allowed-tools: [Read, Grep,]

A trailing comma in a YAML flow list is invalid; strict parsers reject the block outright. Drop the comma: allowed-tools: [Read, Grep].

4. Mixed indentation and list styles

Tabs where YAML expects spaces, or a list that switches between - and * halfway down. It parses until it doesn’t, then the whole frontmatter block is discarded — and your skill installs with no metadata at all.

5. A description that states a topic, not a trigger

This one is invisible to any parser and is the most expensive:

description: "Helps with code review"          # topic — when does it fire?

An agent decides whether to load the skill from the description. A topic gives it nothing to match against. Write it as an activation condition:

description: "Use when the user pastes a diff and asks whether it is safe to merge, or asks to review a PR for security issues. Reports findings by severity. Does not run the code."

When to use this + what it does + when not to. Agents are literal. Be literal.

6. Steps that describe outcomes, not actions

“Consider the trade-offs and produce a good summary” produces a different answer every run. “Step 1: list every changed file. Step 2: classify each as added/modified/deleted. Step 3: output a table with columns X, Y, Z” produces the same shape every time. Number the steps; one action each.

7. No boundaries

A skill that says what to do but not what to avoid will drift — fetching the network when it shouldn’t, editing files outside the target directory, inventing paths. Add the short “do not” list. It’s half the specification.

8. No success check

If the skill can’t tell when it’s done, you become the reviewer. Define “done”: “a table with columns X, Y, Z and a file:line source on every row.” A self-check turns the agent into its own first pass.

The one-pass check

Breakages 1–4 are the ones that make a skill silently fail to load, and they’re mechanical — a parser can catch every one. I got tired of eyeballing frontmatter, so I wrote a validator.

skl-validator reads a SKILL.md, parses the frontmatter, walks a nine-point checklist (frontmatter keys, required sections, kebab-case naming, description quality, fenced code, no secrets), and returns a verdict —

Verdict: REVISE

Findings
- [FAIL] SKILL.md:4  Unquoted colon in `description`
         fix: description: "A validator: checks SKILL.md"
- [WARN] SKILL.md:9  Trailing comma in `allowed-tools`
         fix: allowed-tools: [Read, Grep]
- [FAIL] Section     Missing `## Triggers`
         fix: add a Triggers section listing activation phrases

Checklist: 7 pass · 2 fail · 1 warn

— with a file:line and a concrete fix for each finding. It’s instruction-only (it runs inside your agent, reads the file, prints the report); nothing leaves your machine. It’s free on Agensi:

Install the free SKILL.md validator →

Why a validator matters more than it sounds

A skill is software that a model executes by reading it. The parser is the compiler; the description is the entry point; the steps are the function body. When the “compiler” fails, it fails silently — the skill just doesn’t exist to the agent. Catching that in one pass, before you spend the next hour debugging the model, is the highest-leverage thirty seconds in skill-building.

The rest of the toolkit

The validator is the free one. Around it I built a small series of $5 micro-skills that fix the annoying parts of keeping skills healthy:

  • YAML Frontmatter Fixer — repairs the four frontmatter breakages above and shows a before/after for each fix.
  • SKILL.md Snippet Generator — scaffolds a valid, structured SKILL.md from a one-liner.
  • Markdown Link Checker — finds broken relative links in your skill docs.
  • Git Changed-Scope Lister — ranks your uncommitted changes by churn before an agent run.
  • Context Offload Hint — decides FITS / TRIM / OFFLOAD before you paste 40k tokens.

All one-time purchases, no subscription. Start with the free validator:

Get the free SKILL.md validator →


AI assistance was used in authoring this article and in the tools described. Products are sold through Agensi’s marketplace checkout; each listing states its own pricing and refund terms.