skill-frontmatter-doctor

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:

# BAD — echoes the description, one entry, trails off
triggers:
  - "Use when the user asks to author or scaffold a skill and"

# GOOD — distinct, concrete, complete
triggers:
  -