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

Your skill's frontmatter has a typo. Anything you write may remain unnoticed. A few days ago, I shipped a Claude Code command with a frontmatter entry that contained a mistake. The frontmatter looked like this:

```yaml

name: deploy-helper

description: Helps with deployments

effort: high

```

Effort was intended to prevent the model from exceeding its capabilities. Before releasing, I ran the claude plugin validate command. It returned a green, indicating the command was valid. However, effort is not a valid key for a Claude Code frontmatter. It's a Codex concept. When the entry was shipped, the official validator silently ignored the error.

This behavior is the most frustrating aspect: not the crash, but the silent failure. A misspelled PreToolUs hook would not execute, a licence key would never be issued, and reading your own configuration would show it as correct, yet it would do nothing forever. To address this issue, I created frontmatter-guard: a semantic linter for skill and plugin frontmatter.

It knows the correct key vocabulary and hook event list, and it fails loudly if you deviate from it. To use it, install it with pip install frontmatter-guard, and then run frontmatter-guard check .claude/ --strict commands/deploy.md. The linter will report errors for unknown keys and hook events. Unknown keys are error codes, while unknown hook events also produce an error.

The tool checks for unknown keys (an error), unknown hook events (an error), missing required fields (an error), incorrect hook types (a warning), and incorrectly formatted YAML (a warning). It also provides file:line information, the rule name, and a concrete fix suggestion for every finding. The exit codes are CI-ready: 1 on any error or warning (strict mode), 0 when clean, and 2 on usage errors.

It supports JSON output for machine parsing. The official validator answers a different question: "will this plugin load?" - compatibility and structure. Frontmatter-guard asks "does everything you wrote actually do something?" - semantic strictness. Both tools complement each other, not compete with one another. Frontmatter-guard has zero dependencies, is compatible with Python 3.9+, and uses a hand-rolled YAML parser from the standard library to ensure compatibility with locked-down CI runners.

It works with both *.md frontmatter (skills, commands) and plugin.json files. Try it now with pip install frontmatter-guard frontmatter-guard check . --strict. If it catches a typo that could have silently shipped, that's exactly what it's designed to do.