// 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.
Use for complex or high-risk implementation work that needs plan-first execution, explicit verification design, pre-code review, and autonomous post-implementation hardening through self-test, simplify, and review-loop.
Prove the requested goal works on the highest-signal affected surface before closing. Default closing behavior for every implementation task — not just when explicitly asked. Also triggers on: 'make sure it works', 'test it yourself', 'don't just tell me it's done', 'I don't want to test this'.
Post-implementation review/fix loop. Use host-appropriate review coverage on your implementation, fix issues, iterate until highly confident, then commit.
Lightweight read-only audit. Use host-appropriate review coverage for evidence and findings. Iterate on disagreement or low confidence. No code changes.
Iteratively clarify requirements for a new task until reaching 90%+ confidence, then auto-invoke plan-loop.
Orchestrate complex tasks with agent teams. Clarify requirements, plan with dual-model review, implement with TeamCreate, simplify, review, and ship.