Happy Path Works
Available now

Free skill audit

This one is for people who write their own skills. If you want finished documents rather than a way to grade skill files, start with the free action items list or Document Ops.

Point it at a SKILL.md and it grades the file against seven gates, tells you exactly what is missing on each failure, and returns an exit code you can put in a script. It is free, its source is public, and it applies the same floor every paid skill here has to clear.

What a run looks like

skill_audit — skill-audit SKILL.md scripts: skill_audit.py [D] Upload-safe description PASS description is 781 of 1024 chars and holds no XML-tag shape. [R] References resolve PASS All 1 bundled path(s) resolve. (1 workspace path(s) skipped — not this skill's to resolve) [1] Names the gap PASS A gap/failure-mode statement is present. [2] Deterministic entry PASS A deterministic entry (prefix or unambiguous condition) is present (`audit:`). [3] Enforced hard-fails PASS Hard-fails are present and the skill ships a script (skill_audit.py). [4] Verify before voice NOT CHECKABLE No countable/spec'd constraint detected; gate not applicable. -> If the skill does have a hard constraint (a count, a spec), make sure it's verified, not asserted. [5] Loud failure, named exit PASS Scope boundaries name an explicit exit (if X, refuse and do Y). [6] No prior-chat references PASS No phrasing that leans on an earlier chat ("as we discussed", "like last time"). [7] Deciding example PASS A worked example is present and shows a catch, not just the happy path. FAIL 0 REVIEW 0 NOT CHECKABLE 1 PASS 8 VERDICT: PASS Every gate the lint can decide came back clean. One gate it cannot decide is marked NOT CHECKABLE above — read its -> line. Not graded: whether the skill works in a fresh session. The lint reads files; only a run shows what a model does with them. -> Open a session where your own project instructions do not load, install the skill from its archive, give it a real task that starts with `audit:`, and check what it does against what the skill promises.

Output captured verbatim from a run of skill_audit.py 2.0.0 against its own skill file on 2026-10-27; the path shown is the argument, so you pass your own. NOT CHECKABLE means the file gives that gate nothing to test; it does not count toward the verdict. exit 0 = pass · exit 2 = review · exit 1 = fail · exit 3 = refused, an input it will not grade (nothing gradable at that path, or a SKILL.md it cannot read as written) · exit 4 = usage, a wrong command line or Python older than 3.8. Put it in a pre-commit hook or a CI step; the code is the interface.

The seven gates

What a failure looks like.

1
Names the gap
The description explains what the skill does but not what goes wrong without it.
2
Deterministic entry
The trigger is a list of forty keywords and a hope.
3
Enforced hard-fails
The file says "never ship X" and nothing checks for X.
4
Verify before voice
The skill asserts a character count it never counted.
5
Loud failure, named exit
A boundary reads "stay in scope" with no instruction for what to do at the edge.
6
No prior-chat references
The skill leans on a conversation it does not contain — "as we discussed", "like last time". A fresh session never had that conversation, so it quietly does something else.
7
Deciding example
The only example is the obvious case working.

Install

Which file do you need?

The download is two files. Both hold the same skill and the same checker. Get the one for where you use Claude.

skill-audit.zip is for Claude Code. The full package: the skill, the checker, the worked examples, the tests and the plugin manifest. Unzip it and drop the whole skill-audit folder into your skills directory, each skill in its own folder:

Claude Code (personal)~/.claude/skills/skill-audit/
Claude Code (one project)<project>/.claude/skills/skill-audit/

skill-audit-upload.zip is for claude.ai and the desktop app. Six files: SKILL.md, skill_audit.py, README, SETUP, CHANGELOG, LICENSE. Upload it to your claude.ai account as it came, at claude.ai/customize/skills/new/upload. Do not unzip it.

Why two: claude.ai’s skill upload refuses a zip that holds a plugin manifest or more than one SKILL.md, and the full package has both (each worked example carries its own SKILL.md). Upload skill-audit.zip there and it is refused. The upload file is the same skill with those parts left out.

No dependencies to install. If you have Python 3.8 or newer, you can run this.

Install location differs by surface, and the two do not sync. A folder you drop into ~/.claude/skills/ or .claude/skills/ is local to Claude Code on that machine. Skills added to your claude.ai account are the ones that reach the web app, the desktop app, cloud sessions and routines. Installing one place does not install the other, so put it wherever you actually work. Use Claude Code and claude.ai both? Get both files.

Three ways to get it

GitHub — clone it, read it, fork it. A clone is the full package, for Claude Code.
Gumroad — $0 or pay what you want, if you would rather have it as a download. Two files: skill-audit.zip for Claude Code, skill-audit-upload.zip for claude.ai and the desktop app. Install, on this page, says which you need and why.
Newsletter — subscribe and the download link comes with the first issue.

Get the download by email

Subscribe and the download link comes with the first issue. Roughly monthly after that; unsubscribe from any issue.

What the paid audit adds

  • Scope-boundary analysis across a whole skill directory, not one file.
  • Trigger collision detection — which of your skills will fire on each other's inputs.
  • Session-hygiene scoring.
Session Discipline, January 12 →