skill-frontmatter-quality
Skill frontmatter quality
A SKILL.md description: field is the only thing an agent runtime sees when deciding whether to load the skill. If the description is vague, missing trigger keywords, or wanders off the house voice, the skill won't be discovered and the work that went into the body is wasted.
When reviewing a PR that adds or modifies a skills/*/SKILL.md, surface issues from these buckets only:
Flag these
-
Missing trigger surface. The description does not name the situation, file type, or user action that should load the skill. An actionable description leads with the imperative verb ("Flag", "Review", "Use when…") and names the artifact ("PRs that change…", "frontend code with…"). Quote the offending description and propose a rewrite.
-
Topic-not-trigger. The description names the topic the skill addresses but not the moment of use. "Reviews code for performance issues" is topic-only; "Apply to PRs that add database queries, batch jobs, or render-blocking JS" is a trigger.
-
Restates the name. The description is a verbose synonym of the directory name.
name: test-discipline+description: "Skill for test discipline"carries no signal an agent can search on. Demand concrete buckets. -
Voice drift. The house voice in this catalog is terse, prescriptive, second-person imperative. Flag deviations: "we recommend", "you should consider", marketing copy ("supercharge your reviews"), exclamation marks, emoji in descriptions, hedging ("might want to", "could be useful").
-
Frontmatter-body mismatch. The frontmatter promises one thing (e.g. "flag X, Y, Z") and the body delivers a different list. Quote both. The description is the contract — fix whichever side is wrong.
-
kindthat does not match what the skill judges. A skill about prose carryingkind: rulecan be the sole citation for a finding about code behaviour, which SPEC §2.2 reserves forruleskills. Check the body against the value: code correctness →rule, shipped prose →writing, the rendered surface →design. An absentkindmeansrule, so omitting it on a prose skill has the same effect as declaring it wrongly.