@yawlabs/ctxlint 0.12.3 → 0.13.0

package/.pre-commit-hooks.yaml

@@ -4,7 +4,7 @@
   # Version-pinned so a checkout at `rev: vX.Y.Z` runs exactly that release
   # of ctxlint — matches the pinning done by `ctxlint init`. release.sh keeps
   # this in sync with package.json on each bump.
-  entry: npx @yawlabs/ctxlint@0.12.3 --strict
+  entry: npx @yawlabs/ctxlint@0.13.0 --strict
   language: node
   always_run: true
   pass_filenames: false

package/AGENT_SESSION_LINT_SPEC.md

@@ -15,7 +15,7 @@ This specification defines a standard set of lint rules for validating agent ses
 
 The specification includes:
 - A reference of session data locations across 8 AI coding agents
-- 7 lint rules in the `session` category with defined severities
+- 8 lint rules in the `session` category with defined severities
 - A machine-readable rule catalog ([`agent-session-lint-rules.json`](./agent-session-lint-rules.json))
 - Sibling-repo detection for cross-project checks
 
@@ -128,7 +128,7 @@ Skip hidden directories (starting with `.`) and `node_modules`.
 
 ## 2. Lint Rules
 
-7 rules in 1 category (`session`). All rules in this category perform cross-project checks using sibling detection or per-project history analysis.
+8 rules in 1 category (`session`). All rules in this category perform cross-project checks using sibling detection or per-project history analysis.
 
 Severity levels:
 - **error** -- the session data reveals a verifiably missing configuration. Should fail CI.
@@ -437,6 +437,5 @@ This specification follows semver:
 
 - [AI Context File Linting Specification](./CONTEXT_LINT_SPEC.md) -- context file lint rules (the first pillar)
 - [MCP Server Configuration Linting Specification](./MCP_CONFIG_LINT_SPEC.md) -- MCP config lint rules (the second pillar)
-- [ctxlint](https://github.com/YawLabs/ctxlint) -- reference implementation of all three specifications
+- [ctxlint](https://github.com/YawLabs/ctxlint) -- reference implementation of all four specifications
 - [mcp-compliance](https://github.com/YawLabs/mcp-compliance) -- tests MCP server behavior against the protocol spec
-- [mcp.hosting](https://mcp.hosting) -- managed MCP server hosting

package/AGENT_SKILL_LINT_SPEC.md

@@ -0,0 +1,107 @@
+# AI Agent Skill Linting Specification
+
+**Version:** 1.0.0-draft
+**Date:** 2026-06-02
+**Maintained by:** [Yaw Labs](https://yaw.sh) / [ctxlint](https://github.com/YawLabs/ctxlint)
+**License:** CC BY 4.0
+
+---
+
+## What is this?
+
+AI coding agents are increasingly extended with **skills** and **subagents** -- reusable, named units of behavior the agent loads on demand. In Claude Code these live as:
+
+- **Skills:** `~/.claude/skills/<name>/SKILL.md` -- a markdown file with YAML frontmatter (`name`, `description`) plus a body of instructions.
+- **Agents (subagents):** `~/.claude/agents/*.md` -- a markdown file with frontmatter (`name`, `description`, optional `tools` restriction) plus a body.
+
+These definition files have the same failure modes as context files: their frontmatter goes missing, their body references paths that no longer exist, their trigger phrases collide so the wrong one fires, a skill directory is left without a `SKILL.md`, or a subagent restricts itself to a tool name that doesn't exist. When that happens the skill/agent silently misbehaves -- it never fires, fires for the wrong prompt, or runs with the wrong tool set.
+
+This specification defines a standard set of lint rules for validating agent-skill definitions. It is the **fourth pillar** alongside context-file linting, MCP-config linting, and session-data linting:
+
+| Pillar | What it checks | Specification |
+|---|---|---|
+| Context files | Instructions the agent reads | [CONTEXT_LINT_SPEC.md](./CONTEXT_LINT_SPEC.md) |
+| MCP configs | Tools the agent can use | [MCP_CONFIG_LINT_SPEC.md](./MCP_CONFIG_LINT_SPEC.md) |
+| Session data | History and memory the agent carries | [AGENT_SESSION_LINT_SPEC.md](./AGENT_SESSION_LINT_SPEC.md) |
+| Agent skills | Skills and subagents the agent loads | This document |
+
+**v1 scope is deliberately tight: Claude Code only** (`~/.claude/skills/<name>/SKILL.md` and `~/.claude/agents/*.md`). Other agents' skill/subagent formats may be added in later spec versions.
+
+**Reference implementation:** [ctxlint](https://github.com/YawLabs/ctxlint) -- run via `ctxlint --skills` (or `--skills-only`).
+
+---
+
+## 1. Agent Skill Landscape Reference
+
+### 1.1 Data sources (v1)
+
+| Kind | Location | Required frontmatter |
+|---|---|---|
+| Skill | `~/.claude/skills/<name>/SKILL.md` | `name`, `description` |
+| Agent (subagent) | `~/.claude/agents/<name>.md` | `name`, `description` (optional `tools` / `allowed-tools`) |
+
+The skill `<name>` is the directory name; the agent `<name>` is the filename without `.md`. A `~/.claude/skills/<name>/` directory with no `SKILL.md` is an **orphaned skill** -- the directory exists but Claude Code has nothing to load.
+
+### 1.2 Scan targets
+
+Skill/agent definitions live in the user-global `~/.claude/` tree, NOT inside the project. The checks therefore scan the home directory, like the session pillar -- they are opt-in (`--skills`) for the same reason: they read files outside the project directory.
+
+---
+
+## 2. Lint Rules
+
+5 rules in 1 category (`skill`). All rules audit Claude Code skill (`SKILL.md`) and agent (`.md`) definition files.
+
+Severity levels:
+- **error** -- the definition is structurally broken (e.g. unclosed or absent frontmatter). The skill/agent will not load as intended.
+- **warning** -- the definition has a likely problem worth investigating (missing field, broken reference, trigger collision, dead tool restriction).
+- **info** -- reserved for future advisory rules.
+
+### 2.1 skill — agent skill audit
+
+| Rule ID | Severity | Trigger | Message |
+|---|---|---|---|
+| `skill/missing-frontmatter` | warning (error when frontmatter absent/unclosed) | A SKILL.md / agent .md has no `---`-delimited frontmatter, has unclosed frontmatter, or is missing a required field (`name`, `description`) | `{file}: missing required frontmatter field "{field}"` |
+| `skill/broken-ref` | warning | A `./` or `../` path reference in the body (outside example code blocks) does not exist relative to the skill directory | `{file}: references "{path}" which does not exist relative to the skill directory` |
+| `skill/trigger-collision` | warning | A normalized trigger phrase (quoted phrase in the description, or a `trigger`/`triggers` field) is declared by more than one distinct skill/agent | `Trigger phrase "{trigger}" is declared by {count} skills/agents — only one will win` |
+| `skill/orphaned` | warning | A `~/.claude/skills/<name>/` directory contains no `SKILL.md` | `{dir}: skill directory has no SKILL.md — Claude Code has nothing to load` |
+| `skill/dead-tool-restriction` | warning | An agent's `tools` / `allowed-tools` frontmatter lists a non-MCP, non-wildcard tool name that is not a known Claude Code built-in tool | `{file}: tool restriction lists "{tool}" which is not a known Claude Code tool` |
+
+**Notes:**
+
+- **`skill/broken-ref`** reuses the path-reference detection shape from the context-file pillar. Only explicitly-relative references (`./`, `../`) are verified, resolved against the skill/agent file's own directory; bare `foo/bar` tokens in prose are too ambiguous to resolve without false positives, so they are skipped. References inside example code blocks (`ts`, `py`, `json`, ...) are excluded.
+- **`skill/trigger-collision`** extracts triggers from quoted phrases inside the `description` (e.g. `"ship 1.3.X"`) and from an optional `trigger`/`triggers` field. Phrases are lowercased and whitespace-collapsed before comparison.
+- **`skill/dead-tool-restriction`** validates only against the known built-in tool set. MCP-namespaced tools (`mcp__server__tool`) and wildcard entries are skipped because their validity depends on the loaded MCP servers, which the linter cannot see statically.
+
+All v1 rules are marked **experimental** in the catalog -- the heuristics are conservative and may broaden as more skill/agent shapes are observed. Experimental rules bump patch; promotion to stable bumps minor (see `CHANGELOG.md` versioning policy).
+
+---
+
+## 3. Rule Catalog (machine-readable)
+
+A machine-readable JSON catalog of all rules is available at [`agent-skill-lint-rules.json`](./agent-skill-lint-rules.json). It conforms to the shared catalog schema ([`schemas/ctxlint-catalog.schema.json`](./schemas/ctxlint-catalog.schema.json)), like the other three pillars.
+
+Rule IDs use the ctxlint `category/slug` format (see [CONTRIBUTING.md](./CONTRIBUTING.md) "Rule ID format" for why this differs from the sibling mcp-compliance project).
+
+---
+
+## 4. Implementing This Specification
+
+1. Discover skill files (`~/.claude/skills/<name>/SKILL.md`) and agent files (`~/.claude/agents/*.md`). Record each `~/.claude/skills/<name>/` directory that has no `SKILL.md` as an orphaned skill.
+2. Parse YAML frontmatter (`name`, `description`, and for agents `tools` / `allowed-tools`).
+3. Run the five rules in section 2.1.
+4. Report findings against the user-global path (`~/.claude/...`) -- these are not project files.
+
+### Versioning
+
+This spec follows semver:
+- **Patch** (1.0.x): Typo fixes, clarifications, no rule changes.
+- **Minor** (1.x.0): New rules added, new agents/skill formats documented.
+- **Major** (x.0.0): Rules removed or semantics changed in breaking ways.
+
+### Related specifications and tools
+
+- [AI Context File Linting Specification](./CONTEXT_LINT_SPEC.md) -- context file lint rules (the first pillar)
+- [MCP Server Configuration Linting Specification](./MCP_CONFIG_LINT_SPEC.md) -- MCP config lint rules (the second pillar)
+- [AI Agent Session Linting Specification](./AGENT_SESSION_LINT_SPEC.md) -- session data lint rules (the third pillar)
+- [ctxlint](https://github.com/YawLabs/ctxlint) -- reference implementation of all four specifications

package/CONTEXT_LINT_SPEC.md

@@ -15,7 +15,7 @@ This specification defines a standard set of lint rules for validating AI agent
 
 The specification includes:
 - A complete reference of context file formats across 17 AI coding clients (21+ file patterns)
-- 21 lint rules organized into 9 categories with defined severities
+- 28 lint rules organized into 11 categories with defined severities
 - A machine-readable rule and format catalog ([`context-lint-rules.json`](./context-lint-rules.json))
 - Auto-fix definitions for rules that support automated correction
 - Frontmatter schema requirements per client
@@ -47,6 +47,7 @@ The specification includes:
   - [3.7 frontmatter — client metadata validation](#37-frontmatter--client-metadata-validation)
   - [3.8 ci-coverage — CI workflow documentation](#38-ci-coverage--ci-workflow-documentation)
   - [3.9 ci-secrets — CI secrets documentation](#39-ci-secrets--ci-secrets-documentation)
+  - [3.11 hook-coverage — hook enforcement coverage](#311-hook-coverage--hook-enforcement-coverage)
 - [4. Rule Catalog (machine-readable)](#4-rule-catalog-machine-readable)
 - [5. Implementing This Specification](#5-implementing-this-specification)
 - [6. Contributing](#6-contributing)
@@ -300,7 +301,7 @@ Context files consume an agent's context window. Counting tokens helps teams und
 
 ## 3. Lint Rules
 
-21 rules organized into 9 categories.
+28 rules organized into 11 categories.
 
 Severity levels:
 - **error** — the context file has a verifiably incorrect reference or invalid metadata. Should fail CI.
@@ -592,6 +593,23 @@ Checks that secrets referenced in CI workflow files are mentioned in context fil
 4. For each remaining secret, search all context files for the secret name (case-insensitive, flexible underscore/space matching).
 5. Emit one info-level issue per undocumented secret.
 
+### 3.11 hook-coverage — hook enforcement coverage
+
+The inverse of `tier-tokens/hard-enforcement-missing`. Where `tier-tokens` flags an inviolable rule that has *no* hook to enforce it, `hook-coverage` flags a hook (or permissions entry) that points at a script which no longer exists — a dead gate that silently no-ops. Claude Code cannot run a script that isn't on disk, so a `PreToolUse` hook whose `command` references a deleted/renamed file stops blocking anything, while the user still believes the protection is in place.
+
+| Rule ID | Severity | Trigger | Message |
+|---|---|---|---|
+| `hook-coverage/dead-hook` | warning | A `hooks.<Event>[].hooks[].command` or `permissions.{allow,deny,ask}[]` entry in `.claude/settings.json` contains a path-shaped token that does not exist on disk | `{origin} references "{path}" which does not exist on disk — the gate silently no-ops` |
+
+**Detection algorithm:**
+
+1. Load settings from project `.claude/settings.json`, project `.claude/settings.local.json`, and user `~/.claude/settings.json` (parsed as JSONC; missing files are skipped).
+2. For each hook command and each `permissions` list entry, tokenize on whitespace (respecting quotes) and keep tokens that look like script paths (a path separator + a script extension such as `.sh`/`.js`/`.py`/`.ps1`, or an explicit `./` `~/` `/` `$VAR/` `C:\` prefix). Inline tool matchers like `Bash(npm login)` yield no path tokens.
+3. Resolve each path token: expand a leading `~` and the env vars Claude Code documents for settings paths — `$CLAUDE_PROJECT_DIR`, `$CLAUDE_CONFIG_DIR`, `$HOME`, `$USERPROFILE`. A token that still contains an unresolvable `$VAR` is skipped (it cannot be verified, and a false "dead hook" is worse than a missed one).
+4. Emit one warning per resolved path that does not exist on disk, with the source file's line number for project files (the user-global file is noted inline).
+
+**Stability:** experimental — the path-extraction heuristic is conservative by design (it prefers a missed dead hook over a false positive) and may broaden as more hook-command shapes are observed.
+
 ---
 
 ## 4. Rule Catalog (machine-readable)
@@ -665,6 +683,5 @@ This specification follows semver:
 - [AAIF AGENTS.md](https://github.com/anthropics/agents-spec) — Linux Foundation standard for multi-agent context files
 - [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/) — the protocol that MCP server configs serve
 - [MCP Server Configuration Linting Specification](./MCP_CONFIG_LINT_SPEC.md) — companion spec for linting MCP server configs
-- [ctxlint](https://github.com/YawLabs/ctxlint) — reference implementation of both specifications
+- [ctxlint](https://github.com/YawLabs/ctxlint) — reference implementation of all four specifications
 - [mcp-compliance](https://github.com/YawLabs/mcp-compliance) — tests MCP server behavior against the protocol spec
-- [mcp.hosting](https://mcp.hosting) — managed MCP server hosting

package/MCP_CONFIG_LINT_SPEC.md

@@ -16,7 +16,7 @@ This specification defines a standard set of lint rules for validating MCP serve
 
 The specification includes:
 - A complete reference of MCP config file locations, formats, and client-specific behaviors
-- 43 lint rules organized into 8 categories with defined severities
+- 27 lint rules organized into 8 categories with defined severities
 - A machine-readable rule catalog ([`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json))
 - Auto-fix definitions for rules that support automated correction
 
@@ -408,4 +408,3 @@ This specification follows semver:
 - [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/) — the underlying protocol this config format serves
 - [ctxlint](https://github.com/YawLabs/ctxlint) — reference implementation of this specification
 - [mcp-compliance](https://github.com/YawLabs/mcp-compliance) — tests MCP server *behavior* against the protocol spec (complementary to config linting)
-- [mcp.hosting](https://mcp.hosting) — managed MCP server hosting (eliminates many config issues by providing remote endpoints)

package/README.md

@@ -11,7 +11,7 @@
 
 Your `CLAUDE.md` is lying to your agent. Your `.mcp.json` has a hardcoded API key. ctxlint catches both.
 
-[![Add to Yaw MCP](https://yaw.sh/yaw-mcp-button.svg)](yaw://install?name=ctxlint&command=npx&args=-y%2C%40yawlabs%2Fctxlint%2Cserve&description=Lint%20AI%20agent%20context%20files%20and%20MCP%20configs%20against%20your%20codebase&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fctxlint)
+[![Add to Yaw MCP](https://yaw.sh/yaw-mcp-button.svg)](https://yaw.sh/mcp/install?name=ctxlint&command=npx&args=-y%2C%40yawlabs%2Fctxlint%2Cserve&description=Lint%20AI%20agent%20context%20files%20and%20MCP%20configs%20against%20your%20codebase&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fctxlint)
 
 One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.
 
@@ -82,6 +82,7 @@ Useful if you want `ctxlint` available in every project without per-project setu
 | **Frontmatter**       | Invalid or missing YAML frontmatter in Cursor .mdc, Copilot instructions, and Windsurf rules  |
 | **CI coverage**       | Release/deploy workflows in `.github/workflows/` not documented in any context file           |
 | **CI secrets**        | Secrets used in CI workflows (`${{ secrets.X }}`) not mentioned in context files              |
+| **Dead hooks**        | PreToolUse hooks / permissions entries in `.claude/settings.json` pointing at scripts that no longer exist (a dead gate silently no-ops). Scans project `.claude/settings.json[.local]` by default; pass `--hooks-global` to also scan the user-global `~/.claude/settings.json` |
 | **Missing secrets**   | GitHub secrets set on sibling repos but missing from current project                          |
 | **Diverged configs**  | Canonical config files (CI, tsconfig, etc.) drifting across sibling projects                  |
 | **Missing workflows** | GitHub Actions workflows present in 2+ siblings but absent here                               |
@@ -176,12 +177,14 @@ Summary: 3 errors, 2 warnings, 1 info
 
 The full specification for MCP config linting rules, the cross-client config landscape, and a machine-readable rule catalog are published as open specifications:
 
-- **[`MCP_CONFIG_LINT_SPEC.md`](./MCP_CONFIG_LINT_SPEC.md)** — 43 lint rules across 8 categories, the complete client/format reference, and implementation guidance. Tool-agnostic — any linter can implement it.
+- **[`MCP_CONFIG_LINT_SPEC.md`](./MCP_CONFIG_LINT_SPEC.md)** — the full lint-rule set (rule count in the [Specifications](#specifications) family table), the complete client/format reference, and implementation guidance. Tool-agnostic — any linter can implement it.
 - **[`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json)** — Machine-readable rule catalog for programmatic consumption by AI agents, CI systems, and other tools.
 
 ## mcph Config Linting
 
-ctxlint also lints `.mcph.json` — the config file read by the [`@yawlabs/mcph`](https://github.com/YawLabs/mcph) CLI, which orchestrates MCP servers via the mcp.hosting registry. Distinct from `.mcp.json` (different schema, different threat model). Applies across the user-global (`~/.mcph.json`), per-project (`.mcph.json`), and machine-local (`.mcph.local.json`) scope cascade.
+ctxlint also lints `.mcph.json` — the config file read by the [`@yawlabs/mcph`](https://github.com/YawLabs/mcph) CLI. Distinct from `.mcp.json` (different schema, different threat model). Applies across the user-global (`~/.mcph.json`), per-project (`.mcph.json`), and machine-local (`.mcph.local.json`) scope cascade.
+
+> **Note:** the mcph rule family (and the `ctxlint_mcph_audit` MCP tool) is **under review** — the upstream mcp.hosting platform is archived, so this family's future is being reassessed. The rules and tool still ship and work; only their long-term status is undecided.
 
 ```bash
 # Lint context files + .mcph.json
@@ -536,14 +539,15 @@ Returns structured JSON with all file results, issues, and summary — useful fo
 
 ## Specifications
 
-ctxlint is the reference implementation of three open specifications for linting AI agent interfaces. These specs are tool-agnostic — any linter, IDE extension, or CI system can implement them.
+ctxlint is the reference implementation of four open specifications for linting AI agent interfaces. These specs are tool-agnostic — any linter, IDE extension, or CI system can implement them.
 
 | Spec                                                           | What it covers                                                                                                                                                                                                                       |
 | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **[AI Context File Linting Spec](./CONTEXT_LINT_SPEC.md)**     | 19 rules for validating context files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) across 17 clients. Covers file formats, frontmatter schemas, path/command validation, staleness, token budgets, redundancy, and contradictions.     |
-| **[MCP Config Linting Spec](./MCP_CONFIG_LINT_SPEC.md)**       | 43 rules for validating MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) across 8 clients. Covers schema validation, hardcoded secrets, env var syntax, deprecated transports, and cross-file consistency.   |
+| **[AI Context File Linting Spec](./CONTEXT_LINT_SPEC.md)**     | 28 rules for validating context files (CLAUDE.md, .cursorrules, AGENTS.md, etc.) across 17 clients. Covers file formats, frontmatter schemas, path/command validation, staleness, token budgets, redundancy, and contradictions.     |
+| **[MCP Config Linting Spec](./MCP_CONFIG_LINT_SPEC.md)**       | 27 rules for validating MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, etc.) across 8 clients. Covers schema validation, hardcoded secrets, env var syntax, deprecated transports, and cross-file consistency.   |
 | **mcph Config Linting** (`mcph-config-lint-rules.json`)        | 10 rules for validating `.mcph.json` — the config file read by the `@yawlabs/mcph` CLI. Covers PAT format + leakage, env-var posture, plaintext API endpoints, schema drift, and allow/deny list semantics across the scope cascade. |
-| **[Agent Session Linting Spec](./AGENT_SESSION_LINT_SPEC.md)** | 7 rules for auditing agent session data (history, memory) across 8 agents. Covers cross-project secret consistency, config drift, stale memory, and loop detection.                                                                  |
+| **[Agent Session Linting Spec](./AGENT_SESSION_LINT_SPEC.md)** | 8 rules for auditing agent session data (history, memory) across 8 agents. Covers cross-project secret consistency, config drift, stale memory, and loop detection.                                                                  |
+| **[Agent Skill Linting Spec](./AGENT_SKILL_LINT_SPEC.md)**     | 5 rules for auditing Claude Code skill (`SKILL.md`) and agent (`.md`) definitions under `~/.claude`. Covers frontmatter presence, broken refs, trigger-phrase collisions, orphaned skills, and dead tool restrictions. (v1, experimental) |
 
 All specs include machine-readable rule catalogs for programmatic consumption:
 
@@ -551,11 +555,11 @@ All specs include machine-readable rule catalogs for programmatic consumption:
 - [`mcp-config-lint-rules.json`](./mcp-config-lint-rules.json) — MCP config rules and 8 client definitions
 - [`mcph-config-lint-rules.json`](./mcph-config-lint-rules.json) — mcph CLI config rules (`.mcph.json`)
 - [`agent-session-lint-rules.json`](./agent-session-lint-rules.json) — session lint rules and 8 agent data source definitions
+- [`agent-skill-lint-rules.json`](./agent-skill-lint-rules.json) — agent-skill lint rules (`~/.claude/skills`, `~/.claude/agents`)
 
 ## Also By Yaw Labs
 
 - [Yaw](https://yaw.sh) — The AI-native terminal
-- [mcp.hosting](https://mcp.hosting) — MCP server proxy platform
 - [Spend](https://spend.sh) — AI spend tracking, cost estimation, and provider comparison across 10+ providers
 - [Token Limit News](https://tokenlimit.news) — Weekly AI dev tooling newsletter
 

package/agent-session-lint-rules.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$schema": "https://raw.githubusercontent.com/YawLabs/ctxlint/main/schemas/ctxlint-catalog.schema.json",
   "title": "AI Agent Session Lint Rules",
   "description": "Machine-readable catalog of lint rules for AI agent session data cross-project consistency",
   "specVersion": "1.0.0-draft",

package/agent-skill-lint-rules.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://raw.githubusercontent.com/YawLabs/ctxlint/main/schemas/ctxlint-catalog.schema.json",
+  "title": "AI Agent Skill Lint Rules",
+  "description": "Machine-readable catalog of lint rules for Claude Code agent-skill definitions (~/.claude/skills/<name>/SKILL.md and ~/.claude/agents/*.md). The fourth ctxlint pillar. v1 is intentionally Claude-Code-only; other agents' skill/subagent formats may be added in later spec versions.",
+  "specVersion": "1.0.0-draft",
+  "specDate": "2026-06-02",
+  "repository": "https://github.com/YawLabs/ctxlint",
+  "categories": [
+    {
+      "id": "skill",
+      "name": "Agent Skill Audit",
+      "description": "Validates Claude Code skill (SKILL.md) and agent (.md) definition files for frontmatter presence, broken references, trigger collisions, orphaned skills, and dead tool restrictions.",
+      "scope": "user-global"
+    }
+  ],
+  "rules": [
+    {
+      "id": "skill/missing-frontmatter",
+      "category": "skill",
+      "severity": "warning",
+      "description": "A SKILL.md or agent .md file is missing required YAML frontmatter, or a required field within it. Skills and agents key off `name` + `description`; the description drives selection, so a missing one means the skill/agent is never invoked.",
+      "trigger": "The file has no `---`-delimited frontmatter, has unclosed frontmatter, or is missing a required field (name, description). A missing file body altogether is reported as error; a missing single field as warning.",
+      "message": "{file}: missing required frontmatter field \"{field}\"",
+      "fixable": false,
+      "stability": "experimental"
+    },
+    {
+      "id": "skill/broken-ref",
+      "category": "skill",
+      "severity": "warning",
+      "description": "A relative path reference (./ or ../) in a SKILL.md / agent body does not resolve to a file or directory relative to the skill/agent file. Reuses the path-reference detection shape from the context-file pillar; only explicitly-relative refs are verified to avoid false positives on prose.",
+      "trigger": "A ./ or ../ path token in the body (outside example code blocks) does not exist on disk relative to the skill directory.",
+      "message": "{file}: references \"{path}\" which does not exist relative to the skill directory",
+      "fixable": false,
+      "stability": "experimental"
+    },
+    {
+      "id": "skill/trigger-collision",
+      "category": "skill",
+      "severity": "warning",
+      "description": "Two or more skills/agents declare the same trigger phrase (a quoted phrase in the description, or a trigger/triggers field). When triggers collide, only one wins -- invocation becomes non-deterministic.",
+      "trigger": "A normalized trigger phrase (lowercased, whitespace-collapsed) is declared by more than one distinct skill/agent file.",
+      "message": "Trigger phrase \"{trigger}\" is declared by {count} skills/agents -- only one will win",
+      "fixable": false,
+      "stability": "experimental"
+    },
+    {
+      "id": "skill/orphaned",
+      "category": "skill",
+      "severity": "warning",
+      "description": "A ~/.claude/skills/<name>/ directory exists but contains no SKILL.md. Claude Code has nothing to load for that skill -- the directory is dead weight.",
+      "trigger": "A subdirectory of ~/.claude/skills/ does not contain a SKILL.md file.",
+      "message": "{dir}: skill directory has no SKILL.md -- Claude Code has nothing to load",
+      "fixable": false,
+      "stability": "experimental"
+    },
+    {
+      "id": "skill/dead-tool-restriction",
+      "category": "skill",
+      "severity": "warning",
+      "description": "An agent definition's tool restriction (tools / allowed-tools frontmatter) lists a tool name that is not a known Claude Code built-in tool. A dead restriction silently fails to grant/deny the intended tool. MCP-namespaced tools (mcp__server__tool) and wildcards are not validated (their existence depends on loaded MCP servers).",
+      "trigger": "A non-MCP, non-wildcard entry in an agent's tools/allowed-tools list does not match a known built-in Claude Code tool name (Bash, Read, Edit, Glob, Grep, Write, Task, WebFetch, WebSearch, etc.).",
+      "message": "{file}: tool restriction lists \"{tool}\" which is not a known Claude Code tool",
+      "fixable": false,
+      "stability": "experimental"
+    }
+  ],
+  "dataSources": [
+    {
+      "agent": "claude-code",
+      "skills": "~/.claude/skills/<name>/SKILL.md",
+      "agents": "~/.claude/agents/*.md"
+    }
+  ]
+}

package/context-lint-rules.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$schema": "https://raw.githubusercontent.com/YawLabs/ctxlint/main/schemas/ctxlint-catalog.schema.json",
   "specVersion": "1.0.0-draft",
   "specDate": "2026-04-07",
   "repository": "https://github.com/YawLabs/ctxlint",
@@ -64,6 +64,12 @@
       "name": "CI Secrets Documentation",
       "description": "Checks that CI secrets used in workflows are documented in context files.",
       "scope": "cross-file"
+    },
+    {
+      "id": "hook-coverage",
+      "name": "Hook Enforcement Coverage",
+      "description": "Validates that PreToolUse hooks and permissions entries in .claude/settings.json reference scripts that exist on disk. The inverse of tier-tokens/hard-enforcement-missing.",
+      "scope": "cross-file"
     }
   ],
   "rules": [
@@ -379,6 +385,16 @@
       "message": "CI secret \"{name}\" is used in {workflow} but not mentioned in any context file",
       "fixable": false,
       "stability": "stable"
+    },
+    {
+      "id": "hook-coverage/dead-hook",
+      "category": "hook-coverage",
+      "severity": "warning",
+      "description": "A PreToolUse (or other) hook command, or a permissions entry, in .claude/settings.json references a script/path that does not exist on disk. The gate silently no-ops -- Claude Code cannot run a missing script, so the protection the user believes is in place does nothing.",
+      "trigger": "A hooks.<Event>[].hooks[].command or permissions.{allow,deny,ask}[] entry contains a path-shaped token (resolved through ~, $CLAUDE_PROJECT_DIR, $CLAUDE_CONFIG_DIR, $HOME) that does not exist on disk. Entries with unresolvable env vars are skipped (cannot be verified). Scans project .claude/settings.json + settings.local.json and user ~/.claude/settings.json.",
+      "message": "{origin} references \"{path}\" which does not exist on disk -- the gate silently no-ops",
+      "fixable": false,
+      "stability": "experimental"
     }
   ],
   "formats": [