| name | skill-frontmatter-doctor |
| description | Use when authoring or reviewing a SKILL.md or agent .md and you need to detect and fix the four most common frontmatter defects — echoed or truncated triggers, tools written as a YAML array instead of a comma-separated string, a description outside the 1-1024 character bound, and a missing "Use when..." clause. |
| description-frequency | on-demand |
| user-invocable | true |
| version | 1.0.0 |
| format | "2025-10-02T00:00:00.000Z" |
| triggers | ["authoring or reviewing a SKILL.md or agent .md for frontmatter defects","fix malformed skill frontmatter, triggers, tools array, or description length"] |
| updated | "2026-07-06T00:00:00.000Z" |
| status | ACTIVE |
Skill Frontmatter Doctor
Detect and fix the four highest-frequency defects in skill and agent
frontmatter. This is the corpus-wide #1 defect class, and there is no
deterministic guard for it — so treat this checklist as the guard.
Run the advisory linter first to get a candidate list:
node tools/skill-frontmatter-doctor.mjs
It scans .claude/skills/**/SKILL.md, .claude/agents/*.md,
project-claude/skills/**/SKILL.md and project-claude/agents/*.md,
prints a report, and always exits 0 (advisory, not a gate). Use its
output to target the fixes below, then verify by re-reading the file.
The four defect classes
1. Echoed or truncated triggers
A triggers: entry must be a distinct, usable keyword or phrase a user
would actually type — not a copy of the description and not a fragment
that was cut mid-thought.
Recognize a bad trigger when it:
- Echoes the description — the trigger string is a substring of the
description (or vice versa). A trigger that just repeats the
description adds no routing signal.
- Ends mid-word — the last token is a partial word (a truncation
artifact, e.g.
"...author a new cartri").
- Ends at a conjunction or preposition — trails off on
and, or, but, with, for, to, of, the, a, an
(e.g. "scaffold a department and").
- Ends at an open parenthesis — an unbalanced
( signals a clipped
phrase (e.g. "build a content cartridge (").
Fix: replace with short, self-contained phrases the user would say.
Prefer several concrete invocations over one long echo of the
description. Example:
triggers:
- "Use when the user asks to author or scaffold a skill and"
triggers:
-
