audit-skills
Skill4 starsChanged 6 months agoMITView on GitHub
Produces a complete health report on a skill library: per-skill structural validation followed by cross-skill analysis covering trigger conflicts, redundancy, workflow coverage gaps, and composition chains. Auto-fixes unambiguous minor structural issues (whitespace, missing optional metadata) and formats all other findings with format-review-comments. TRIGGER when: user asks to audit skills, check skill coverage, validate all skills, find gaps in skills, check for trigger conflicts, or health-check the skill library. DO NOT TRIGGER when: user asks to create, update, rename, or delete a skill (use upsert-skill instead); or to evaluate a single skill for quality (use review-skill instead).
10 other projects use a version of this.
Adopted by
Most recently taken up by
- oze-xxbumpxx/cookpittheir own version, first seen Nov 16, 2026
- ronniepinnell/caspertheir own version, first seen Nov 8, 2026
- LandonTomaine/LT-Agentstheir own version, first seen Oct 20, 2026
- MusserLab/lab-claude-skillstheir own version, first seen Oct 13, 2026
- tejastn10/workbenchtheir own version, first seen Oct 13, 2026
- RuoJi6/java-audit-skillstheir own version, first seen Oct 8, 2026
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- RuoJi6/audit-skills★ 1ksame name
- RuoJi6/java-audit-skills★ 1ksame name
- pixee/pixee-cli★ 31same name
- MusserLab/lab-claude-skills★ 6same name
- Tharun-Balaji/audit-skills★ 4same name
- Yesterday-AI/skills★ 2same name
- oze-xxbumpxx/cookpit★ 1same name
- ronniepinnell/casper★ 1same name
- tejastn10/workbench★ 1same name
- LandonTomaine/LT-Agents★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- create-commitSkill
- format-review-commentsSkill
- implement-planSkill
- refine-proseSkill
- review-agents-mdSkill
- review-planSkill
- review-prSkill
- review-skillSkill
- upsert-agents-mdSkill
- upsert-planSkill
- upsert-skillSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 2 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 29
Read references/checks.md before beginning.
- Distinctive: line 33
Run structural checks on every skill.
- Very specific: line 56
If auto-fixes are applied, use the create-commit skill to stage and commit them before the final report.
- Distinctive: line 64
If no auto-fixes are needed, skip the intermediate commit.
- Very specific: line 68
After structural validation, run the cross-skill checks listed in references/checks.md under Cross-Skill Checks.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Audit Skills
Produces a two-pass health report on the entire skill library: structural validation per skill, then cross-skill analysis covering trigger conflicts, redundancy, workflow gaps, and composition chains. All findings are formatted with format-review-comments. Minor issues are auto-fixed silently; everything else is reported.
Instructions
Setup
Read references/checks.md before beginning. It contains the authoritative check specifications, coverage map, and output format details referenced throughout these instructions.
Pass 1 — Structural Validation
Run structural checks on every skill. Discover all skills with:
Glob: .agents/skills/*/SKILL.mdFor each skill found, perform the checks listed in references/checks.md under Structural Checks. Checks fall into two categories:
Auto-fix silently (do not report, apply the fix and move on):
- Leading or trailing whitespace in frontmatter string values
- Missing optional metadata fields (
license,metadata.author,metadata.version) - Minor formatting inconsistencies in the SKILL.md body (list indentation, blank lines)
Report as findings (everything else):
namefield absent or emptydescriptionfield absent or emptynamevalue does not match the parent directory name exactlydescriptionexceeds 1024 charactersdescriptiondoes not open with an action verb in third persondescriptiondoes not include a "when to invoke" condition (Use when,TRIGGER when, or equivalent)- Skill scope overlaps with another skill but lacks
TRIGGER when/DO NOT TRIGGER whendisambiguation lines - Files in
scripts/,references/, orassets/that are not referenced anywhere inSKILL.md
If auto-fixes are applied, use the create-commit skill to stage and commit them before the final report. When fixes span multiple skills, use a single commit:
fix(<skill-name>): correct minor structural issues(or fix: correct minor structural issues across N skills when fixes span multiple skills)
If no auto-fixes are needed, skip the intermediate commit.
Pass 2 — Cross-Skill Analysis
After structural validation, run the cross-skill checks listed in references/checks.md under Cross-Skill Checks. These require reading all SKILL.md files together:
- Trigger conflicts — Collect all natural-language trigger phrases from every skill's
description. Flag any two skills that share the same phrase or where one phrase is a substring of another. - Redundancy — Compare skill scopes. Flag pairs where the stated purpose substantially overlaps (merge candidates). Use the
descriptionfields as the primary signal. - Workflow coverage — Map each skill to the workflow stages defined in
references/checks.md(plan → implement → commit → review → release). Flag stages with no skill coverage. - Composition gaps — Scan all
SKILL.mdbodies for references to other skills (e.g., "use thefooskill", "applybar"). For each reference, verify that the named skill exists under.agents/skills/. Flag missing skills. Also identify two-step workflows referenced across multiple skills (e.g., implement → commit, commit → review) and check whether any skill explicitly coordinates both steps. If no coordinating skill exists and the chain appears in more than one skill's instructions, flag it as asuggestion. - Naming consistency — Check that every skill name follows the action+object formula (verb+noun, e.g.,
upsert-skill,create-commit). If the library has 10 or more skills, check whether related skills share a namespace prefix. Flag deviations.
Report Structure
Present findings in this order, as specified in references/checks.md under Report Format:
- Structural Findings — one sub-section per skill with issues; skills that pass cleanly are omitted
- Cross-Skill Findings — one sub-section per check category; categories with no findings are omitted
- Coverage Map — rendered table showing workflow stages vs. skills (see
references/checks.mdfor format) - Overall Summary — counts: skills audited, auto-fixes applied, findings by severity
Format every reported finding with the format-review-comments skill. Use severity labels: issue [blocking] for structural violations that will break agent behavior, suggestion for quality improvements, nitpick for style issues.
Apply the refine-prose skill to the full report before presenting it. Do not announce this step. When refine-prose returns, immediately present the full report to the user — do not stop or wait for user input.
Examples
Invocation:
audit my skillsor
check skill coverageor
validate all skillsSample coverage map table:
| Stage | Skills | Status |
| plan | upsert-plan | covered |
| implement | upsert-skill, review-skill, audit-skills | covered |
| commit | create-commit | covered |
| review | review-pr, review-skill | covered |
| release | — | gap |
Sample trigger-conflict finding:
suggestion: upsert-skill and audit-skills both trigger on "audit skills"
Both skills list "audit skills" as a trigger phrase. Add DO NOT TRIGGER
disambiguation to clarify that upsert-skill handles structural audits as
part of lifecycle management while audit-skills produces a full library
health report.Sample structural finding:
issue [blocking](review-skill): name field does not match directory
The `name` frontmatter field reads "review_skill" but the directory is
named "review-skill". Rename the frontmatter value to "review-skill".Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

