Skill Audit

Audit all installed skills for quality, duplicates, structural issues, and best-practice compliance. Use when asked to review, audit, lint, or check skills f...

Security Scan

The skill's code and instructions are consistent with an on-device skill-audit purpose; nothing requests unrelated credentials or external networks, though there are a few small inconsistencies in the docs vs the script's exact behavior.

Purpose & Capability

Name/description match the included script and behavior. The bundled script scans local skill directories (workspace and a candidate global path under $HOME) to produce per-skill metadata and scores; these capabilities are appropriate for an audit skill.

Instruction Scope

Runtime instructions tell the agent to run scripts/audit.sh and state results are written to .sub-agent-results/skill-audit-report.md and summarized in chat. The script prints a delimited header and one-line records to stdout (and lists orphan .skill files) but does not itself write to .sub-agent-results/skill-audit-report.md or render a markdown report. This is a functional inconsistency (the agent can capture stdout and write the file, but the SKILL.md overstates what the script itself does).

Install Mechanism

No install spec and only a small local shell script are present. No network downloads or package installs are performed by the skill bundle; risk from installation is minimal.

Credentials

No env vars, credentials, or special config paths are requested. The script uses $HOME and reads skill directories; this is expected for a local audit and proportionate to the stated purpose.

Persistence & Privilege

Skill does not request always:true, does not modify other skills or global agent settings, and has normal model invocation settings. It only reads filesystem locations and prints a report; no privileged persistence is requested.

Assessment

This skill appears to do what it claims: scan local skill folders and produce a simple scorecard. Before running, check and confirm the directories it will scan (default WORKSPACE_SKILLS is $HOME/clawd/skills and it also probes a candidate global path under $HOME). Note the SKILL.md says results are written to .sub-agent-results/skill-audit-report.md but the included script writes CSV-like output to stdout (you should redirect or have the agent capture stdout to save the report to that path). Inspect the script yourself if you want to be sure what files will be read, and run it with limited filesystem permissions if you have sensitive files in the scanned trees.

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

7. Duplicates — Same skill name or overlapping functionality across global/workspace/project dirs
8. Orphan files — Stale .skill files, empty dirs, leftover copies
9. Category gaps — Which of the 9 categories have no skills at all?
10. 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

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

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

References

• Anthropic: Lessons from Building Claude Code Skills — Thariq's 9 categories, gotchas sections, progressive disclosure
• Ole Lehmann: Auto-improve Skills — Autoresearch loop (future enhance mode)