claude-skill-lint 0.1.0__tar.gz

claude_skill_lint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy Renoult
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_skill_lint-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: claude-skill-lint
+Version: 0.1.0
+Summary: Lint your Claude Code skills: descriptions that never trigger, silent frontmatter typos, boot-token cost.
+Author-email: Jeremy Renoult <jeremy.renoult.pro@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/trinity-organism/skill-lint
+Project-URL: Repository, https://github.com/trinity-organism/skill-lint
+Project-URL: Changelog, https://github.com/trinity-organism/skill-lint/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/trinity-organism/skill-lint/issues
+Keywords: claude-code,claude,skills,lint,frontmatter,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# skill-lint
+
+[![CI](https://github.com/trinity-organism/skill-lint/actions/workflows/test.yml/badge.svg)](https://github.com/trinity-organism/skill-lint/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/skill-lint)](https://pypi.org/project/skill-lint/)
+[![Python versions](https://img.shields.io/pypi/pyversions/skill-lint)](https://pypi.org/project/skill-lint/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A Claude Code skill lives or dies by one field: its `description`. Claude
+reads the name + description of **every** skill at session start and decides
+from that text alone whether your skill ever fires. A typo'd frontmatter key
+is ignored **silently**. Malformed YAML loads the skill with **empty
+metadata** — it will never auto-trigger and nothing tells you. A description
+that says *what* but never *when* under-triggers. And every character of
+every description is context you pay for at **every session**.
+
+`skill-lint` is the linter for that one field and everything around it:
+**one command, zero dependencies, tells you which skills are dead, which are
+silently broken, and what your skills cost at boot.**
+
+- **Dead skills** — malformed frontmatter, no description and nothing to
+  fall back on: skills that can never trigger.
+- **Silent typos** — `descripton:` instead of `description:` is ignored
+  without a word; skill-lint catches it and suggests the fix.
+- **Under-triggering descriptions** — too short, no usage cue, or truncated
+  past the 1,536-character listing cap so Claude never sees the tail.
+- **Boot cost** — chars and estimated tokens of names + descriptions loaded
+  every session, per skill and total; manual-only skills
+  (`disable-model-invocation: true`) correctly counted at zero.
+
+## Install
+
+```
+pipx install skill-lint
+```
+
+or
+
+```
+pip install skill-lint
+```
+
+or straight from source:
+
+```
+pipx install git+https://github.com/trinity-organism/skill-lint
+```
+
+Python >= 3.9. Zero dependencies — standard library only.
+
+## Usage
+
+```
+skill-lint                # lint $CLAUDE_CONFIG_DIR/skills, falling back to ~/.claude/skills
+skill-lint --dir DIR      # lint any skills directory (a project's .claude/skills, a plugin's skills/)
+skill-lint --json         # machine-readable output
+```
+
+Exit codes: `0` clean (or no skills found), `1` at least one finding,
+`2` unreadable directory — so it drops straight into CI or a pre-commit hook.
+
+## Example
+
+Real output on a demo skills directory:
+
+```text
+$ skill-lint --dir skills
+skill-lint — SKILL.md quality + boot cost
+skills dir: skills
+
+ok    deploy-staging  170 chars (~42 tok) at boot
+WARN  meeting-notes   65 chars (~16 tok) at boot
+      - WARN [no-when-cue]: description says what the skill does but never when to use it (no 'use/when/for/trigger...' cue): skills without usage context under-trigger
+WARN  pdf-tools       47 chars (~11 tok) at boot
+      - WARN [unknown-key]: frontmatter key 'descripton' is not a documented field and is ignored silently (did you mean 'description'?)
+      - WARN [no-description]: no description in frontmatter: triggering relies on the first body paragraph, which was not written for matching
+ERROR scratch         20 chars (~5 tok) at boot
+      - ERROR [broken-frontmatter]: unparseable line 4 in frontmatter: malformed YAML means empty metadata, so the skill never auto-triggers
+
+verdict — skills: 4 · errors: 1 · warnings: 3 · boot cost: 302 chars (~75 tokens) of names+descriptions every session
+$ echo $?
+1
+```
+
+And when there is nothing to lint:
+
+```text
+$ skill-lint --dir /some/empty/dir
+skill-lint: no skills found in /some/empty/dir
+Nothing to lint. If your skills live elsewhere, point at them with --dir DIR or $CLAUDE_CONFIG_DIR.
+```
+
+## Rules
+
+Every rule traces to documented Claude Code behavior, not taste.
+
+| Rule                 | Severity | Why it matters                                                                          |
+| -------------------- | -------- | --------------------------------------------------------------------------------------- |
+| `broken-frontmatter` | error    | Malformed YAML loads the skill with empty metadata: it never auto-triggers.              |
+| `undiscoverable`     | error    | No description and an empty body: nothing for Claude to match, ever.                     |
+| `no-description`     | warning  | Matching falls back to the first body paragraph, which wasn't written for matching.      |
+| `no-frontmatter`     | warning  | Same fallback; the skill also loses every other frontmatter feature.                     |
+| `desc-too-short`     | warning  | A handful of characters gives Claude nothing to match against.                           |
+| `no-when-cue`        | warning  | Says *what* but never *when*: the documented under-triggering failure mode.              |
+| `desc-truncated`     | warning  | `description` + `when_to_use` past 1,536 chars is cut in the listing — the tail is invisible. |
+| `unknown-key`        | warning  | Unknown frontmatter fields are ignored silently; usually a typo (did-you-mean included). |
+| `duplicate-key`      | warning  | Only one value survives a duplicated key.                                                |
+| `empty-body`         | warning  | The skill triggers and delivers nothing.                                                 |
+| `no-skill-md`        | warning  | A directory in the skills root with no `SKILL.md` is dead weight, never loaded.          |
+
+Folded and literal YAML blocks (`description: >` / `|`) are parsed correctly —
+the classic case where naive parsers read an empty description and report
+garbage.
+
+## Why lint descriptions at all?
+
+Claude Code loads skill names and descriptions into a context budget
+(about 1% of the model's context window). When it overflows, descriptions
+get dropped. Skills that never trigger still bill you that budget at every
+session — a config that only ever grows, with nothing pruning it. Lint it,
+fix the dead weight, keep the budget for skills that fire.
+
+Auditing the rest of your config (hooks, duplicate levers)? That's this
+tool's sibling: [`bridle-audit`](https://github.com/trinity-organism/bridle-audit).
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+The test suite fabricates synthetic skills in temp directories — it never
+reads your real `~/.claude`.
+
+## License
+
+MIT

claude_skill_lint-0.1.0/README.md

@@ -0,0 +1,137 @@
+# skill-lint
+
+[![CI](https://github.com/trinity-organism/skill-lint/actions/workflows/test.yml/badge.svg)](https://github.com/trinity-organism/skill-lint/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/skill-lint)](https://pypi.org/project/skill-lint/)
+[![Python versions](https://img.shields.io/pypi/pyversions/skill-lint)](https://pypi.org/project/skill-lint/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A Claude Code skill lives or dies by one field: its `description`. Claude
+reads the name + description of **every** skill at session start and decides
+from that text alone whether your skill ever fires. A typo'd frontmatter key
+is ignored **silently**. Malformed YAML loads the skill with **empty
+metadata** — it will never auto-trigger and nothing tells you. A description
+that says *what* but never *when* under-triggers. And every character of
+every description is context you pay for at **every session**.
+
+`skill-lint` is the linter for that one field and everything around it:
+**one command, zero dependencies, tells you which skills are dead, which are
+silently broken, and what your skills cost at boot.**
+
+- **Dead skills** — malformed frontmatter, no description and nothing to
+  fall back on: skills that can never trigger.
+- **Silent typos** — `descripton:` instead of `description:` is ignored
+  without a word; skill-lint catches it and suggests the fix.
+- **Under-triggering descriptions** — too short, no usage cue, or truncated
+  past the 1,536-character listing cap so Claude never sees the tail.
+- **Boot cost** — chars and estimated tokens of names + descriptions loaded
+  every session, per skill and total; manual-only skills
+  (`disable-model-invocation: true`) correctly counted at zero.
+
+## Install
+
+```
+pipx install skill-lint
+```
+
+or
+
+```
+pip install skill-lint
+```
+
+or straight from source:
+
+```
+pipx install git+https://github.com/trinity-organism/skill-lint
+```
+
+Python >= 3.9. Zero dependencies — standard library only.
+
+## Usage
+
+```
+skill-lint                # lint $CLAUDE_CONFIG_DIR/skills, falling back to ~/.claude/skills
+skill-lint --dir DIR      # lint any skills directory (a project's .claude/skills, a plugin's skills/)
+skill-lint --json         # machine-readable output
+```
+
+Exit codes: `0` clean (or no skills found), `1` at least one finding,
+`2` unreadable directory — so it drops straight into CI or a pre-commit hook.
+
+## Example
+
+Real output on a demo skills directory:
+
+```text
+$ skill-lint --dir skills
+skill-lint — SKILL.md quality + boot cost
+skills dir: skills
+
+ok    deploy-staging  170 chars (~42 tok) at boot
+WARN  meeting-notes   65 chars (~16 tok) at boot
+      - WARN [no-when-cue]: description says what the skill does but never when to use it (no 'use/when/for/trigger...' cue): skills without usage context under-trigger
+WARN  pdf-tools       47 chars (~11 tok) at boot
+      - WARN [unknown-key]: frontmatter key 'descripton' is not a documented field and is ignored silently (did you mean 'description'?)
+      - WARN [no-description]: no description in frontmatter: triggering relies on the first body paragraph, which was not written for matching
+ERROR scratch         20 chars (~5 tok) at boot
+      - ERROR [broken-frontmatter]: unparseable line 4 in frontmatter: malformed YAML means empty metadata, so the skill never auto-triggers
+
+verdict — skills: 4 · errors: 1 · warnings: 3 · boot cost: 302 chars (~75 tokens) of names+descriptions every session
+$ echo $?
+1
+```
+
+And when there is nothing to lint:
+
+```text
+$ skill-lint --dir /some/empty/dir
+skill-lint: no skills found in /some/empty/dir
+Nothing to lint. If your skills live elsewhere, point at them with --dir DIR or $CLAUDE_CONFIG_DIR.
+```
+
+## Rules
+
+Every rule traces to documented Claude Code behavior, not taste.
+
+| Rule                 | Severity | Why it matters                                                                          |
+| -------------------- | -------- | --------------------------------------------------------------------------------------- |
+| `broken-frontmatter` | error    | Malformed YAML loads the skill with empty metadata: it never auto-triggers.              |
+| `undiscoverable`     | error    | No description and an empty body: nothing for Claude to match, ever.                     |
+| `no-description`     | warning  | Matching falls back to the first body paragraph, which wasn't written for matching.      |
+| `no-frontmatter`     | warning  | Same fallback; the skill also loses every other frontmatter feature.                     |
+| `desc-too-short`     | warning  | A handful of characters gives Claude nothing to match against.                           |
+| `no-when-cue`        | warning  | Says *what* but never *when*: the documented under-triggering failure mode.              |
+| `desc-truncated`     | warning  | `description` + `when_to_use` past 1,536 chars is cut in the listing — the tail is invisible. |
+| `unknown-key`        | warning  | Unknown frontmatter fields are ignored silently; usually a typo (did-you-mean included). |
+| `duplicate-key`      | warning  | Only one value survives a duplicated key.                                                |
+| `empty-body`         | warning  | The skill triggers and delivers nothing.                                                 |
+| `no-skill-md`        | warning  | A directory in the skills root with no `SKILL.md` is dead weight, never loaded.          |
+
+Folded and literal YAML blocks (`description: >` / `|`) are parsed correctly —
+the classic case where naive parsers read an empty description and report
+garbage.
+
+## Why lint descriptions at all?
+
+Claude Code loads skill names and descriptions into a context budget
+(about 1% of the model's context window). When it overflows, descriptions
+get dropped. Skills that never trigger still bill you that budget at every
+session — a config that only ever grows, with nothing pruning it. Lint it,
+fix the dead weight, keep the budget for skills that fire.
+
+Auditing the rest of your config (hooks, duplicate levers)? That's this
+tool's sibling: [`bridle-audit`](https://github.com/trinity-organism/bridle-audit).
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+The test suite fabricates synthetic skills in temp directories — it never
+reads your real `~/.claude`.
+
+## License
+
+MIT

claude_skill_lint-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "claude-skill-lint"
+description = "Lint your Claude Code skills: descriptions that never trigger, silent frontmatter typos, boot-token cost."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Jeremy Renoult", email = "jeremy.renoult.pro@gmail.com" }]
+keywords = ["claude-code", "claude", "skills", "lint", "frontmatter", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Utilities",
+]
+dependencies = []
+dynamic = ["version"]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/trinity-organism/skill-lint"
+Repository = "https://github.com/trinity-organism/skill-lint"
+Changelog = "https://github.com/trinity-organism/skill-lint/blob/main/CHANGELOG.md"
+Issues = "https://github.com/trinity-organism/skill-lint/issues"
+
+[project.scripts]
+skill-lint = "skill_lint.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "skill_lint.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

claude_skill_lint-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

claude_skill_lint-0.1.0/src/claude_skill_lint.egg-info/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: claude-skill-lint
+Version: 0.1.0
+Summary: Lint your Claude Code skills: descriptions that never trigger, silent frontmatter typos, boot-token cost.
+Author-email: Jeremy Renoult <jeremy.renoult.pro@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/trinity-organism/skill-lint
+Project-URL: Repository, https://github.com/trinity-organism/skill-lint
+Project-URL: Changelog, https://github.com/trinity-organism/skill-lint/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/trinity-organism/skill-lint/issues
+Keywords: claude-code,claude,skills,lint,frontmatter,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# skill-lint
+
+[![CI](https://github.com/trinity-organism/skill-lint/actions/workflows/test.yml/badge.svg)](https://github.com/trinity-organism/skill-lint/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/skill-lint)](https://pypi.org/project/skill-lint/)
+[![Python versions](https://img.shields.io/pypi/pyversions/skill-lint)](https://pypi.org/project/skill-lint/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A Claude Code skill lives or dies by one field: its `description`. Claude
+reads the name + description of **every** skill at session start and decides
+from that text alone whether your skill ever fires. A typo'd frontmatter key
+is ignored **silently**. Malformed YAML loads the skill with **empty
+metadata** — it will never auto-trigger and nothing tells you. A description
+that says *what* but never *when* under-triggers. And every character of
+every description is context you pay for at **every session**.
+
+`skill-lint` is the linter for that one field and everything around it:
+**one command, zero dependencies, tells you which skills are dead, which are
+silently broken, and what your skills cost at boot.**
+
+- **Dead skills** — malformed frontmatter, no description and nothing to
+  fall back on: skills that can never trigger.
+- **Silent typos** — `descripton:` instead of `description:` is ignored
+  without a word; skill-lint catches it and suggests the fix.
+- **Under-triggering descriptions** — too short, no usage cue, or truncated
+  past the 1,536-character listing cap so Claude never sees the tail.
+- **Boot cost** — chars and estimated tokens of names + descriptions loaded
+  every session, per skill and total; manual-only skills
+  (`disable-model-invocation: true`) correctly counted at zero.
+
+## Install
+
+```
+pipx install skill-lint
+```
+
+or
+
+```
+pip install skill-lint
+```
+
+or straight from source:
+
+```
+pipx install git+https://github.com/trinity-organism/skill-lint
+```
+
+Python >= 3.9. Zero dependencies — standard library only.
+
+## Usage
+
+```
+skill-lint                # lint $CLAUDE_CONFIG_DIR/skills, falling back to ~/.claude/skills
+skill-lint --dir DIR      # lint any skills directory (a project's .claude/skills, a plugin's skills/)
+skill-lint --json         # machine-readable output
+```
+
+Exit codes: `0` clean (or no skills found), `1` at least one finding,
+`2` unreadable directory — so it drops straight into CI or a pre-commit hook.
+
+## Example
+
+Real output on a demo skills directory:
+
+```text
+$ skill-lint --dir skills
+skill-lint — SKILL.md quality + boot cost
+skills dir: skills
+
+ok    deploy-staging  170 chars (~42 tok) at boot
+WARN  meeting-notes   65 chars (~16 tok) at boot
+      - WARN [no-when-cue]: description says what the skill does but never when to use it (no 'use/when/for/trigger...' cue): skills without usage context under-trigger
+WARN  pdf-tools       47 chars (~11 tok) at boot
+      - WARN [unknown-key]: frontmatter key 'descripton' is not a documented field and is ignored silently (did you mean 'description'?)
+      - WARN [no-description]: no description in frontmatter: triggering relies on the first body paragraph, which was not written for matching
+ERROR scratch         20 chars (~5 tok) at boot
+      - ERROR [broken-frontmatter]: unparseable line 4 in frontmatter: malformed YAML means empty metadata, so the skill never auto-triggers
+
+verdict — skills: 4 · errors: 1 · warnings: 3 · boot cost: 302 chars (~75 tokens) of names+descriptions every session
+$ echo $?
+1
+```
+
+And when there is nothing to lint:
+
+```text
+$ skill-lint --dir /some/empty/dir
+skill-lint: no skills found in /some/empty/dir
+Nothing to lint. If your skills live elsewhere, point at them with --dir DIR or $CLAUDE_CONFIG_DIR.
+```
+
+## Rules
+
+Every rule traces to documented Claude Code behavior, not taste.
+
+| Rule                 | Severity | Why it matters                                                                          |
+| -------------------- | -------- | --------------------------------------------------------------------------------------- |
+| `broken-frontmatter` | error    | Malformed YAML loads the skill with empty metadata: it never auto-triggers.              |
+| `undiscoverable`     | error    | No description and an empty body: nothing for Claude to match, ever.                     |
+| `no-description`     | warning  | Matching falls back to the first body paragraph, which wasn't written for matching.      |
+| `no-frontmatter`     | warning  | Same fallback; the skill also loses every other frontmatter feature.                     |
+| `desc-too-short`     | warning  | A handful of characters gives Claude nothing to match against.                           |
+| `no-when-cue`        | warning  | Says *what* but never *when*: the documented under-triggering failure mode.              |
+| `desc-truncated`     | warning  | `description` + `when_to_use` past 1,536 chars is cut in the listing — the tail is invisible. |
+| `unknown-key`        | warning  | Unknown frontmatter fields are ignored silently; usually a typo (did-you-mean included). |
+| `duplicate-key`      | warning  | Only one value survives a duplicated key.                                                |
+| `empty-body`         | warning  | The skill triggers and delivers nothing.                                                 |
+| `no-skill-md`        | warning  | A directory in the skills root with no `SKILL.md` is dead weight, never loaded.          |
+
+Folded and literal YAML blocks (`description: >` / `|`) are parsed correctly —
+the classic case where naive parsers read an empty description and report
+garbage.
+
+## Why lint descriptions at all?
+
+Claude Code loads skill names and descriptions into a context budget
+(about 1% of the model's context window). When it overflows, descriptions
+get dropped. Skills that never trigger still bill you that budget at every
+session — a config that only ever grows, with nothing pruning it. Lint it,
+fix the dead weight, keep the budget for skills that fire.
+
+Auditing the rest of your config (hooks, duplicate levers)? That's this
+tool's sibling: [`bridle-audit`](https://github.com/trinity-organism/bridle-audit).
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+The test suite fabricates synthetic skills in temp directories — it never
+reads your real `~/.claude`.
+
+## License
+
+MIT

claude_skill_lint-0.1.0/src/claude_skill_lint.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/claude_skill_lint.egg-info/PKG-INFO
+src/claude_skill_lint.egg-info/SOURCES.txt
+src/claude_skill_lint.egg-info/dependency_links.txt
+src/claude_skill_lint.egg-info/entry_points.txt
+src/claude_skill_lint.egg-info/requires.txt
+src/claude_skill_lint.egg-info/top_level.txt
+src/skill_lint/__init__.py
+src/skill_lint/__main__.py
+src/skill_lint/cli.py
+tests/test_cli.py

claude_skill_lint-0.1.0/src/claude_skill_lint.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

claude_skill_lint-0.1.0/src/claude_skill_lint.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skill-lint = skill_lint.cli:main

claude_skill_lint-0.1.0/src/claude_skill_lint.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest

claude_skill_lint-0.1.0/src/claude_skill_lint.egg-info/top_level.txt

@@ -0,0 +1 @@
+skill_lint

claude_skill_lint-0.1.0/src/skill_lint/__init__.py

@@ -0,0 +1,3 @@
+"""Lint Claude Code skills: dead descriptions, silent typos, boot-token cost."""
+
+__version__ = "0.1.0"

claude_skill_lint-0.1.0/src/skill_lint/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for `python -m skill_lint`."""
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

claude_skill_lint-0.1.0/src/skill_lint/cli.py

@@ -0,0 +1,295 @@
+"""skill-lint — lint Claude Code skills: dead descriptions, silent typos, boot cost.
+
+Skill descriptions are the triggering mechanism: Claude reads name + description
+of every skill at session start and decides from that text alone whether a skill
+ever fires. Each check below traces to documented Claude Code behavior:
+
+- broken frontmatter  -> skill loads with empty metadata, never auto-triggers
+- missing description -> matching falls back to the first body paragraph
+- description + when_to_use is truncated at 1,536 chars in the skill listing
+- unknown frontmatter keys are ignored silently (a typo kills the field)
+- `disable-model-invocation: true` removes the skill from context (0 boot cost)
+
+Exit codes: 0 clean (or no skills found), 1 at least one finding, 2 unreadable dir.
+"""
+import argparse
+import difflib
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+from . import __version__
+
+LISTING_CAP = 1536      # combined description + when_to_use cap in the listing
+SHORT_DESC = 20         # below this, there is nothing to match on
+CHARS_PER_TOKEN = 4     # rough boot-cost estimate
+
+# Documented Claude Code fields + agentskills.io open-standard extras.
+KNOWN_KEYS = {
+    "name", "description", "when_to_use", "argument-hint", "arguments",
+    "disable-model-invocation", "user-invocable", "allowed-tools",
+    "disallowed-tools", "model", "effort", "context", "agent", "hooks",
+    "paths", "shell", "license", "metadata", "version",
+}
+
+KEY_RE = re.compile(r"^([A-Za-z0-9_-]+)\s*:(.*)$")
+BLOCK_MARKERS = {">", "|", ">-", "|-", ">+", "|+"}
+CUE_RE = re.compile(
+    r"\b(use[sd]?|using|when|whenever|for|trigger\w*|invoke\w*)\b", re.I)
+
+
+def parse_frontmatter(text):
+    """YAML-lite frontmatter parse: (fields, keys, state).
+
+    fields: top-level key -> joined string value (folded/literal blocks and
+    plain continuations joined with spaces; surrounding quotes stripped).
+    keys: every top-level key in order (duplicates preserved).
+    state: "ok" | "none" (no frontmatter) | "unclosed" | "junk:<line>".
+    Nested structures (hooks:, arguments:) keep their key; values are unused.
+    """
+    lines = text.lstrip("\ufeff").splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}, [], "none", text
+    fields, keys, current = {}, [], None
+    for i, ln in enumerate(lines[1:], start=1):
+        if ln.strip() == "---":
+            body = "\n".join(lines[i + 1:])
+            return fields, keys, "ok", body
+        if not ln.strip() or ln.lstrip().startswith("#"):
+            continue
+        if ln[0] in " \t":                       # continuation / nested line
+            if current is None:
+                return fields, keys, "junk:%d" % i, ""
+            more = ln.strip()
+            fields[current] = (fields[current] + " " + more).strip()
+            continue
+        m = KEY_RE.match(ln)
+        if not m:                                # top-level junk breaks YAML
+            return fields, keys, "junk:%d" % i, ""
+        current, val = m.group(1), m.group(2).strip()
+        keys.append(current)
+        if val in BLOCK_MARKERS:
+            val = ""
+        elif len(val) >= 2 and val[0] == val[-1] and val[0] in "'\"":
+            val = val[1:-1]
+        fields[current] = val
+    return fields, keys, "unclosed", ""
+
+
+def first_paragraph(body):
+    for block in re.split(r"\n\s*\n", body.strip()):
+        block = block.strip()
+        if block:
+            return " ".join(block.split())
+    return ""
+
+
+def is_true(value):
+    return str(value).strip().lower() == "true"
+
+
+def lint_skill(md_path):
+    """Lint one SKILL.md; returns the per-skill report dict."""
+    dir_name = md_path.parent.name
+    findings = []
+
+    def flag(severity, rule, message):
+        findings.append({"severity": severity, "rule": rule, "message": message})
+
+    try:
+        text = md_path.read_text(errors="replace")
+    except OSError as exc:
+        flag("error", "unreadable", "cannot read SKILL.md: %s" % exc)
+        return {"skill": dir_name, "path": str(md_path), "findings": findings,
+                "listing_chars": 0, "manual_only": False}
+
+    fields, keys, state, body = parse_frontmatter(text)
+    body = body.strip()
+    desc = fields.get("description", "").strip()
+    when = fields.get("when_to_use", "").strip()
+    manual_only = is_true(fields.get("disable-model-invocation", ""))
+
+    if state == "unclosed":
+        flag("error", "broken-frontmatter",
+             "opening --- is never closed: Claude loads this skill with "
+             "empty metadata, so it never auto-triggers")
+    elif state.startswith("junk:"):
+        flag("error", "broken-frontmatter",
+             "unparseable line %s in frontmatter: malformed YAML means empty "
+             "metadata, so the skill never auto-triggers" % state[5:])
+    elif state == "none":
+        flag("warning", "no-frontmatter",
+             "no YAML frontmatter: Claude falls back to the first paragraph "
+             "of the body to decide when to use this skill")
+
+    if state == "ok":
+        for key in sorted(set(keys)):
+            if keys.count(key) > 1:
+                flag("warning", "duplicate-key",
+                     "frontmatter key '%s' appears %d times; only one value "
+                     "survives" % (key, keys.count(key)))
+        for key in dict.fromkeys(keys):          # unique, in order
+            if key not in KNOWN_KEYS:
+                close = difflib.get_close_matches(key, KNOWN_KEYS, n=1)
+                hint = " (did you mean '%s'?)" % close[0] if close else ""
+                flag("warning", "unknown-key",
+                     "frontmatter key '%s' is not a documented field and is "
+                     "ignored silently%s" % (key, hint))
+
+    if not manual_only and state in ("ok", "none"):
+        matchable = desc or first_paragraph(body)
+        if not matchable:
+            flag("error", "undiscoverable",
+                 "no description and an empty body: nothing for Claude to "
+                 "match, this skill can never trigger")
+        elif state == "none":
+            pass                                 # no-frontmatter already flagged
+        elif not desc:
+            flag("warning", "no-description",
+                 "no description in frontmatter: triggering relies on the "
+                 "first body paragraph, which was not written for matching")
+        else:
+            if len(desc) < SHORT_DESC:
+                flag("warning", "desc-too-short",
+                     "description is %d chars: too little for Claude to "
+                     "match against" % len(desc))
+            elif not CUE_RE.search(desc + " " + when):
+                flag("warning", "no-when-cue",
+                     "description says what the skill does but never when to "
+                     "use it (no 'use/when/for/trigger...' cue): skills "
+                     "without usage context under-trigger")
+            combined = len(desc) + (len(when) + 1 if when else 0)
+            if combined > LISTING_CAP:
+                flag("warning", "desc-truncated",
+                     "description + when_to_use is %d chars; the listing "
+                     "caps it at %d, the last %d chars are invisible to "
+                     "Claude" % (combined, LISTING_CAP, combined - LISTING_CAP))
+
+    if state == "ok" and not body:
+        flag("warning", "empty-body",
+             "frontmatter but no instructions: the skill triggers and "
+             "delivers nothing")
+
+    shown_name = fields.get("name", "").strip() or dir_name
+    if manual_only:
+        listing = 0                              # removed from context entirely
+    else:
+        combined = (desc + (" " + when if when else "")) or \
+            ("" if state not in ("ok", "none") else first_paragraph(body))
+        listing = len(shown_name) + min(len(combined), LISTING_CAP)
+
+    return {"skill": dir_name, "path": str(md_path), "findings": findings,
+            "listing_chars": listing, "manual_only": manual_only}
+
+
+def resolve_skills_dir(cli_value=None):
+    """Precedence: --dir flag > $CLAUDE_CONFIG_DIR/skills > ~/.claude/skills."""
+    if cli_value:
+        return Path(cli_value).expanduser()
+    env = os.environ.get("CLAUDE_CONFIG_DIR")
+    if env:
+        return Path(env).expanduser() / "skills"
+    return Path.home() / ".claude" / "skills"
+
+
+def lint_dir(skills_dir):
+    reports = []
+    for entry in sorted(skills_dir.iterdir()):
+        if not entry.is_dir() or entry.name.startswith("."):
+            continue
+        md = entry / "SKILL.md"
+        if md.is_file():
+            reports.append(lint_skill(md))
+        else:
+            reports.append({
+                "skill": entry.name, "path": str(entry), "findings": [
+                    {"severity": "warning", "rule": "no-skill-md",
+                     "message": "directory has no SKILL.md: it is not a "
+                                "skill and is never loaded"}],
+                "listing_chars": 0, "manual_only": False})
+    return reports
+
+
+def print_report(skills_dir, reports, verdict):
+    print("skill-lint — SKILL.md quality + boot cost")
+    print("skills dir: %s" % skills_dir)
+    print()
+    width = max((len(r["skill"]) for r in reports), default=0)
+    sev = {"error": "ERROR", "warning": "WARN"}
+    for r in reports:
+        worst = ("ERROR" if any(f["severity"] == "error" for f in r["findings"])
+                 else "WARN " if r["findings"] else "ok   ")
+        cost = ("manual-only, 0 chars at boot" if r["manual_only"]
+                else "%d chars (~%d tok) at boot"
+                % (r["listing_chars"], r["listing_chars"] // CHARS_PER_TOKEN))
+        print("%s %-*s  %s" % (worst, width, r["skill"], cost))
+        for f in r["findings"]:
+            print("      - %s [%s]: %s" % (sev[f["severity"]], f["rule"],
+                                           f["message"]))
+    print()
+    print("verdict — skills: %d · errors: %d · warnings: %d · boot cost: "
+          "%d chars (~%d tokens) of names+descriptions every session"
+          % (verdict["skills"], verdict["errors"], verdict["warnings"],
+             verdict["listing_chars"], verdict["est_tokens"]))
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="skill-lint",
+        description="Lint Claude Code skills: descriptions that never "
+                    "trigger, silent frontmatter typos, boot-token cost.")
+    parser.add_argument("--dir", metavar="DIR",
+                        help="skills directory (default: "
+                             "$CLAUDE_CONFIG_DIR/skills, then ~/.claude/skills)")
+    parser.add_argument("--json", action="store_true",
+                        help="machine-readable output")
+    parser.add_argument("--version", action="version",
+                        version="%(prog)s " + __version__)
+    args = parser.parse_args(argv)
+
+    skills_dir = resolve_skills_dir(args.dir)
+
+    if skills_dir.exists() and not skills_dir.is_dir():
+        print("skill-lint: %s is not a directory" % skills_dir,
+              file=sys.stderr)
+        return 2
+
+    if not skills_dir.is_dir():
+        reports = []
+    else:
+        try:
+            reports = lint_dir(skills_dir)
+        except OSError as exc:
+            print("skill-lint: cannot read %s: %s" % (skills_dir, exc),
+                  file=sys.stderr)
+            return 2
+
+    errors = sum(1 for r in reports for f in r["findings"]
+                 if f["severity"] == "error")
+    warnings = sum(1 for r in reports for f in r["findings"]
+                   if f["severity"] == "warning")
+    listing = sum(r["listing_chars"] for r in reports)
+    code = 1 if (errors or warnings) else 0
+    verdict = {"skills": len(reports), "errors": errors, "warnings": warnings,
+               "listing_chars": listing,
+               "est_tokens": listing // CHARS_PER_TOKEN, "exit": code}
+
+    if args.json:
+        print(json.dumps({"skills_dir": str(skills_dir), "skills": reports,
+                          "verdict": verdict}, ensure_ascii=False, indent=2))
+        return code
+
+    if not reports:
+        print("skill-lint: no skills found in %s" % skills_dir)
+        print("Nothing to lint. If your skills live elsewhere, point at them "
+              "with --dir DIR or $CLAUDE_CONFIG_DIR.")
+        return 0
+
+    print_report(skills_dir, reports, verdict)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

claude_skill_lint-0.1.0/tests/test_cli.py

@@ -0,0 +1,367 @@
+"""Tests for skill-lint.
+
+Every test runs against synthetic skills fabricated in a pytest tmp_path.
+Nothing reads the host machine's real ~/.claude: an autouse fixture strips
+$CLAUDE_CONFIG_DIR and every invocation points at a fixture directory.
+"""
+import json
+import os
+import subprocess
+import sys
+
+import pytest
+
+from skill_lint import __version__
+from skill_lint.cli import main, parse_frontmatter, resolve_skills_dir
+
+HEALTHY_DESC = ("Use when testing alpha things. Covers folded YAML "
+                "descriptions across several lines.")
+
+
+@pytest.fixture(autouse=True)
+def isolate_env(monkeypatch):
+    """Never let the host's real config leak into a test."""
+    monkeypatch.delenv("CLAUDE_CONFIG_DIR", raising=False)
+
+
+# --- helpers -----------------------------------------------------------------
+
+def write_skill(root, name, content):
+    md = root / name / "SKILL.md"
+    md.parent.mkdir(parents=True, exist_ok=True)
+    md.write_text(content)
+    return md
+
+
+def healthy(root, name="alpha"):
+    return write_skill(root, name,
+                       "---\nname: %s\ndescription: >\n  Use when testing "
+                       "alpha things. Covers folded YAML\n  descriptions "
+                       "across several lines.\nlicense: MIT\n---\n\n"
+                       "# %s\n\nDo the thing.\n" % (name, name))
+
+
+def run_json(capsys, argv):
+    code = main(argv)
+    return code, json.loads(capsys.readouterr().out)
+
+
+def rules(report):
+    return [f["rule"] for f in report["findings"]]
+
+
+def one_skill(data):
+    (skill,) = data["skills"]
+    return skill
+
+
+# --- no skills ---------------------------------------------------------------
+
+def test_missing_dir_is_clean(tmp_path, capsys):
+    code = main(["--dir", str(tmp_path / "nowhere")])
+    out = capsys.readouterr().out
+    assert code == 0
+    assert "no skills found" in out
+    assert "--dir DIR or $CLAUDE_CONFIG_DIR" in out
+
+
+def test_empty_dir_is_clean_json(tmp_path, capsys):
+    root = tmp_path / "skills"
+    root.mkdir()
+    code, data = run_json(capsys, ["--dir", str(root), "--json"])
+    assert code == 0
+    assert data["skills"] == []
+    assert data["verdict"] == {"skills": 0, "errors": 0, "warnings": 0,
+                               "listing_chars": 0, "est_tokens": 0, "exit": 0}
+
+
+def test_root_is_a_file_exits_2(tmp_path, capsys):
+    f = tmp_path / "skills"
+    f.write_text("not a dir")
+    assert main(["--dir", str(f)]) == 2
+    assert "not a directory" in capsys.readouterr().err
+
+
+# --- healthy skill -----------------------------------------------------------
+
+def test_healthy_skill_is_clean(tmp_path, capsys):
+    healthy(tmp_path)
+    code = main(["--dir", str(tmp_path)])
+    out = capsys.readouterr().out
+    assert code == 0
+    assert "ok" in out and "alpha" in out
+    assert "ERROR" not in out and "WARN" not in out
+
+
+def test_folded_description_counted_exactly(tmp_path, capsys):
+    """The classic folded-YAML (`>`) description must be read, not skipped."""
+    healthy(tmp_path)
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    skill = one_skill(data)
+    assert code == 0
+    assert skill["findings"] == []
+    assert skill["listing_chars"] == len("alpha") + len(HEALTHY_DESC)
+
+
+def test_quoted_description_unquoted(tmp_path, capsys):
+    write_skill(tmp_path, "q",
+                '---\ndescription: "Use when quoting things."\n---\nBody.\n')
+    _, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    skill = one_skill(data)
+    assert skill["findings"] == []
+    assert skill["listing_chars"] == len("q") + len("Use when quoting things.")
+
+
+# --- broken / missing frontmatter ---------------------------------------------
+
+def test_unclosed_frontmatter_is_error(tmp_path, capsys):
+    write_skill(tmp_path, "broken",
+                "---\nname: broken\ndescription: never closed\n\nBody text.\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    assert code == 1
+    assert rules(one_skill(data)) == ["broken-frontmatter"]
+    assert data["verdict"]["errors"] == 1
+
+
+def test_junk_line_in_frontmatter_is_error(tmp_path, capsys):
+    write_skill(tmp_path, "junky",
+                "---\nname: junky\n- stray list item\n---\nBody.\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    assert code == 1
+    assert rules(one_skill(data)) == ["broken-frontmatter"]
+
+
+def test_no_frontmatter_warns_and_falls_back(tmp_path, capsys):
+    write_skill(tmp_path, "bare", "Use when running bare skills.\n\nMore.\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    skill = one_skill(data)
+    assert code == 1
+    assert rules(skill) == ["no-frontmatter"]
+    assert skill["listing_chars"] == \
+        len("bare") + len("Use when running bare skills.")
+
+
+# --- description quality -------------------------------------------------------
+
+def test_missing_description_warns(tmp_path, capsys):
+    write_skill(tmp_path, "nodesc", "---\nname: nodesc\n---\nSome body.\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    assert code == 1
+    assert rules(one_skill(data)) == ["no-description"]
+
+
+def test_no_description_empty_body_is_undiscoverable(tmp_path, capsys):
+    write_skill(tmp_path, "ghost", "---\nname: ghost\n---\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    skill = one_skill(data)
+    assert code == 1
+    assert set(rules(skill)) == {"undiscoverable", "empty-body"}
+    assert data["verdict"]["errors"] == 1
+    assert data["verdict"]["warnings"] == 1
+
+
+def test_short_description_warns(tmp_path, capsys):
+    write_skill(tmp_path, "tiny", "---\ndescription: Does stuff.\n---\nBody.\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    assert code == 1
+    assert rules(one_skill(data)) == ["desc-too-short"]
+
+
+def test_no_when_cue_warns(tmp_path, capsys):
+    write_skill(tmp_path, "vague",
+                "---\ndescription: Formats JSON documents beautifully.\n---\n"
+                "Body.\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    assert code == 1
+    assert rules(one_skill(data)) == ["no-when-cue"]
+
+
+def test_when_cue_via_when_to_use_passes(tmp_path, capsys):
+    write_skill(tmp_path, "cued",
+                "---\ndescription: Formats JSON documents beautifully.\n"
+                "when_to_use: Use when the user pastes raw JSON.\n---\nBody.\n")
+    assert main(["--dir", str(tmp_path)]) == 0
+
+
+def test_overlong_listing_text_warns_with_overflow(tmp_path, capsys):
+    desc = "Use when testing. " + "x" * 982          # 1000 chars
+    when = "y" * 600
+    write_skill(tmp_path, "fat",
+                "---\ndescription: %s\nwhen_to_use: %s\n---\nBody.\n"
+                % (desc, when))
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    skill = one_skill(data)
+    assert code == 1
+    assert rules(skill) == ["desc-truncated"]
+    assert "the last 65 chars are invisible" in skill["findings"][0]["message"]
+    assert skill["listing_chars"] == len("fat") + 1536
+
+
+# --- frontmatter keys ----------------------------------------------------------
+
+def test_unknown_key_suggests_close_match(tmp_path, capsys):
+    write_skill(tmp_path, "typo",
+                "---\ndescripton: Use when spelling fails.\n---\nBody.\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    skill = one_skill(data)
+    assert code == 1
+    assert "unknown-key" in rules(skill)
+    assert "no-description" in rules(skill)      # the typo's real casualty
+    joined = " ".join(f["message"] for f in skill["findings"])
+    assert "did you mean 'description'?" in joined
+
+
+def test_duplicate_key_warns(tmp_path, capsys):
+    write_skill(tmp_path, "twice",
+                "---\ndescription: Use when one.\ndescription: Use when two.\n"
+                "---\nBody.\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    assert code == 1
+    assert "duplicate-key" in rules(one_skill(data))
+
+
+def test_documented_keys_accepted(tmp_path, capsys):
+    write_skill(tmp_path, "full",
+                "---\nname: full\ndescription: Use when everything is set.\n"
+                "when_to_use: Whenever.\nargument-hint: '[file]'\n"
+                "allowed-tools: Read Grep\nmodel: inherit\nuser-invocable: "
+                "true\npaths: src/**\nlicense: MIT\n---\nBody.\n")
+    assert main(["--dir", str(tmp_path)]) == 0
+
+
+# --- manual-only skills --------------------------------------------------------
+
+def test_manual_only_skips_trigger_checks(tmp_path, capsys):
+    write_skill(tmp_path, "manual",
+                "---\nname: manual\ndisable-model-invocation: true\n---\n"
+                "Run the deploy.\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    skill = one_skill(data)
+    assert code == 0
+    assert skill["findings"] == []
+    assert skill["manual_only"] is True
+    assert skill["listing_chars"] == 0           # removed from context
+    assert data["verdict"]["listing_chars"] == 0
+
+
+# --- empty body ----------------------------------------------------------------
+
+def test_empty_body_warns(tmp_path, capsys):
+    write_skill(tmp_path, "hollow",
+                "---\ndescription: Use when hollow skills are needed.\n---\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    assert code == 1
+    assert rules(one_skill(data)) == ["empty-body"]
+
+
+# --- stray directories -----------------------------------------------------------
+
+def test_dir_without_skill_md_warns_hidden_ignored(tmp_path, capsys):
+    (tmp_path / "stray").mkdir()
+    (tmp_path / ".git").mkdir()
+    healthy(tmp_path)
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    assert code == 1
+    names = [s["skill"] for s in data["skills"]]
+    assert names == ["alpha", "stray"]
+    stray = data["skills"][1]
+    assert rules(stray) == ["no-skill-md"]
+
+
+# --- directory resolution --------------------------------------------------------
+
+def test_dir_flag_beats_env(tmp_path, monkeypatch, capsys):
+    flag_root = tmp_path / "flag"
+    healthy(flag_root)
+    env_cfg = tmp_path / "envcfg"
+    healthy(env_cfg / "skills", name="from-env")
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(env_cfg))
+    code, data = run_json(capsys, ["--dir", str(flag_root), "--json"])
+    assert data["skills_dir"] == str(flag_root)
+    assert [s["skill"] for s in data["skills"]] == ["alpha"]
+
+
+def test_env_var_honored(tmp_path, monkeypatch, capsys):
+    cfg = tmp_path / "cfg"
+    healthy(cfg / "skills")
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(cfg))
+    code, data = run_json(capsys, ["--json"])
+    assert code == 0
+    assert data["skills_dir"] == str(cfg / "skills")
+
+
+def test_default_falls_back_to_home_dot_claude(tmp_path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))  # windows
+    assert resolve_skills_dir(None) == tmp_path / ".claude" / "skills"
+
+
+# --- output shape -----------------------------------------------------------------
+
+def test_json_shape_and_verdict_consistency(tmp_path, capsys):
+    healthy(tmp_path)
+    write_skill(tmp_path, "ghost", "---\n---\n")
+    code, data = run_json(capsys, ["--dir", str(tmp_path), "--json"])
+    assert code == 1
+    assert set(data) == {"skills_dir", "skills", "verdict"}
+    assert set(data["skills"][0]) == {"skill", "path", "findings",
+                                      "listing_chars", "manual_only"}
+    v = data["verdict"]
+    assert v["skills"] == 2
+    assert v["errors"] == sum(1 for s in data["skills"]
+                              for f in s["findings"]
+                              if f["severity"] == "error")
+    assert v["est_tokens"] == v["listing_chars"] // 4
+    assert v["exit"] == 1
+
+
+def test_human_output_verdict_line(tmp_path, capsys):
+    healthy(tmp_path)
+    main(["--dir", str(tmp_path)])
+    out = capsys.readouterr().out
+    assert "verdict — skills: 1" in out
+    assert "every session" in out
+
+
+# --- parser unit -------------------------------------------------------------------
+
+@pytest.mark.parametrize("text,expected_desc", [
+    ("---\ndescription: plain value\n---\n", "plain value"),
+    ("---\ndescription: >\n  folded one\n  folded two\n---\n",
+     "folded one folded two"),
+    ("---\ndescription: |\n  literal one\n  literal two\n---\n",
+     "literal one literal two"),
+    ("---\ndescription: >-\n  chomped\n---\n", "chomped"),
+    ("\ufeff---\ndescription: after bom\n---\n", "after bom"),
+])
+def test_parse_frontmatter_descriptions(text, expected_desc):
+    fields, keys, state, _ = parse_frontmatter(text)
+    assert state == "ok"
+    assert fields["description"] == expected_desc
+
+
+def test_parse_frontmatter_states():
+    assert parse_frontmatter("no marker\n")[2] == "none"
+    assert parse_frontmatter("---\nkey: val\n")[2] == "unclosed"
+    assert parse_frontmatter("---\n- junk\n---\n")[2] == "junk:1"
+
+
+# --- entry points --------------------------------------------------------------------
+
+def test_version_flag(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["--version"])
+    assert exc.value.code == 0
+    assert __version__ in capsys.readouterr().out
+
+
+def test_python_dash_m_entrypoint(tmp_path):
+    cfg = tmp_path / "cfg"
+    healthy(cfg / "skills")
+    env = {**os.environ, "CLAUDE_CONFIG_DIR": str(cfg)}
+    proc = subprocess.run([sys.executable, "-m", "skill_lint", "--json"],
+                          capture_output=True, text=True, env=env)
+    assert proc.returncode == 0
+    data = json.loads(proc.stdout)
+    assert data["skills_dir"] == str(cfg / "skills")
+    assert [s["skill"] for s in data["skills"]] == ["alpha"]