Your Skill's Frontmatter Has a Typo. Nothing Will Ever Tell You

Description and use

frontmatter-guard detects typos in Claude Code skill frontmatter that the official validator misses, preventing silent failures.

Problem

A typo in a Claude Code skill’s frontmatter (e.g., an unknown key or misspelled hook event) can silently pass validation and never trigger the intended behavior.

Outcome

frontmatter-guard catches typos that the official validator misses, preventing silent failures and ensuring that all declared keys and hook events are valid and functional.

Workflow

• Install the tool: pip install frontmatter-guard
• Run the linter against the skill directory: frontmatter-guard check . --strict
• Review the output for errors such as unknown-key or unknown-hook-event
• Fix the reported issues in the frontmatter
• Re‑run the linter to confirm no errors remain

Evidence

effort: high was supposed to keep the model from going overboard. I ran claude plugin validate before shipping. It passed. Green. Ship it.

Source

commands/deploy.md:4: error [unknown-key] Unknown key 'effort'. fix: Remove the key -- unknown keys are silently ignored, so it currently does nothing.

Source