unknown-key

What it catches#

A frontmatter key the reading tool ignores.

A frontmatter key that the tool reading the file does not know. When the key is one or two edits from a real one (user-invokable for user-invocable) and its value is the kind the real key takes (a boolean for user-invocable), it is a warning, because it is almost always a typo that silently turns the option off. Otherwise it is a note: the key does nothing. In a SKILL.md the note adds that claude.ai and the Claude API reject an upload with keys outside the spec, and suggests moving your own data under metadata:.

Why it matters#

An ignored key does nothing. When it is one or two letters away from a real key it is reported as a warning, because it is almost always a typo.

---
name: scaffold
description: Scaffold a new package in the monorepo. Use when asked to create a package or module.
user-invokable: false
allowed_tools: Bash(pnpm *)
---

---
name: scaffold
description: Scaffold a new package in the monorepo. Use when asked to create a package or module.
user-invocable: false
allowed-tools: Bash(pnpm *)
---

How to fix#

Use the spelling from the message. Keys are case-sensitive and use hyphens in skills and commands (allowed-tools), camelCase in subagents (permissionMode) and Cursor rules (alwaysApply). A Claude Code rule in .claude/rules/ reads paths only. For a key that is not a typo, either remove it or move it under metadata, which the spec reserves for extra data.

asitis can propose this edit. asitis lint --fix-preview prints a unified diff that git apply accepts, and the suggest_fixes MCP tool returns the same diff; nothing is written to disk by either. The fix for this rule needs review before you apply it, because it changes or removes content.

Suppress or configure#

For one finding, put a comment on the line above it. The reason after -- is optional but worth writing:

<!-- asitis-disable-next-line unknown-key -- why this one is fine -->

For a whole file:

<!-- asitis-disable-file unknown-key -- why this file is an exception -->

For every file, turn it off or change its severity in .asitisrc.json:

{ "rules": { "unknown-key": "off" } }

A .asitisrc.json overrides entry limits a change to some paths, and a baseline (asitis lint --format json --write-baseline) accepts today's findings so only new ones fail the build.

Source#

Claude Code docs: Skills, read on 14 October 2026.