S
SkillNav

skill-audit

by bill492

Audit all installed skills for quality, duplicates, structural issues, and best-practice compliance. Use when asked to review, audit, lint, or check skills for problems. Triggers on "audit skills", "skill quality", "check my skills", "skill duplicates", "skill hygiene".

View Chinese version with editor review

安装

claude skill add --url github.com/openclaw/skills/tree/main/skills/bill492/unblocklabs-skill-audit

文档

skill-audit

Scans all skill locations (global, workspace, project) and produces a structured audit report.

What It Checks

Structural Quality (per skill)

  1. Description quality — Is the description field trigger-oriented (tells the model when to use it) vs a vague summary?
  2. Gotchas section — Does the SKILL.md include a Gotchas/Pitfalls/Common Issues section? (Highest-signal content per Anthropic)
  3. Progressive disclosure — Does the skill use subdirectories (scripts/, references/, assets/, examples/) or is it a flat SKILL.md?
  4. File structure — Are there scripts, templates, or reference files the agent can discover?
  5. YAML frontmatter — Does it have name, description, and optionally compatibility?
  6. Category fit — Does it map cleanly to one of the 9 skill categories (Library/API, Verification, Data, Automation, Scaffolding, Code Quality, CI/CD, Runbooks, Infrastructure)?

Cross-Skill Issues

  1. Duplicates — Same skill name or overlapping functionality across global/workspace/project dirs
  2. Orphan files — Stale .skill files, empty dirs, leftover copies
  3. Category gaps — Which of the 9 categories have no skills at all?
  4. Stale skills — Skills that reference missing tools, dead paths, or deprecated APIs

How to Run

Tell the agent: "audit my skills" or "run skill-audit"

The agent will:

  1. Run scripts/audit.sh to scan all skill locations and collect metadata
  2. Score each skill (0-10) based on the checks above
  3. Produce a summary report with:
    • Per-skill scorecard
    • Top issues to fix (sorted by impact)
    • Category coverage map
    • Duplicate/orphan findings

Output

Results are written to .sub-agent-results/skill-audit-report.md and summarized in chat.

Scoring

PointsCriteria
+2Has YAML frontmatter with name + description
+2Description is trigger-oriented (contains "use when", "trigger", action verbs)
+2Has a Gotchas/Pitfalls/Common Issues section
+2Uses progressive disclosure (has subdirs with scripts/references/assets)
+1Has at least one script or executable file
+1SKILL.md is between 200-5000 chars (not too sparse, not bloated)

Scores: 8-10 = Good, 5-7 = Needs work, 0-4 = Poor

References