Use when a skill isn't triggering as expected, before adding a new skill (to check for a name collision), during periodic cleanup of an accumulated skills directory, or when asked to review skill quality — checks frontmatter validity, description quality against Skill Discovery Optimization conventions, body size, and cross-scope name collisions.
The English summary is being prepared. Showing the original description.
See how to installReview the instructions the agent will receive before you install.
Skills accumulate. Nobody deletes them, most developers hit 8-12 installed skills before the per-session token cost of loading every description starts to outweigh the benefit, and a skill installed at both the personal and project scope with the same name fails silently — the higher-precedence one wins and the other never fires, with no error anywhere. This script checks the mechanical properties that predict a skill working or silently failing: valid frontmatter, a description that leads with the trigger (not a workflow summary), a body under the token-efficiency guideline, and no name collision across scopes.
Core principle: A skill that never triggers and a skill that doesn't exist have the same effect on the user, but only one of them is visible in a directory listing. This script finds the invisible kind.
python3 ${CLAUDE_SKILL_DIR}/scripts/audit.py [skills_dir ...]
With no arguments, checks .claude/skills/ (project) and ~/.claude/skills/ (personal) if they exist. Pass explicit paths to also check a plugin's skills/ directory (plugin skill dirs aren't auto-discovered, since a plugin's install location varies). Exit code 0 = clean, 1 = findings, 2 = usage error.
python3 ${CLAUDE_SKILL_DIR}/scripts/audit.py .claude/skills ~/.claude/skills ./my-plugin/skills
| Check | Why it matters |
|---|---|
| Frontmatter parses | A SKILL.md without valid ----delimited YAML at the top is invisible to Claude Code — not degraded, just never loaded |
name field matches directory name | The command comes from the directory name for personal/project skills; a mismatched name field is almost always a copy-paste leftover from another skill |
| Description opens with a trigger phrase | Per Skill Discovery Optimization: "Route the task and adopt it as your instructions" (what it does) trains the model to act on the summary instead of reading the body; "Use when the user names a task" (when to fire) doesn't |
| Description doesn't summarize the workflow | A description that describes the process ("dispatches a subagent per task, reviews between each") gives the model a shortcut that has been observed to cause it to skip steps the actual skill body specifies |
| Description length | Over 1024 characters fails the Agent Skills spec limit |
| Body word count | Past ~2000 words (~500 lines), token cost per invocation is high enough that a reference file loaded on demand almost always beats keeping everything inline |
| Cross-scope name collisions | Two SKILL.md files with the same name (or same directory name) at different scopes — one always wins, the other never triggers, and nothing tells you which |
Whether the skill's instructions are correct, whether it actually gets invoked on the prompts it should (that requires running real scenarios — see the with-skill/without-skill baseline in agent-skills-prompt.md), or whether supporting files referenced from the body actually exist and are useful. This script catches the mechanical failure modes; it is not a substitute for testing trigger accuracy.
A clean audit means the skill is structurally capable of working. It says nothing about whether it triggers on the right prompts or produces the right output — that's a separate, behavioral test, not a static one.
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Use when evaluating, comparing, installing, or recommending a Claude Code plugin, Agent Skill, MCP server, agent toolkit, or GitHub-hosted AI extension, especially when popularity is weak evidence or the candidate requests shell, network, filesystem, or credential access.
The English summary is being prepared. Showing the original description.
Use when cutting a release, writing a CHANGELOG entry, or summarizing what changed since a tag — when the repo's commits follow (or mostly follow) Conventional Commits and a mechanically-accurate section breakdown beats a model's reading of the diff.
The English summary is being prepared. Showing the original description.
Use before committing, opening a PR, or reporting a task done — when you want ground-truth confirmation there are no conflict markers, live-looking credentials, debug leftovers, untracked TODOs, or oversized files, without spending a model turn re-reading every file yourself.
The English summary is being prepared. Showing the original description.
Use before publishing documentation, merging a docs PR, or reporting a Markdown-heavy repo's navigation as complete — when you want ground-truth confirmation that internal links, heading anchors, and directory links resolve, without opening every file yourself.
The English summary is being prepared. Showing the original description.
Use when the user names a coding or Claude Code task ("add OAuth", "set up hooks", "review this PR", "pick a model"), asks which prompt to use, says to "use the right prompt", or when you enter this repo and need to orient without reading every file.
The English summary is being prepared. Showing the original description.
Use when the user names a coding, Claude Code, research, documentation, or technology-selection task; asks which prompt to use; says to use the right prompt; or when an agent enters this repository and needs to orient without reading every file.
The English summary is being prepared. Showing the original description.