claudecode-linter 2.1.143 → 2.1.148

package/.claudecode-lint.defaults.yaml

@@ -24,6 +24,7 @@ rules:
 
   # ── SKILL.md ─────────────────────────────────────────────
   skill-md/valid-frontmatter: error
+  skill-md/schema-valid: error
   skill-md/name-required: error
   skill-md/name-kebab-case: error
   skill-md/name-max-length: error
@@ -37,10 +38,11 @@ rules:
 
   # ── Agent .md ────────────────────────────────────────────
   agent-md/valid-frontmatter: error
+  agent-md/schema-valid: error
   agent-md/name-required: error
   agent-md/name-format: error
   agent-md/description-required: error
-  agent-md/description-examples: warning
+  agent-md/description-routing-guidance: warning
   agent-md/model-required: error
   agent-md/model-valid: warning
   agent-md/color-required: error
@@ -51,6 +53,7 @@ rules:
 
   # ── Command .md ──────────────────────────────────────────
   command-md/valid-frontmatter: error
+  command-md/schema-valid: error
   command-md/description-required: error
   command-md/allowed-tools-valid: warning
   command-md/body-present: warning
@@ -72,9 +75,19 @@ rules:
   settings-json/scope-field: warning
   settings-json/no-unknown-fields: warning
   settings-json/permissions-object: error
+  settings-json/permissions-unknown-field: warning
+  settings-json/permissions-default-mode: warning
+  settings-json/permissions-disable-bypass: warning
+  settings-json/permissions-field-type: warning
   settings-json/allow-array: error
   settings-json/allow-known-tools: warning
   settings-json/deny-array: error
+  settings-json/ask-array: error
+  settings-json/permission-rule-syntax: error
+  settings-json/permission-rule-pattern: error
+  settings-json/sandbox-object: error
+  settings-json/sandbox-unknown-field: warning
+  settings-json/sandbox-field-type: warning
   settings-json/env-object: error
   settings-json/env-string-values: warning
   settings-json/plugins-object: error

package/README.md

@@ -7,7 +7,7 @@
 
 Standalone linter for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugins and configuration files.
 
-Validates `plugin.json`, `SKILL.md`, agent/command markdown, `hooks.json`, `mcp.json`, `settings.json`, `CLAUDE.md`, `.lsp.json`, and `monitors/monitors.json` files. plugin.json/lsp.json/monitors.json are checked against JSON Schemas auto-extracted from Claude Code's runtime Zod validators — failures the linter reports are the same failures Claude Code would raise at session start.
+Validates `plugin.json`, `SKILL.md`, agent/command markdown, `hooks.json`, `mcp.json`, `settings.json`, `CLAUDE.md`, `.lsp.json`, and `monitors/monitors.json` files. plugin.json, settings.json, the agent/skill/command frontmatter, .lsp.json and monitors.json are checked against JSON Schemas auto-extracted from Claude Code's runtime Zod validators — failures the linter reports are the same failures Claude Code would raise at session start.
 
 ![demo](assets/demo.gif)
 
@@ -74,6 +74,24 @@ claudecode-linter --fix path/to/plugin/
 claudecode-linter --fix-dry-run path/to/plugin/
 ```
 
+### Detect
+
+Print which Claude Code artifact types a path contains — one machine-readable
+type per line — and set the exit code (`0` if any found, `1` if none). Intended
+for a generic git hook that gates the linter on "is this repo a Claude Code
+plugin?":
+
+```bash
+# one artifact type per line
+claudecode-linter --detect path/to/repo/
+
+# JSON array
+claudecode-linter --detect --output json path/to/repo/
+
+# git hook: only lint repos that actually contain Claude Code artifacts
+claudecode-linter --detect . >/dev/null 2>&1 && claudecode-linter .
+```
+
 ### Example Output
 
 ```
@@ -112,11 +130,11 @@ No issues found.
 | Type | Files | Rules |
 |------|-------|-------|
 | plugin-json | `.claude-plugin/plugin.json` | 13 |
-| skill-md | `skills/*/SKILL.md` | 11 |
-| agent-md | `agents/*.md` | 13 |
-| command-md | `commands/*.md` | 5 |
+| skill-md | `skills/*/SKILL.md` | 12 |
+| agent-md | `agents/*.md` | 17 |
+| command-md | `commands/*.md` | 6 |
 | hooks-json | `hooks/hooks.json` | 9 |
-| settings-json | `.claude-plugin/settings.json` | 14 |
+| settings-json | `.claude-plugin/settings.json` | 25 |
 | mcp-json | `.claude-plugin/mcp.json` | 16 |
 | claude-md | `CLAUDE.md` | 10 |
 | lsp-json | `.lsp.json` | 3 |
@@ -124,7 +142,7 @@ No issues found.
 
 ## Schema-derived rules
 
-`plugin-json/schema-valid`, `lsp-json/schema-valid`, and `monitors-json/schema-valid` validate against JSON Schemas that are *auto-extracted from Claude Code's cli.js bundle* — same Zod schemas that the runtime calls `.safeParse(content)` on. This catches:
+Seven `*/schema-valid` rules — for `plugin-json`, `settings-json`, `skill-md`, `agent-md`, `command-md`, `lsp-json` and `monitors-json` — validate against JSON Schemas that are *auto-extracted from Claude Code's cli.js bundle* — the same Zod schemas the runtime calls `.safeParse(content)` on. This catches:
 
 - **Missing required fields** (e.g., LSP server without `extensionToLanguage`)
 - **Wrong field types** (e.g., `name: 42` instead of a string)

package/contracts/agent-frontmatter.schema.json

@@ -0,0 +1,147 @@
+{
+	"extractedFromClaudeCodeVersion": "2.1.146",
+	"extractedAt": "2026-05-21T21:04:24.810Z",
+	"schema": {
+		"$schema": "https://json-schema.org/draft/2020-12/schema",
+		"title": "Claude Code agent .md frontmatter",
+		"type": "object",
+		"properties": {
+			"name": {
+				"description": "Agent identifier. Required — this is how the Agent tool and `--agent` flag address it."
+			},
+			"description": {
+				"description": "When to use this agent. Required — shown in the Agent tool listing."
+			},
+			"model": {
+				"description": "Model override for this agent. Use `inherit` to match the spawning conversation."
+			},
+			"tools": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "Tools available to this agent. Replaces the default set."
+			},
+			"disallowedTools": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "Tools removed from the default set. Ignored if `tools` is set."
+			},
+			"color": {
+				"description": "@internal — display color in the agents UI"
+			},
+			"effort": {
+				"description": "Thinking effort: `low`, `medium`, `high`, `max`, or an integer."
+			},
+			"permissionMode": {
+				"description": "Permission mode the agent runs in."
+			},
+			"mcpServers": {
+				"description": "MCP servers to connect when this agent runs."
+			},
+			"hooks": {
+				"description": "Hooks registered while this agent runs."
+			},
+			"maxTurns": {
+				"anyOf": [
+					{
+						"type": "number"
+					},
+					{
+						"type": "string"
+					},
+					{
+						"type": "null"
+					}
+				],
+				"description": "Maximum conversation turns before the agent stops."
+			},
+			"skills": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "Skills preloaded for this agent."
+			},
+			"initialPrompt": {
+				"description": "Auto-submitted first message when this agent runs as the main session (via `--agent` or settings). Not read when spawned as a subagent."
+			},
+			"memory": {
+				"description": "Memory scope: `user`, `project`, or `local`."
+			},
+			"background": {
+				"description": "If true, the agent runs in the background by default."
+			},
+			"isolation": {
+				"description": "Filesystem isolation: `worktree` runs in a temporary git worktree."
+			}
+		},
+		"required": [
+			"name",
+			"description"
+		],
+		"description": "Claude Code agent .md YAML frontmatter. Validates the structure of known fields; the object is intentionally permissive — unknown frontmatter keys are not schema errors (Claude Code still loads the agent), they are reported by the advisory agent-md/no-unknown-frontmatter rule."
+	}
+}

package/contracts/command-frontmatter.schema.json

@@ -0,0 +1,93 @@
+{
+	"extractedFromClaudeCodeVersion": "2.1.146",
+	"extractedAt": "2026-05-21T21:04:24.812Z",
+	"schema": {
+		"$schema": "https://json-schema.org/draft/2020-12/schema",
+		"title": "Claude Code command .md frontmatter",
+		"type": "object",
+		"properties": {
+			"name": {
+				"description": "Display name. Defaults to the filename without extension."
+			},
+			"description": {
+				"description": "One-line summary shown in listings and the Skill tool."
+			},
+			"model": {
+				"description": "Model override (`haiku`, `sonnet`, `opus`, or a full ID). Use `inherit` to match the parent conversation."
+			},
+			"allowed-tools": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "Tools available to the model while this file is active. Comma-separated string or YAML list."
+			},
+			"argument-hint": {
+				"description": "Placeholder text shown after the slash command name."
+			},
+			"arguments": {
+				"anyOf": [
+					{
+						"anyOf": [
+							{
+								"type": "string"
+							},
+							{
+								"type": "number"
+							},
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "null"
+							}
+						]
+					},
+					{
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				],
+				"description": "@internal — typed variant of argument-hint; argument-hint is the documented form"
+			},
+			"disable-model-invocation": {
+				"description": "If true, the model cannot invoke this via the Skill tool; only users can type the slash command."
+			},
+			"user-invocable": {
+				"description": "If false, hides the slash command from users; only the model can invoke it via the Skill tool."
+			},
+			"effort": {
+				"description": "Thinking effort for the model: `low`, `medium`, `high`, `max`, or an integer."
+			},
+			"shell": {
+				"description": "Shell for `!`-command blocks: `bash` or `powershell`. Defaults to bash regardless of platform."
+			},
+			"version": {
+				"description": "@internal — bookkeeping, not surfaced to users"
+			}
+		},
+		"description": "Claude Code slash-command .md YAML frontmatter. Validates the structure of known fields; the object is intentionally permissive — unknown frontmatter keys are not schema errors (Claude Code still loads the command), they are reported by the advisory command-md/no-unknown-frontmatter rule."
+	}
+}