claudecode-linter 2.1.144 → 2.1.148

package/dist/linters/settings-json.js

@@ -1,15 +1,27 @@
 import { basename } from "node:path";
-import { SETTINGS_USER_FIELDS, SETTINGS_PROJECT_FIELDS, TOOLS } from "../contracts.js";
+import { SETTINGS_USER_FIELDS, SETTINGS_PROJECT_FIELDS, TOOLS, PERMISSIONS_FIELDS, PERMISSION_MODES, SANDBOX_FIELDS, SANDBOX_NETWORK_FIELDS, SANDBOX_FILESYSTEM_FIELDS, } from "../contracts.js";
+import { formatAjvError, loadSettingsSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 const RULES = [
     { id: "settings-json/valid-json", defaultSeverity: "error" },
+    { id: "settings-json/schema-valid", defaultSeverity: "error" },
     { id: "settings-json/scope-file-name", defaultSeverity: "error" },
     { id: "settings-json/scope-field", defaultSeverity: "warning" },
     { id: "settings-json/no-unknown-fields", defaultSeverity: "warning" },
     { id: "settings-json/permissions-object", defaultSeverity: "error" },
+    { id: "settings-json/permissions-unknown-field", defaultSeverity: "warning" },
+    { id: "settings-json/permissions-default-mode", defaultSeverity: "warning" },
+    { id: "settings-json/permissions-disable-bypass", defaultSeverity: "warning" },
+    { id: "settings-json/permissions-field-type", defaultSeverity: "warning" },
     { id: "settings-json/allow-array", defaultSeverity: "error" },
     { id: "settings-json/allow-known-tools", defaultSeverity: "warning" },
     { id: "settings-json/deny-array", defaultSeverity: "error" },
+    { id: "settings-json/ask-array", defaultSeverity: "error" },
+    { id: "settings-json/permission-rule-syntax", defaultSeverity: "error" },
+    { id: "settings-json/permission-rule-pattern", defaultSeverity: "error" },
+    { id: "settings-json/sandbox-object", defaultSeverity: "error" },
+    { id: "settings-json/sandbox-unknown-field", defaultSeverity: "warning" },
+    { id: "settings-json/sandbox-field-type", defaultSeverity: "warning" },
     { id: "settings-json/env-object", defaultSeverity: "error" },
     { id: "settings-json/env-string-values", defaultSeverity: "warning" },
     { id: "settings-json/plugins-object", defaultSeverity: "error" },
@@ -17,6 +29,154 @@ const RULES = [
     { id: "settings-json/plugins-format", defaultSeverity: "warning" },
     { id: "settings-json/skip-prompt-boolean", defaultSeverity: "error" },
 ];
+// Expected type for each known sandbox sub-key, and for the nested
+// network/filesystem objects. Mirrors Claude Code's Zod schema.
+const SANDBOX_FIELD_TYPES = {
+    enabled: "boolean",
+    failIfUnavailable: "boolean",
+    autoAllowBashIfSandboxed: "boolean",
+    allowUnsandboxedCommands: "boolean",
+    enableWeakerNestedSandbox: "boolean",
+    enableWeakerNetworkIsolation: "boolean",
+    excludedCommands: "string-array",
+    network: "object",
+    filesystem: "object",
+    ripgrep: "object",
+    ignoreViolations: "object",
+    bwrapPath: "string",
+};
+const NETWORK_FIELD_TYPES = {
+    allowedDomains: "string-array",
+    deniedDomains: "string-array",
+    allowManagedDomainsOnly: "boolean",
+    allowUnixSockets: "string-array",
+    allowAllUnixSockets: "boolean",
+    allowLocalBinding: "boolean",
+    allowMachLookup: "string-array",
+    httpProxyPort: "number",
+    socksProxyPort: "number",
+    tlsTerminate: "object",
+};
+const FILESYSTEM_FIELD_TYPES = {
+    allowWrite: "string-array",
+    denyWrite: "string-array",
+    denyRead: "string-array",
+    allowRead: "string-array",
+    allowManagedReadPathsOnly: "boolean",
+};
+// sandbox.network.tlsTerminate — a small nested object of optional paths.
+const TLS_TERMINATE_FIELD_TYPES = {
+    caCertPath: "string",
+    caKeyPath: "string",
+};
+// Tool classes that drive per-rule pattern validation (Claude Code's `Fx$`).
+const FILE_PATTERN_TOOLS = new Set(["Read", "Write", "Edit", "Glob", "NotebookRead", "NotebookEdit"]);
+const BASH_PREFIX_TOOLS = new Set(["Bash"]);
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function typeMatches(expected, val) {
+    switch (expected) {
+        case "boolean": return typeof val === "boolean";
+        case "string": return typeof val === "string";
+        case "number": return typeof val === "number";
+        case "string-array": return isStringArray(val);
+        case "object": return isPlainObject(val);
+    }
+}
+function articleType(expected) {
+    switch (expected) {
+        case "boolean": return "a boolean";
+        case "string": return "a string";
+        case "number": return "a number";
+        case "string-array": return "an array of strings";
+        case "object": return "an object";
+    }
+}
+/**
+ * Lightweight permission-rule syntax check, mirroring the syntactic rejections
+ * of Claude Code's runtime rule validator (the per-tool pattern grammar is
+ * deliberately not reproduced). Returns an error description, or null if the
+ * rule is syntactically well-formed.
+ */
+function ruleSyntaxError(rule) {
+    if (rule.trim() === "")
+        return "permission rule cannot be empty";
+    const opens = (rule.match(/\(/g) ?? []).length;
+    const closes = (rule.match(/\)/g) ?? []).length;
+    if (opens !== closes)
+        return "mismatched parentheses";
+    if (/\(\s*\)/.test(rule)) {
+        const before = rule.slice(0, rule.indexOf("(")).trim();
+        return before === ""
+            ? "empty parentheses with no tool name"
+            : `empty parentheses — use "${before}" alone, or specify a pattern`;
+    }
+    const parenIdx = rule.indexOf("(");
+    const toolName = (parenIdx === -1 ? rule : rule.slice(0, parenIdx)).trim();
+    if (toolName === "")
+        return "tool name cannot be empty";
+    if (rule.startsWith("mcp__")) {
+        return parenIdx === -1
+            ? null
+            : "MCP rules do not support patterns in parentheses";
+    }
+    if (!toolName.includes("_") && toolName[0] !== toolName[0].toUpperCase()) {
+        return "tool names must start with an uppercase letter";
+    }
+    return null;
+}
+/**
+ * Split a syntactically valid rule into its tool name and parenthesized
+ * pattern. `content` is null for a bare tool or a `()` / `(*)` wildcard.
+ */
+function parseRule(rule) {
+    const open = rule.indexOf("(");
+    if (open === -1)
+        return { toolName: rule.trim(), content: null };
+    const inner = rule.slice(open + 1, rule.lastIndexOf(")"));
+    return {
+        toolName: rule.slice(0, open).trim(),
+        content: inner === "" || inner === "*" ? null : inner,
+    };
+}
+/**
+ * Per-tool pattern validation, mirroring Claude Code's `Fx$` rule table:
+ * WebSearch/WebFetch custom validators, the Bash `:*` prefix marker, and the
+ * file-pattern tools that reject `:*`. Returns an error description or null.
+ */
+function ruleContentError(toolName, content) {
+    if (toolName === "WebSearch") {
+        if (content.includes("*") || content.includes("?")) {
+            return "WebSearch rules do not support wildcards (* or ?)";
+        }
+    }
+    else if (toolName === "WebFetch") {
+        if (content.includes("://") || content.startsWith("http")) {
+            return "WebFetch rules use \"domain:hostname\" format, not URLs";
+        }
+        if (!content.startsWith("domain:")) {
+            return "WebFetch rules must use the \"domain:\" prefix";
+        }
+    }
+    else if (BASH_PREFIX_TOOLS.has(toolName)) {
+        if (content.includes(":*") && !content.endsWith(":*")) {
+            return "the \":*\" prefix marker must be at the end of the pattern";
+        }
+        if (content === ":*") {
+            return "the command prefix before \":*\" cannot be empty";
+        }
+    }
+    else if (FILE_PATTERN_TOOLS.has(toolName)) {
+        if (content.includes(":*")) {
+            return "the \":*\" syntax is Bash-only — use glob patterns (* or **) for files";
+        }
+    }
+    return null;
+}
 function findKeyPosition(content, key) {
     const re = new RegExp(`"${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"\\s*:`);
     const match = re.exec(content);
@@ -60,6 +220,28 @@ export const settingsJsonLinter = {
             push(diag(config, filePath, "settings-json/valid-json", "error", "settings.json must be a JSON object"));
             return diagnostics;
         }
+        // schema-valid — defer to the JSON Schema auto-extracted from Claude Code's
+        // settings validator for the ~113 structurally-unchecked top-level fields.
+        // The hand-written rules below cover Claude-Code-specific advice the schema
+        // can't express (permission-rule syntax, scope semantics, …) with friendlier
+        // messages. The extracted schema is intentionally permissive at the top
+        // level (Claude Code uses .passthrough()), so unknown keys are NOT reported
+        // here — settings-json/no-unknown-fields handles those. Skipped silently if
+        // the schema bundle isn't shipped with this install.
+        if (isRuleEnabled(config, "settings-json/schema-valid")) {
+            const compiled = loadSettingsSchema();
+            if (compiled) {
+                const ok = compiled.validate(parsed);
+                if (!ok && compiled.validate.errors) {
+                    const filtered = summarizeErrors(compiled.validate.errors);
+                    for (const err of filtered) {
+                        const firstSeg = err.instancePath.split("/").filter(Boolean)[0];
+                        const p = firstSeg ? findKeyPosition(content, firstSeg) : undefined;
+                        push(diag(config, filePath, "settings-json/schema-valid", "error", formatAjvError(err), p?.line, p?.column));
+                    }
+                }
+            }
+        }
         // Scope-aware: settings.json (non-local) should only be at user level
         if (!isLocal && scope && scope !== "user") {
             push(diag(config, filePath, "settings-json/scope-file-name", "error", `"settings.json" should only exist at user level (~/.claude/). Use "settings.local.json" for project-level settings`));
@@ -78,46 +260,151 @@ export const settingsJsonLinter = {
                 }
             }
         }
+        // Validate the sub-keys of a nested object against a known-field set and a
+        // type map (used for sandbox.network and sandbox.filesystem).
+        const checkNested = (obj, prefix, known, types) => {
+            for (const [key, val] of Object.entries(obj)) {
+                const kp = findKeyPosition(content, key);
+                if (!known.has(key)) {
+                    push(diag(config, filePath, "settings-json/sandbox-unknown-field", "warning", `Unknown field "${prefix}.${key}"`, kp?.line, kp?.column));
+                    continue;
+                }
+                const expected = types[key];
+                if (expected && !typeMatches(expected, val)) {
+                    push(diag(config, filePath, "settings-json/sandbox-field-type", "warning", `"${prefix}.${key}" should be ${articleType(expected)}`, kp?.line, kp?.column));
+                }
+            }
+        };
         // permissions
         if ("permissions" in parsed) {
             const perms = parsed.permissions;
             const pp = findKeyPosition(content, "permissions");
-            if (typeof perms !== "object" || perms === null || Array.isArray(perms)) {
+            if (!isPlainObject(perms)) {
                 push(diag(config, filePath, "settings-json/permissions-object", "error", "\"permissions\" must be an object", pp?.line, pp?.column));
             }
             else {
                 const p = perms;
-                // allow list
-                if ("allow" in p) {
-                    const ap = findKeyPosition(content, "allow");
-                    if (!Array.isArray(p.allow)) {
-                        push(diag(config, filePath, "settings-json/allow-array", "error", "\"permissions.allow\" must be an array of strings", ap?.line, ap?.column));
+                // unknown permissions sub-keys
+                for (const key of Object.keys(p)) {
+                    if (!PERMISSIONS_FIELDS.has(key)) {
+                        const kp = findKeyPosition(content, key);
+                        push(diag(config, filePath, "settings-json/permissions-unknown-field", "warning", `Unknown field "permissions.${key}"`, kp?.line, kp?.column));
                     }
-                    else {
-                        for (const entry of p.allow) {
-                            if (typeof entry !== "string") {
-                                push(diag(config, filePath, "settings-json/allow-array", "error", `"permissions.allow" entries must be strings (got ${typeof entry})`, ap?.line, ap?.column));
+                }
+                // allow / deny / ask — each an array of permission-rule strings
+                const checkRuleArray = (name, arrayRuleId) => {
+                    if (!(name in p))
+                        return;
+                    const kp = findKeyPosition(content, name);
+                    if (!Array.isArray(p[name])) {
+                        push(diag(config, filePath, arrayRuleId, "error", `"permissions.${name}" must be an array of strings`, kp?.line, kp?.column));
+                        return;
+                    }
+                    for (const entry of p[name]) {
+                        if (typeof entry !== "string") {
+                            push(diag(config, filePath, arrayRuleId, "error", `"permissions.${name}" entries must be strings (got ${typeof entry})`, kp?.line, kp?.column));
+                            continue;
+                        }
+                        // Syntax first — a malformed rule string is rejected at runtime.
+                        const syntaxErr = ruleSyntaxError(entry);
+                        if (syntaxErr) {
+                            push(diag(config, filePath, "settings-json/permission-rule-syntax", "error", `Invalid permission rule "${entry}" in permissions.${name}: ${syntaxErr}`, kp?.line, kp?.column));
+                            continue;
+                        }
+                        // Per-tool pattern grammar (Bash :* placement, WebFetch domain:, …).
+                        const { toolName, content: ruleContent } = parseRule(entry);
+                        if (ruleContent !== null) {
+                            const patternErr = ruleContentError(toolName, ruleContent);
+                            if (patternErr) {
+                                push(diag(config, filePath, "settings-json/permission-rule-pattern", "error", `Invalid permission rule "${entry}" in permissions.${name}: ${patternErr}`, kp?.line, kp?.column));
                                 continue;
                             }
-                            // Extract base tool name from scoped pattern like "Bash(cmd:*)"
-                            const toolMatch = entry.match(/^([A-Za-z]+)(\(.*\))?$/);
-                            if (toolMatch) {
-                                const toolName = toolMatch[1];
-                                if (!TOOLS.has(toolName)) {
-                                    // Allow MCP tool patterns (mcp__*)
-                                    if (!entry.startsWith("mcp__")) {
-                                        push(diag(config, filePath, "settings-json/allow-known-tools", "warning", `Unknown tool "${toolName}" in permissions.allow`, ap?.line, ap?.column));
-                                    }
-                                }
-                            }
                         }
+                        // Rules are "Tool" or "Tool(specifier)". Warn on a base tool name
+                        // Claude Code does not expose (mcp__* is dynamic).
+                        const toolMatch = entry.match(/^([A-Za-z]+)(\(.*\))?$/);
+                        if (toolMatch && !TOOLS.has(toolMatch[1]) && !entry.startsWith("mcp__")) {
+                            push(diag(config, filePath, "settings-json/allow-known-tools", "warning", `Unknown tool "${toolMatch[1]}" in permissions.${name}`, kp?.line, kp?.column));
+                        }
+                    }
+                };
+                checkRuleArray("allow", "settings-json/allow-array");
+                checkRuleArray("deny", "settings-json/deny-array");
+                checkRuleArray("ask", "settings-json/ask-array");
+                // defaultMode — must be a known permission mode
+                if ("defaultMode" in p) {
+                    const mp = findKeyPosition(content, "defaultMode");
+                    if (typeof p.defaultMode !== "string" || !PERMISSION_MODES.has(p.defaultMode)) {
+                        push(diag(config, filePath, "settings-json/permissions-default-mode", "warning", `"permissions.defaultMode" should be one of: ${[...PERMISSION_MODES].join(", ")}`, mp?.line, mp?.column));
                     }
                 }
-                // deny list
-                if ("deny" in p) {
-                    const dp = findKeyPosition(content, "deny");
-                    if (!Array.isArray(p.deny)) {
-                        push(diag(config, filePath, "settings-json/deny-array", "error", "\"permissions.deny\" must be an array of strings", dp?.line, dp?.column));
+                // disableBypassPermissionsMode — the only accepted value is "disable"
+                if ("disableBypassPermissionsMode" in p && p.disableBypassPermissionsMode !== "disable") {
+                    const dp = findKeyPosition(content, "disableBypassPermissionsMode");
+                    push(diag(config, filePath, "settings-json/permissions-disable-bypass", "warning", "\"permissions.disableBypassPermissionsMode\" only accepts the string \"disable\"", dp?.line, dp?.column));
+                }
+                // additionalDirectories — array of strings
+                if ("additionalDirectories" in p && !isStringArray(p.additionalDirectories)) {
+                    const ap = findKeyPosition(content, "additionalDirectories");
+                    push(diag(config, filePath, "settings-json/permissions-field-type", "warning", "\"permissions.additionalDirectories\" should be an array of strings", ap?.line, ap?.column));
+                }
+                // disableAutoMode — boolean
+                if ("disableAutoMode" in p && typeof p.disableAutoMode !== "boolean") {
+                    const ap = findKeyPosition(content, "disableAutoMode");
+                    push(diag(config, filePath, "settings-json/permissions-field-type", "warning", "\"permissions.disableAutoMode\" should be a boolean", ap?.line, ap?.column));
+                }
+            }
+        }
+        // sandbox
+        if ("sandbox" in parsed) {
+            const sandbox = parsed.sandbox;
+            const sp = findKeyPosition(content, "sandbox");
+            if (!isPlainObject(sandbox)) {
+                push(diag(config, filePath, "settings-json/sandbox-object", "error", "\"sandbox\" must be an object", sp?.line, sp?.column));
+            }
+            else {
+                for (const [key, val] of Object.entries(sandbox)) {
+                    const kp = findKeyPosition(content, key);
+                    if (!SANDBOX_FIELDS.has(key)) {
+                        push(diag(config, filePath, "settings-json/sandbox-unknown-field", "warning", `Unknown field "sandbox.${key}"`, kp?.line, kp?.column));
+                        continue;
+                    }
+                    const expected = SANDBOX_FIELD_TYPES[key];
+                    if (expected && !typeMatches(expected, val)) {
+                        push(diag(config, filePath, "settings-json/sandbox-field-type", "warning", `"sandbox.${key}" should be ${articleType(expected)}`, kp?.line, kp?.column));
+                        continue;
+                    }
+                    // Nested object validation
+                    if (key === "network" && isPlainObject(val)) {
+                        checkNested(val, "sandbox.network", SANDBOX_NETWORK_FIELDS, NETWORK_FIELD_TYPES);
+                        if (isPlainObject(val.tlsTerminate)) {
+                            checkNested(val.tlsTerminate, "sandbox.network.tlsTerminate", new Set(Object.keys(TLS_TERMINATE_FIELD_TYPES)), TLS_TERMINATE_FIELD_TYPES);
+                        }
+                    }
+                    else if (key === "filesystem" && isPlainObject(val)) {
+                        checkNested(val, "sandbox.filesystem", SANDBOX_FILESYSTEM_FIELDS, FILESYSTEM_FIELD_TYPES);
+                    }
+                    else if (key === "ripgrep" && isPlainObject(val)) {
+                        for (const rk of Object.keys(val)) {
+                            if (rk !== "command" && rk !== "args") {
+                                const rp = findKeyPosition(content, rk);
+                                push(diag(config, filePath, "settings-json/sandbox-unknown-field", "warning", `Unknown field "sandbox.ripgrep.${rk}"`, rp?.line, rp?.column));
+                            }
+                        }
+                        if (typeof val.command !== "string") {
+                            push(diag(config, filePath, "settings-json/sandbox-field-type", "warning", "\"sandbox.ripgrep.command\" is required and must be a string", kp?.line, kp?.column));
+                        }
+                        if ("args" in val && !isStringArray(val.args)) {
+                            push(diag(config, filePath, "settings-json/sandbox-field-type", "warning", "\"sandbox.ripgrep.args\" should be an array of strings", kp?.line, kp?.column));
+                        }
+                    }
+                    else if (key === "ignoreViolations" && isPlainObject(val)) {
+                        for (const [vk, vv] of Object.entries(val)) {
+                            if (!isStringArray(vv)) {
+                                const vp = findKeyPosition(content, vk);
+                                push(diag(config, filePath, "settings-json/sandbox-field-type", "warning", `"sandbox.ignoreViolations.${vk}" should be an array of strings`, vp?.line, vp?.column));
+                            }
+                        }
                     }
                 }
             }
@@ -126,7 +413,7 @@ export const settingsJsonLinter = {
         if ("env" in parsed) {
             const env = parsed.env;
             const envp = findKeyPosition(content, "env");
-            if (typeof env !== "object" || env === null || Array.isArray(env)) {
+            if (!isPlainObject(env)) {
                 push(diag(config, filePath, "settings-json/env-object", "error", "\"env\" must be an object of string key-value pairs", envp?.line, envp?.column));
             }
             else {
@@ -142,7 +429,7 @@ export const settingsJsonLinter = {
         if ("enabledPlugins" in parsed) {
             const plugins = parsed.enabledPlugins;
             const plp = findKeyPosition(content, "enabledPlugins");
-            if (typeof plugins !== "object" || plugins === null || Array.isArray(plugins)) {
+            if (!isPlainObject(plugins)) {
                 push(diag(config, filePath, "settings-json/plugins-object", "error", "\"enabledPlugins\" must be an object", plp?.line, plp?.column));
             }
             else {

package/dist/linters/skill-md.js

@@ -1,9 +1,11 @@
-import { SKILL_FRONTMATTER } from "../contracts.js";
+import { formatAjvError, loadSkillFrontmatterSchema, summarizeErrors, } from "../plugin-schema.js";
 import { isRuleEnabled, getRuleSeverity } from "../types.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
+import { artifactLabel, classifyUnknownFrontmatterKey, } from "../utils/frontmatter-keys.js";
 import { isKebabCase } from "../utils/kebab-case.js";
 const RULES = [
     { id: "skill-md/valid-frontmatter", defaultSeverity: "error" },
+    { id: "skill-md/schema-valid", defaultSeverity: "error" },
     { id: "skill-md/name-required", defaultSeverity: "error" },
     { id: "skill-md/name-kebab-case", defaultSeverity: "error" },
     { id: "skill-md/name-max-length", defaultSeverity: "error" },
@@ -11,10 +13,72 @@ 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/no-unknown-frontmatter", defaultSeverity: "warning" },
-    { id: "skill-md/body-word-count", 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" },
 ];
+/**
+ * Decide whether a SKILL.md `description` communicates *when* the skill
+ * applies. A description that gives Claude Code any concrete applicability
+ * cue is fine — only purely declarative descriptions (a flat statement of
+ * what the skill is, with no routing signal at all) should be flagged.
+ *
+ * Recognized signals, in rough order of how common they are in real skills:
+ *  - explicit trigger sections: "Trigger on …", "Trigger when/whenever …",
+ *    "Triggers: …", "TRIGGER when:", routing-marker comments
+ *  - "use when / use for / use whenever / use this skill when / use to"
+ *  - "should be used when …", "applies when …", "invoke when …"
+ *  - "when the user asks/wants/mentions/needs …" and bare "when <verb>ing"
+ *  - imperative-verb openers ("Diagnose …", "Deploy …", "Author …") — an
+ *    imperative description states the task the skill performs, which is
+ *    itself an applicability cue
+ *  - gerund openers ("Building …", "Searching …")
+ */
+function hasTriggerSignal(desc) {
+    const d = desc.trim();
+    if (!d)
+        return false;
+    // Routing-marker comments authors drop in to delimit trigger lists.
+    if (/BEGIN ROUTING TRIGGERS|ROUTING TRIGGERS/i.test(d))
+        return true;
+    // Explicit trigger / use-when phrasing anywhere in the description.
+    // "Trigger" only counts as a routing cue when used as a directive verb
+    // ("Trigger on …", "Trigger when/whenever/if …", "Triggers: …", "TRIGGER
+    // when:") — not when "trigger" merely appears as a noun (e.g. the phrase
+    // "no trigger phrases").
+    const triggerPhrases = /\btrigger(s)?\b\s*(on|when|whenever|if|upon|for)\b|\btriggers?\s*:|\buse (this skill |it )?(when|whenever|for|to|on|if)\b|\bshould be used (when|whenever|for|to|if)\b|\b(applies|invoke|reach for|call this|run this|use this) (when|whenever|if|to|for)\b|\bwhen (the user|you|asked|working|debugging|diagnosing|investigating|reviewing|writing|building|creating|editing|setting up|deploying|the task|a request|a question|you need|there|something|anything)\b|\bwhen [a-z]+ing\b|\bfor (debugging|diagnosing|tasks|requests|questions|when|any)\b/i;
+    if (triggerPhrases.test(d))
+        return true;
+    // First "sentence-ish" chunk — used to detect imperative / gerund openers.
+    const opener = d.split(/[.\n—:(]/, 1)[0].trim();
+    const firstWord = opener.split(/\s+/, 1)[0].replace(/[^A-Za-z-]/g, "");
+    // Gerund opener ("Building a …", "Searching the …").
+    if (/^[A-Z][a-z]+ing\b/.test(opener))
+        return true;
+    // Imperative-verb opener. A skill description that starts with a bare
+    // verb is describing the action the skill performs, which signals when
+    // to route to it. Accept a curated set of common imperative verbs so we
+    // don't accidentally pass a noun-opener declarative description.
+    const imperativeVerbs = new Set([
+        "add", "analyze", "audit", "author", "automate", "build", "check",
+        "clean", "configure", "convert", "create", "debug", "delete", "deploy",
+        "diagnose", "drive", "edit", "enforce", "ensure", "estimate",
+        "evaluate", "execute", "extract", "fetch", "find", "fix", "format",
+        "generate", "guide", "handle", "help", "identify", "implement",
+        "initialize", "inspect", "install", "investigate", "lint", "list",
+        "manage", "migrate", "mint", "monitor", "open", "optimize", "parse",
+        "perform", "pin", "plan", "prepare", "preview", "produce", "profile",
+        "publish", "pull", "push", "query", "reclaim", "refactor", "render",
+        "report", "resolve", "restore", "review", "rollout", "run", "scaffold",
+        "scan", "search", "set", "ship", "size", "summarize", "sweep", "sync",
+        "test", "trace", "track", "transform", "transition", "translate",
+        "troubleshoot", "tune", "update", "upgrade", "validate", "verify",
+        "watch", "write",
+    ]);
+    if (imperativeVerbs.has(firstWord.toLowerCase()))
+        return true;
+    return false;
+}
 function diag(config, filePath, ruleId, defaultSeverity, message, line, column) {
     if (!isRuleEnabled(config, ruleId))
         return null;
@@ -38,6 +102,25 @@ export const skillMdLinter = {
             push(diag(config, filePath, "skill-md/valid-frontmatter", "error", fm.error ?? "Invalid frontmatter"));
             return diagnostics;
         }
+        // schema-valid — structural validation against the JSON Schema
+        // auto-extracted from Claude Code's skill frontmatter Zod validator. The
+        // hand-written rules below add Claude-Code-specific advice the schema
+        // can't express (kebab-case names, trigger phrasing, …). The extracted
+        // schema is intentionally permissive about unknown frontmatter keys
+        // (Claude Code still loads the skill), so those are NOT reported here —
+        // skill-md/no-unknown-frontmatter handles them. Skipped silently if the
+        // schema bundle isn't shipped with this install.
+        if (isRuleEnabled(config, "skill-md/schema-valid")) {
+            const compiled = loadSkillFrontmatterSchema();
+            if (compiled) {
+                const ok = compiled.validate(fm.data);
+                if (!ok && compiled.validate.errors) {
+                    for (const err of summarizeErrors(compiled.validate.errors)) {
+                        push(diag(config, filePath, "skill-md/schema-valid", "error", formatAjvError(err)));
+                    }
+                }
+            }
+        }
         // name
         if (!("name" in fm.data) || typeof fm.data.name !== "string") {
             push(diag(config, filePath, "skill-md/name-required", "error", "\"name\" is required in frontmatter"));
@@ -63,25 +146,32 @@ export const skillMdLinter = {
             if (/<|>/.test(desc)) {
                 push(diag(config, filePath, "skill-md/description-no-angle-brackets", "error", "\"description\" must not contain angle brackets (< or >)"));
             }
-            if (!/when the user|should be used when/i.test(desc)) {
-                push(diag(config, filePath, "skill-md/description-trigger-phrases", "warning", "Description should contain trigger phrases (e.g., \"when the user asks to...\")"));
+            if (!hasTriggerSignal(desc)) {
+                push(diag(config, filePath, "skill-md/description-trigger-phrases", "warning", "Description has no applicability signal — say when the skill applies " +
+                    "(e.g., \"Use when…\", \"Trigger on…\", \"when the user asks to…\", or an imperative verb)"));
             }
         }
-        // unknown frontmatter keys
+        // 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.
         for (const key of Object.keys(fm.data)) {
-            if (!SKILL_FRONTMATTER.has(key)) {
-                push(diag(config, filePath, "skill-md/no-unknown-frontmatter", "warning", `Unknown frontmatter key "${key}" (known: ${[...SKILL_FRONTMATTER].join(", ")})`));
+            const cls = classifyUnknownFrontmatterKey(key, "skill");
+            if (cls?.kind === "owned-by-other" && cls.owner) {
+                push(diag(config, filePath, "skill-md/no-unknown-frontmatter", "info", `"${key}" is ${artifactLabel(cls.owner)} frontmatter — Claude Code ignores it on a skill`));
             }
         }
         // body checks
         const body = fm.body.trim();
         if (body) {
+            // Word-count is a soft style hint: a concise, well-scoped skill body is
+            // legitimate. Only flag genuinely thin bodies (< 150 words) or very
+            // large ones (> 5000) that likely belong split into references/.
             const words = body.split(/\s+/).length;
-            if (words < 500) {
-                push(diag(config, filePath, "skill-md/body-word-count", "warning", `Body has ${words} words (recommended: 500-5000)`, fm.bodyStartLine));
+            if (words < 150) {
+                push(diag(config, filePath, "skill-md/body-word-count", "info", `Body has ${words} words — consider adding more detail (recommended: 150-5000)`, fm.bodyStartLine));
             }
             else if (words > 5000) {
-                push(diag(config, filePath, "skill-md/body-word-count", "warning", `Body has ${words} words — consider moving detail to references/ (recommended: 500-5000)`, fm.bodyStartLine));
+                push(diag(config, filePath, "skill-md/body-word-count", "info", `Body has ${words} words — consider moving detail to references/ (recommended: 150-5000)`, fm.bodyStartLine));
             }
             if (!/^##\s/m.test(body)) {
                 push(diag(config, filePath, "skill-md/body-has-headers", "info", "Body should use H2 (##) sections for organization", fm.bodyStartLine));

package/dist/plugin-schema.js

@@ -62,6 +62,18 @@ export function loadLspSchema() {
 export function loadMonitorsSchema() {
     return loadCompiledSchema("monitors.schema.json");
 }
+export function loadSettingsSchema() {
+    return loadCompiledSchema("settings.schema.json");
+}
+export function loadSkillFrontmatterSchema() {
+    return loadCompiledSchema("skill-frontmatter.schema.json");
+}
+export function loadAgentFrontmatterSchema() {
+    return loadCompiledSchema("agent-frontmatter.schema.json");
+}
+export function loadCommandFrontmatterSchema() {
+    return loadCompiledSchema("command-frontmatter.schema.json");
+}
 export function loadPluginSchema() {
     if (cached)
         return cached;

package/dist/utils/frontmatter-keys.js

@@ -0,0 +1,38 @@
+import { SKILL_FRONTMATTER, AGENT_FRONTMATTER, COMMAND_FRONTMATTER, } from "../contracts.js";
+const KEY_SETS = {
+    skill: SKILL_FRONTMATTER,
+    agent: AGENT_FRONTMATTER,
+    command: COMMAND_FRONTMATTER,
+};
+const ARTIFACT_LABEL = {
+    skill: "skill",
+    agent: "agent",
+    command: "command",
+};
+/**
+ * Classify `key` relative to `self` (the artifact being linted).
+ *
+ * `extraKnown` lets a caller treat a few extra keys as known-for-self (some
+ * linters historically accept hyphenated aliases the contract set lists in a
+ * canonicalized form, e.g. `allowed-tools` / `argument-hint`).
+ */
+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))
+        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)) {
+            return { kind: "owned-by-other", owner: kind };
+        }
+    }
+    // Valid nowhere → genuinely unfamiliar; callers stay silent.
+    return { kind: "unknown-everywhere" };
+}
+/** Human-readable label for an artifact kind ("skill", "agent", "command"). */
+export function artifactLabel(kind) {
+    return ARTIFACT_LABEL[kind];
+}
+//# sourceMappingURL=frontmatter-keys.js.map