claudecode-linter 2.1.148-patch.1 → 2.1.148-patch.2

package/contracts/skill-frontmatter.schema.json

@@ -1,18 +1,60 @@
 {
 	"extractedFromClaudeCodeVersion": "2.1.146",
-	"extractedAt": "2026-05-21T21:04:24.797Z",
+	"extractedAt": "2026-05-22T08:49:59.762Z",
 	"schema": {
 		"$schema": "https://json-schema.org/draft/2020-12/schema",
 		"title": "Claude Code SKILL.md frontmatter",
 		"type": "object",
 		"properties": {
 			"name": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Display name. Defaults to the filename without extension."
 			},
 			"description": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "One-line summary shown in listings and the Skill tool."
 			},
 			"model": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Model override (`haiku`, `sonnet`, `opus`, or a full ID). Use `inherit` to match the parent conversation."
 			},
 			"allowed-tools": {
@@ -43,6 +85,20 @@
 				"description": "Tools available to the model while this file is active. Comma-separated string or YAML list."
 			},
 			"argument-hint": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Placeholder text shown after the slash command name."
 			},
 			"arguments": {
@@ -73,21 +129,105 @@
 				"description": "@internal — typed variant of argument-hint; argument-hint is the documented form"
 			},
 			"disable-model-invocation": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "If true, the model cannot invoke this via the Skill tool; only users can type the slash command."
 			},
 			"user-invocable": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "If false, hides the slash command from users; only the model can invoke it via the Skill tool."
 			},
 			"effort": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Thinking effort for the model: `low`, `medium`, `high`, `max`, or an integer."
 			},
 			"shell": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Shell for `!`-command blocks: `bash` or `powershell`. Defaults to bash regardless of platform."
 			},
 			"version": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "@internal — bookkeeping, not surfaced to users"
 			},
 			"when_to_use": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Guidance for when the model should reach for this skill. Becomes part of the tool description."
 			},
 			"paths": {
@@ -129,15 +269,71 @@
 				"description": "Where the skill runs: `inline` expands into the current conversation; `fork` spawns a subagent."
 			},
 			"agent": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "Agent type to spawn when `context: fork`."
 			},
 			"fallback": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "@internal — interim defense-in-depth for thin-pointer skill stubs. If true, this skill yields to a same-suffix plugin or MCP skill (`<plugin>:<name>` / `<server>:<name>`) when one is loaded. Stubs carrying this should be deleted once their canonical plugin/MCP skill ships, not maintained."
 			},
 			"created_by": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "@internal — provenance marker (e.g. dream-proposal)"
 			},
 			"improved_by": {
+				"anyOf": [
+					{
+						"type": "string"
+					},
+					{
+						"type": "number"
+					},
+					{
+						"type": "boolean"
+					},
+					{
+						"type": "null"
+					}
+				],
 				"description": "@internal — provenance marker (e.g. dream-proposal)"
 			},
 			"mcpServers": {

package/dist/contracts.js

@@ -389,4 +389,17 @@ export const PLUGIN_SUBAGENT_BLOCKED_TOOLS = new Set([
     "Glob",
     "Grep",
 ]);
+// Hand-curated named values for the frontmatter `effort` field. The Zod
+// schema types `effort` as a permissive scalar; the field's own describe()
+// string in the Claude Code bundle reads: "Thinking effort for the model:
+// `low`, `medium`, `high`, `max`, or an integer." — so a string `effort`
+// must be one of these, and a numeric `effort` must be an integer. (The
+// runtime effortLevel enum also has `xhigh`, but the frontmatter describe
+// string deliberately omits it; we follow the frontmatter contract.)
+export const EFFORT_LEVELS = new Set([
+    "low",
+    "medium",
+    "high",
+    "max",
+]);
 //# sourceMappingURL=contracts.js.map

package/dist/linters/agent-md.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { AGENT_MODELS, AGENT_COLORS, TOOLS, PLUGIN_SUBAGENT_BLOCKED_TOOLS, } from "../contracts.js";
+import { AGENT_MODELS, AGENT_COLORS, TOOLS, PERMISSION_MODES, PLUGIN_SUBAGENT_BLOCKED_TOOLS, } from "../contracts.js";
+import { invalidEffortReason } from "../utils/effort.js";
 import { formatAjvError, loadAgentFrontmatterSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
@@ -65,6 +66,9 @@ const RULES = [
     { id: "agent-md/description-routing-guidance", defaultSeverity: "warning" },
     { id: "agent-md/model-required", defaultSeverity: "error" },
     { id: "agent-md/model-valid", defaultSeverity: "warning" },
+    { id: "agent-md/permission-mode-valid", defaultSeverity: "warning" },
+    { id: "agent-md/effort-valid", defaultSeverity: "warning" },
+    { id: "agent-md/max-turns-valid", defaultSeverity: "warning" },
     { id: "agent-md/color-required", defaultSeverity: "warning" },
     { id: "agent-md/color-valid", defaultSeverity: "warning" },
     { id: "agent-md/system-prompt-present", defaultSeverity: "error" },
@@ -158,6 +162,30 @@ export const agentMdLinter = {
             !fm.data.model.startsWith("claude-")) {
             push(diag(config, filePath, "agent-md/model-valid", "warning", `"model" must be one of: ${[...AGENT_MODELS].join(", ")} or a versioned claude-* model ID (got "${fm.data.model}")`));
         }
+        // permissionMode — typed as a permissive scalar by the Zod schema;
+        // at runtime only the PERMISSION_MODES values take effect.
+        if ("permissionMode" in fm.data) {
+            const pm = fm.data.permissionMode;
+            if (typeof pm !== "string" || !PERMISSION_MODES.has(pm)) {
+                push(diag(config, filePath, "agent-md/permission-mode-valid", "warning", `"permissionMode" must be one of: ${[...PERMISSION_MODES].join(", ")} (got ${JSON.stringify(pm)})`));
+            }
+        }
+        // effort — Zod types it as a permissive scalar; the field's describe()
+        // string restricts it to a named level or an integer.
+        if ("effort" in fm.data) {
+            const reason = invalidEffortReason(fm.data.effort);
+            if (reason) {
+                push(diag(config, filePath, "agent-md/effort-valid", "warning", reason));
+            }
+        }
+        // maxTurns — Zod accepts a string / float; only a positive integer
+        // is a meaningful turn budget.
+        if ("maxTurns" in fm.data) {
+            const mt = fm.data.maxTurns;
+            if (typeof mt !== "number" || !Number.isInteger(mt) || mt <= 0) {
+                push(diag(config, filePath, "agent-md/max-turns-valid", "warning", `"maxTurns" must be a positive integer (got ${JSON.stringify(mt)})`));
+            }
+        }
         // color
         if (!("color" in fm.data) || typeof fm.data.color !== "string") {
             push(diag(config, filePath, "agent-md/color-required", "warning", '"color" is required in frontmatter'));

package/dist/linters/command-md.js

@@ -1,12 +1,17 @@
-import { TOOLS } from "../contracts.js";
+import { AGENT_MODELS, TOOLS } from "../contracts.js";
 import { formatAjvError, loadCommandFrontmatterSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
+import { invalidEffortReason } from "../utils/effort.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
 import { artifactLabel, classifyUnknownFrontmatterKey, } from "../utils/frontmatter-keys.js";
 const RULES = [
     { id: "command-md/valid-frontmatter", defaultSeverity: "error" },
     { id: "command-md/schema-valid", defaultSeverity: "error" },
     { id: "command-md/description-required", defaultSeverity: "error" },
+    { id: "command-md/name-format", defaultSeverity: "warning" },
+    { id: "command-md/model-valid", defaultSeverity: "warning" },
+    { id: "command-md/effort-valid", defaultSeverity: "warning" },
+    { id: "command-md/frontmatter-field-type", defaultSeverity: "warning" },
     { id: "command-md/allowed-tools-valid", defaultSeverity: "warning" },
     { id: "command-md/body-present", defaultSeverity: "warning" },
     { id: "command-md/no-unknown-frontmatter", defaultSeverity: "info" },
@@ -57,6 +62,37 @@ export const commandMdLinter = {
         if (!("description" in fm.data) || typeof fm.data.description !== "string") {
             push(diag(config, filePath, "command-md/description-required", "error", "\"description\" is required in frontmatter"));
         }
+        // name — optional display-name override. Zod types it as a permissive
+        // scalar; if present it must be a non-empty string.
+        if ("name" in fm.data) {
+            const name = fm.data.name;
+            if (typeof name !== "string" || name.trim() === "") {
+                push(diag(config, filePath, "command-md/name-format", "warning", `"name" must be a non-empty string (got ${JSON.stringify(name)})`));
+            }
+        }
+        // model — Zod types it as a permissive scalar; accept a named alias or a
+        // versioned claude-* model id. Mirrors agent-md/model-valid.
+        if ("model" in fm.data && typeof fm.data.model === "string") {
+            const model = fm.data.model;
+            if (!AGENT_MODELS.has(model) && !model.startsWith("claude-")) {
+                push(diag(config, filePath, "command-md/model-valid", "warning", `"model" must be one of: ${[...AGENT_MODELS].join(", ")} or a versioned claude-* model ID (got "${model}")`));
+            }
+        }
+        // effort — Zod types it as a permissive scalar; the field's describe()
+        // string restricts it to a named level or an integer.
+        if ("effort" in fm.data) {
+            const reason = invalidEffortReason(fm.data.effort);
+            if (reason) {
+                push(diag(config, filePath, "command-md/effort-valid", "warning", reason));
+            }
+        }
+        // boolean fields — the Zod schema accepts the string "true"; only a real
+        // boolean behaves as expected.
+        for (const field of ["disable-model-invocation", "user-invocable"]) {
+            if (field in fm.data && typeof fm.data[field] !== "boolean") {
+                push(diag(config, filePath, "command-md/frontmatter-field-type", "warning", `"${field}" must be a boolean (got ${JSON.stringify(fm.data[field])})`));
+            }
+        }
         // allowed-tools
         if ("allowed-tools" in fm.data) {
             const tools = fm.data["allowed-tools"];

package/dist/linters/hooks-json.js

@@ -1,7 +1,9 @@
 import { HOOK_EVENTS, HOOK_TYPES, PROMPT_EVENTS } from "../contracts.js";
+import { formatAjvError, loadHooksJsonSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 const RULES = [
     { id: "hooks-json/valid-json", defaultSeverity: "error" },
+    { id: "hooks-json/schema-valid", defaultSeverity: "error" },
     { id: "hooks-json/root-hooks-key", defaultSeverity: "error" },
     { id: "hooks-json/valid-event-names", defaultSeverity: "error" },
     { id: "hooks-json/hook-type-required", defaultSeverity: "error" },
@@ -52,6 +54,28 @@ export const hooksJsonLinter = {
             push(diag(config, filePath, "hooks-json/valid-json", "error", "hooks.json must be a JSON object"));
             return diagnostics;
         }
+        // schema-valid — structural validation against the JSON Schema
+        // auto-extracted from Claude Code's hooks-config Zod validator (the
+        // hook-event → matcher-array map, each matcher holding a discriminated
+        // union of hook definitions). The hand-written rules below add
+        // Claude-Code-specific advice the schema can't express (hardcoded-path
+        // warnings, prompt-event-support hints, …). The extracted schema is
+        // intentionally permissive about unknown hook fields (Claude Code's hook
+        // objects are not .strict()). Skipped silently if the schema bundle isn't
+        // shipped with this install.
+        if (isRuleEnabled(config, "hooks-json/schema-valid")) {
+            const compiled = loadHooksJsonSchema();
+            if (compiled) {
+                const ok = compiled.validate(parsed);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        const firstSeg = err.instancePath.split("/").filter(Boolean)[0];
+                        const p = firstSeg ? findKeyPosition(content, firstSeg) : undefined;
+                        push(diag(config, filePath, "hooks-json/schema-valid", "error", formatAjvError(err), p?.line, p?.column));
+                    }
+                }
+            }
+        }
         const root = parsed;
         // root "hooks" key
         if (!("hooks" in root) || typeof root.hooks !== "object" || root.hooks === null) {

package/dist/linters/mcp-json.js

@@ -1,5 +1,6 @@
 import { basename } from "node:path";
 import { MCP_SERVER_FIELDS } from "../contracts.js";
+import { formatAjvError, loadMcpJsonSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { isKebabCase } from "../utils/kebab-case.js";
 // Valid `type` values for a URL-based HTTP MCP server. Claude Code v2.1.146
@@ -9,6 +10,7 @@ const HTTP_TRANSPORT_TYPES = new Set(["http", "streamable-http"]);
 const RULES = [
     { id: "mcp-json/scope-file-name", defaultSeverity: "warning" },
     { id: "mcp-json/valid-json", defaultSeverity: "error" },
+    { id: "mcp-json/schema-valid", defaultSeverity: "error" },
     { id: "mcp-json/servers-required", defaultSeverity: "error" },
     { id: "mcp-json/servers-object", defaultSeverity: "error" },
     { id: "mcp-json/server-name-kebab", defaultSeverity: "info" },
@@ -73,6 +75,28 @@ export const mcpJsonLinter = {
             push(diag(config, filePath, "mcp-json/valid-json", "error", "mcp.json must be a JSON object"));
             return diagnostics;
         }
+        // schema-valid — structural validation against the JSON Schema
+        // auto-extracted from Claude Code's .mcp.json Zod validator (the
+        // `mcpServers` record of discriminated transport configs). The hand-written
+        // rules below add Claude-Code-specific advice the schema can't express
+        // (kebab-case names, ${CLAUDE_PLUGIN_ROOT} hints, …). The extracted schema
+        // is intentionally permissive about unknown server fields (Claude Code's
+        // server union is not .strict()), so those are NOT reported here —
+        // mcp-json/no-unknown-server-fields handles them. Skipped silently if the
+        // schema bundle isn't shipped with this install.
+        if (isRuleEnabled(config, "mcp-json/schema-valid")) {
+            const compiled = loadMcpJsonSchema();
+            if (compiled) {
+                const ok = compiled.validate(parsed);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        const firstSeg = err.instancePath.split("/").filter(Boolean)[0];
+                        const p = firstSeg ? findKeyPosition(content, firstSeg) : undefined;
+                        push(diag(config, filePath, "mcp-json/schema-valid", "error", formatAjvError(err), p?.line, p?.column));
+                    }
+                }
+            }
+        }
         // mcpServers required
         if (!("mcpServers" in parsed)) {
             push(diag(config, filePath, "mcp-json/servers-required", "error", "\"mcpServers\" field is required"));

package/dist/linters/skill-md.js

@@ -1,5 +1,7 @@
+import { AGENT_MODELS, TOOLS } from "../contracts.js";
 import { formatAjvError, loadSkillFrontmatterSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
+import { invalidEffortReason } from "../utils/effort.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
 import { artifactLabel, classifyUnknownFrontmatterKey, } from "../utils/frontmatter-keys.js";
 import { isKebabCase } from "../utils/kebab-case.js";
@@ -13,6 +15,10 @@ const RULES = [
     { id: "skill-md/description-max-length", defaultSeverity: "error" },
     { id: "skill-md/description-no-angle-brackets", defaultSeverity: "error" },
     { id: "skill-md/description-trigger-phrases", defaultSeverity: "warning" },
+    { id: "skill-md/model-valid", defaultSeverity: "warning" },
+    { id: "skill-md/effort-valid", defaultSeverity: "warning" },
+    { id: "skill-md/allowed-tools-valid", defaultSeverity: "warning" },
+    { id: "skill-md/frontmatter-field-type", defaultSeverity: "warning" },
     { id: "skill-md/no-unknown-frontmatter", defaultSeverity: "info" },
     { id: "skill-md/body-word-count", defaultSeverity: "info" },
     { id: "skill-md/body-has-headers", defaultSeverity: "info" },
@@ -151,6 +157,41 @@ export const skillMdLinter = {
                     "(e.g., \"Use when…\", \"Trigger on…\", \"when the user asks to…\", or an imperative verb)"));
             }
         }
+        // model — Zod types it as a permissive scalar; accept a named alias or a
+        // versioned claude-* model id. Mirrors agent-md/model-valid.
+        if ("model" in fm.data && typeof fm.data.model === "string") {
+            const model = fm.data.model;
+            if (!AGENT_MODELS.has(model) && !model.startsWith("claude-")) {
+                push(diag(config, filePath, "skill-md/model-valid", "warning", `"model" must be one of: ${[...AGENT_MODELS].join(", ")} or a versioned claude-* model ID (got "${model}")`));
+            }
+        }
+        // effort — Zod types it as a permissive scalar; the field's describe()
+        // string restricts it to a named level or an integer.
+        if ("effort" in fm.data) {
+            const reason = invalidEffortReason(fm.data.effort);
+            if (reason) {
+                push(diag(config, filePath, "skill-md/effort-valid", "warning", reason));
+            }
+        }
+        // allowed-tools — validate built-in tool names. mcp__* patterns are
+        // dynamic (resolved at runtime); accept them. Mirrors command-md.
+        if ("allowed-tools" in fm.data) {
+            const tools = fm.data["allowed-tools"];
+            if (Array.isArray(tools)) {
+                for (const t of tools) {
+                    if (typeof t === "string" && !t.startsWith("mcp__") && !TOOLS.has(t)) {
+                        push(diag(config, filePath, "skill-md/allowed-tools-valid", "warning", `Unknown tool "${t}" in allowed-tools`));
+                    }
+                }
+            }
+        }
+        // boolean fields — the Zod schema accepts the string "true"; only a real
+        // boolean behaves as expected.
+        for (const field of ["disable-model-invocation", "user-invocable"]) {
+            if (field in fm.data && typeof fm.data[field] !== "boolean") {
+                push(diag(config, filePath, "skill-md/frontmatter-field-type", "warning", `"${field}" must be a boolean (got ${JSON.stringify(fm.data[field])})`));
+            }
+        }
         // Frontmatter keys: only flag cross-artifact misplacement. A key that is
         // valid for a *different* markdown artifact (e.g. agent's "effort" on a
         // skill) gets an info; a key valid for no artifact stays silent.

package/dist/plugin-schema.js

@@ -52,6 +52,7 @@ function loadCompiledSchema(fileName) {
     const compiled = {
         validate: getAjv().compile(wrapped.schema),
         extractedFromVersion: wrapped.extractedFromClaudeCodeVersion,
+        knownFields: new Set(Object.keys(wrapped.schema.properties ?? {})),
     };
     compiledCache.set(fileName, compiled);
     return compiled;
@@ -65,6 +66,12 @@ export function loadMonitorsSchema() {
 export function loadSettingsSchema() {
     return loadCompiledSchema("settings.schema.json");
 }
+export function loadMcpJsonSchema() {
+    return loadCompiledSchema("mcp.schema.json");
+}
+export function loadHooksJsonSchema() {
+    return loadCompiledSchema("hooks.schema.json");
+}
 export function loadSkillFrontmatterSchema() {
     return loadCompiledSchema("skill-frontmatter.schema.json");
 }

package/dist/utils/effort.js

@@ -0,0 +1,29 @@
+import { EFFORT_LEVELS } from "../contracts.js";
+/**
+ * Validate a frontmatter `effort` value against the Claude Code contract.
+ *
+ * Claude Code's frontmatter Zod schema types `effort` as a permissive scalar
+ * (`anyOf[string,number,boolean,null]`), but the field's own `.describe()`
+ * string in the bundle reads:
+ *   "Thinking effort for the model: `low`, `medium`, `high`, `max`, or an integer."
+ *
+ * So a valid `effort` is either one of the named levels (EFFORT_LEVELS) or an
+ * integer. Anything else — a non-integer number, a boolean, an unknown string,
+ * null — is reported. Returns a human-readable reason when invalid, or null
+ * when the value is acceptable.
+ */
+export function invalidEffortReason(value) {
+    const valid = [...EFFORT_LEVELS].join(", ");
+    if (typeof value === "string") {
+        if (EFFORT_LEVELS.has(value))
+            return null;
+        return `"effort" string must be one of: ${valid} (got "${value}")`;
+    }
+    if (typeof value === "number") {
+        if (Number.isInteger(value))
+            return null;
+        return `"effort" number must be an integer (got ${value})`;
+    }
+    return `"effort" must be one of: ${valid}, or an integer (got ${JSON.stringify(value)})`;
+}
+//# sourceMappingURL=effort.js.map

package/dist/utils/frontmatter-keys.js

@@ -1,9 +1,38 @@
 import { SKILL_FRONTMATTER, AGENT_FRONTMATTER, COMMAND_FRONTMATTER, } from "../contracts.js";
-const KEY_SETS = {
+import { loadSkillFrontmatterSchema, loadAgentFrontmatterSchema, loadCommandFrontmatterSchema, } from "../plugin-schema.js";
+// Census-extraction sets (scripts/extract-contracts.ts). Used only as a
+// fallback when the auto-extracted frontmatter schema is unavailable — the
+// census extractor lags the schema walker (e.g. it was missing `effort`).
+const CENSUS_FALLBACK = {
     skill: SKILL_FRONTMATTER,
     agent: AGENT_FRONTMATTER,
     command: COMMAND_FRONTMATTER,
 };
+const SCHEMA_LOADERS = {
+    skill: loadSkillFrontmatterSchema,
+    agent: loadAgentFrontmatterSchema,
+    command: loadCommandFrontmatterSchema,
+};
+const keyCache = new Map();
+/**
+ * Known frontmatter keys for an artifact — the union of the auto-extracted
+ * schema's property names (authoritative, complete, kept in sync with Claude
+ * Code's Zod) and the census-contract set. Union rather than schema-only so a
+ * key known to *either* extraction is never mis-flagged: `no-unknown-
+ * frontmatter` is advisory and a false positive is the only real harm.
+ */
+function knownKeys(kind) {
+    const cached = keyCache.get(kind);
+    if (cached)
+        return cached;
+    const merged = new Set(CENSUS_FALLBACK[kind]);
+    const schema = SCHEMA_LOADERS[kind]();
+    if (schema)
+        for (const k of schema.knownFields)
+            merged.add(k);
+    keyCache.set(kind, merged);
+    return merged;
+}
 const ARTIFACT_LABEL = {
     skill: "skill",
     agent: "agent",
@@ -18,13 +47,13 @@ const ARTIFACT_LABEL = {
  */
 export function classifyUnknownFrontmatterKey(key, self, extraKnown = new Set()) {
     // Known for the current artifact — not unknown at all.
-    if (KEY_SETS[self].has(key) || extraKnown.has(key))
+    if (knownKeys(self).has(key) || extraKnown.has(key))
         return null;
     // Valid for some *other* markdown artifact → misplacement.
     for (const kind of ["skill", "agent", "command"]) {
         if (kind === self)
             continue;
-        if (KEY_SETS[kind].has(key)) {
+        if (knownKeys(kind).has(key)) {
             return { kind: "owned-by-other", owner: kind };
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claudecode-linter",
-	"version": "2.1.148-patch.1",
+	"version": "2.1.148-patch.2",
 	"description": "Standalone linter for Claude Code plugins and configuration files",
 	"type": "module",
 	"bin": {
@@ -30,6 +30,8 @@
 		"contracts/skill-frontmatter.schema.json",
 		"contracts/agent-frontmatter.schema.json",
 		"contracts/command-frontmatter.schema.json",
+		"contracts/mcp.schema.json",
+		"contracts/hooks.schema.json",
 		".claudecode-lint.defaults.yaml",
 		"README.md"
 	],