skillcheck is a static analyzer for SKILL.md files, the format agents like Claude Code, Copilot, Codex, and Cursor use to load reusable skills. It validates frontmatter, scores description discoverability, checks file references, enforces token budgets, and flags cross-agent compatibility issues. No network calls, no LLM calls, no file mutations. Runs as a CLI, a GitHub Action, or a pre-commit hook.
pip install skillcheck
skillcheck skills/
Latest pass was hardening and accuracy, not features. Here's what changed and why.
Description scores went up. Skills that were scoring low because the scorer was broken will now see a jump in scoring. Median across the reference corpus went from 75 to 90. --explain-score also now tells you which pattern hits or misses instead of just a number. The score exists to predict whether an agent will actually find and trigger your skill, so a scorer that under-credits good descriptions defeats the point. The fix was validated against real-world skills, and the separation held: filler still scores 28-65, well-written descriptions 85-100.
Corrupt files now fail cleanly instead of crashing. Before, a bad history ledger or non-UTF-8 skillcheck.toml above the skill dumped a Python traceback. It's now a clear error naming the file and byte offset (exit code 2). Config discovery walks up the directory tree, so one bad file could break every scan under it. Now every untrusted read (ingest, history, config) goes through the same guard before parsing, so they all reject the same way.
README has been corrected in regards to token estimates. Without tiktoken, expect roughly 20-30% over-estimation, so install the extra if you're near a budget limit. The offline heuristic feeds the budget checks and its accuracy had never actually been measured, just assumed. It's benchmarked against tiktoken across the full corpus now, and the documented numbers are the measured ones.
pip install "skillcheck[tiktoken]"
The rest of the pass is invisible on purpose: flag-conflict logic consolidated to one source of truth, golden-file tests pinning exact diagnostic output, coverage floor raised from 75% to 80% (actual sits at 90%). Diagnostic output across the corpus verified byte-for-byte identical before and after. Nothing changed except what's above.
moonrunnerkc
/
skillcheck
Cross-agent skill quality gate for SKILL.md files. Validates frontmatter, scores description discoverability, checks file references, enforces three-tier token budgets, and flags compatibility issues across Claude Code, VS Code/Copilot, Codex, and Cursor.
Static analyzer for SKILL.md files. Validates frontmatter, body sizing, file references, and cross-agent compatibility against the agentskills.io specification. No network calls. No LLM API calls. No file mutations.
1058 tests cover all rule modules.
Install
pip install skillcheck
Requires Python 3.10 or later. For more accurate token estimates, install the optional extra:
pip install "skillcheck[tiktoken]"
Token estimation accuracy
Token counts are estimates, and the sizing rules report them as such. The bands below are measured, not estimated: scripts/measure_token_error.py compares the offline heuristic against tiktoken cl100k_base across a corpus of 61 real SKILL.md files, for the three spans the rules actually size.
Span
Rule
Median error
p95 error
Direction
Whole file
sizing.total-tokens
23.0%
30.7%
over-estimates 61/61
Frontmatter
disclosure.metadata-budget
25.9%
35.3%
over-estimates 61/61
Body
disclosure.body-budget
22.7%
30.7%
over-estimates 61/61
The bias is one-directional: the offline heuristic read high on every file in the corpus. For a budget check that…
If skillcheck flags something in your skills that looks wrong, open an issue. The reference corpus grows from real-world cases and the scorer improves with them.
Top comments (0)