// Audit agent skills in a repo against best practices — checks .claude/skills/ and .agents/skills/ for quality, structure, and coverage gaps. Use when the user wants to review, improve, or evaluate their skills, or when they mention skill quality, skill audit, or skill best practices.
| name | skills-audit |
| description | Audit agent skills in a repo against best practices — checks .claude/skills/ and .agents/skills/ for quality, structure, and coverage gaps. Use when the user wants to review, improve, or evaluate their skills, or when they mention skill quality, skill audit, or skill best practices. |
Scan a repo's agent skills and audit them against field-tested best practices. Works across agent systems — Claude Code (.claude/skills/), Codex (.agents/skills/), or custom paths.
Search for skills in both user-level and project-level locations:
User-level (global installs):
~/.claude/skills/ — Claude Code skills~/.agents/skills/ — Codex / generic agent skills~/.claude/commands/ — Claude Code commandsProject-level (repo-local):
.claude/skills/ — Claude Code skills checked into the repo.agents/skills/ — Codex skills checked into the repoAlso check any custom paths the user provides. Deduplicate if the same skill appears in both locations.
For each skill found, note:
If no skills are found, tell the user and offer to help them create their first one.
Assign each skill to one of the 9 categories in references/categories.md. Read that file for the full taxonomy.
Classification signals:
If a skill clearly straddles two categories, flag it — this is a smell. Good skills fit cleanly into one category. Suggest how to split or refocus.
Apply the checklist from references/checklist.md to each skill. The checklist has two tiers:
.claude/skills/Use judgment about applicability. Not every check applies to every skill. The checklist has N/A options — use them. A 25-line behavioral skill shouldn't be penalized for lacking progressive disclosure or bundled scripts. A generic cross-repo skill shouldn't be penalized for "stating the obvious" when stating principles IS its purpose. Score only checks that are meaningful for that skill's purpose and size. The score denominator should reflect only the checks that apply (e.g., 5/6 if 2 checks were N/A out of 8).
For each applicable check, score as:
Look at the repo's actual contents to identify missing skill categories:
.github/workflows/, etc.) but no CI/CD skill?Suggest the highest-value skills to create, prioritized by how much time they'd save.
Present findings as a prioritized scorecard. Structure:
For each skill, show:
Top 3-5 changes that would have the biggest impact across all skills. These are the "do these first" items.
If the user asks to fix/improve a specific skill, interactively apply the audit findings:
Don't batch-apply fixes across all skills without asking — let the user pick which to improve.