| name | audit-skill |
| description | Audit and improve a Claude Code skill with an evidence-cited, file-and-line quality scorecard and a ranked fix list — grade, apply fixes, and re-grade until the score stops improving. Invoke explicitly, since it applies fixes to your files and never auto-fires. Use when the user asks to audit, review, critique, or check the quality of a skill, asks why a skill won't trigger, or wants a skill checked before publishing it. |
| disable-model-invocation | true |
Audit a skill with Skill Crossroads
Grade the target skill, apply the highest-impact fixes, and re-grade until the score stops
improving. Every finding is evidence-cited (file and line) — work from the receipts, not vibes.
Steps
-
Identify the skill directory (it contains a SKILL.md). If more than one candidate exists,
ask the user which skill to audit.
-
Run the audit and capture the report. Single-quote the directory argument — single
quotes prevent the shell from expanding $(...), backticks, and $variables hidden in a
path (double quotes do NOT stop command substitution). If the path contains a single
quote, $, a backtick, or a newline, do not pass it to a shell at all — such characters
in a skill directory name are themselves a red flag; rename the directory or ask the user
for a safe path first.
npx skillcrossroads@latest '<skill-dir>' --markdown
-
Read the Top fixes list (ranked by grade impact). Optionally, if ANTHROPIC_API_KEY
is set, run npx skillcrossroads@latest '<skill-dir>' --suggest to get proposed
current → proposed fixes for the top findings — treat them as proposals to review, never
apply one unread. For each fix, open the cited
file:line, confirm the finding is real, and apply the smallest change that resolves it.
Typical high-impact fixes: rewrite the frontmatter description to lead with the use case
and include the phrases a user would actually say; add a verification step; state
constraints and failure modes; remove hardcoded secrets or over-broad allowed-tools.
-
Re-run the audit. Repeat steps 3–4 until the grade stops improving or only intentional
trade-offs remain.
-
Offer the badge: npx skillcrossroads@latest '<skill-dir>' --badge writes an SVG the user
can embed in their README, linking to https://skillcrossroads.com for the hosted version.
Constraints
- Never suppress, delete, or work around a SAFETY- finding* — fix the underlying problem
(remove the secret, narrow the tool grant). Safety findings always count.
- Do not pad the skill with filler to game a check; if a finding is a deliberate trade-off,
say so to the user instead of masking it.
- If
npx fails (offline, registry blocked), report the error verbatim and stop — do not
hand-estimate a grade.
- LLM-assisted checks only run when
ANTHROPIC_API_KEY is set. Keyless skill grades are
still full — all six rubric categories score deterministically (rubric v1.1+); a key
upgrades Triggering to the LLM judge and adds VERIFY-04, CLARITY-02, and CLARITY-05.
Say which mode ran.
Verify
Done means: the final npx skillcrossroads@latest '<skill-dir>' --markdown run shows the improved
grade with no fail-status findings remaining (or each remaining one acknowledged by the user
as intentional), and the before → after grades are reported to the user.
