{
  "id": 13686906,
  "title": "Your Skill's Frontmatter Has a Typo. Nothing Will Ever Tell You",
  "url": "https://urgent.news/2026/10/11/your-skills-frontmatter-has-a-typo-nothing-will-ever-tell-you",
  "topic": "ai",
  "section": "AI",
  "published": "2026-10-11T09:28:41.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/haoli/your-skills-frontmatter-has-a-typo-nothing-will-ever-tell-you-18b5"
  },
  "original_language": "en",
  "account": "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:\n\n```yaml\nname: deploy-helper\ndescription: Helps with deployments\neffort: high\n```\n\nEffort 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.",
  "summary": "Your skill's frontmatter has a typo. Nothing will ever tell you. A few days ago I shipped a Claude Code command with this frontmatter: --- name : deploy-helper description : \" Helps with deployments\" effort : high --- effort: high was supposed to keep the model from going overboard. I ran claude plugin validate before shipping. It passed. Green. Ship it. Except effort is not a Claude Code…",
  "key_points": [
    "Frontmatter-guard is a semantic linter for skill and plugin frontmatter.",
    "It detects unknown keys, unknown hook events, missing fields, and incorrect types.",
    "The tool provides file:line information, rule names, and concrete fix suggestions."
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}