TECHDEV · Open-source tool

skill-audit

Your agent skills pack is growing. Which skills are duplicates? Which ones fight over the same trigger? Which ones have no description, so the agent never picks them? skill-audit answers those questions in one command, with zero dependencies.

View on GitHub →Read the article →

Python 3.9+ · Zero dependencies · 9 checks · MIT

Who hurts, and what this does about it

Agent Skills packs are exploding — every week brings new packs, and teams copy skills from several sources into one folder. The result: two skills with the same name (the agent picks one arbitrarily), two skills with near-identical descriptions (both trigger on the same prompt, so you get random behaviour), skills with no description (the agent never triggers them, because the description is how it decides), skills with invalid names or no frontmatter (silently ignored by some loaders), and packs with no version (nobody knows whether they have the latest).

Existing skill packs add more skills. skill-audit tells you whether the ones you already have are healthy.

What it checks

Check	What it finds
`duplicate-name`	Two `SKILL.md` files declaring the same `name`
`invalid-name`	Names that are not kebab-case (`Bad Name`, `UPPER`, ...)
`missing-name` / `missing-description`	Frontmatter without `name` or `description`
`frontmatter-parse`	`SKILL.md` with no `---` block at all
`overlapping-description`	Identical descriptions, or ≥70% token overlap (Jaccard)
`description-length`	Under 20 chars, or over 1024 chars
`thin-body`	`SKILL.md` body under 50 chars — a header, not a skill
`missing-skill-md`	A folder with files but no `SKILL.md` — not discoverable
`no-version`	No `version` in frontmatter — consider adding one

Exit code 0 = no errors, 1 = errors found. Warnings never fail the run on their own.

Try it now

$ skill-audit check --path examples/messy
[ERROR] duplicate-name: Duplicate skill name 'dup-skill'
[ERROR] invalid-name: 'Bad Name' must be kebab-case
[ERROR] missing-description: no-desc has no 'description'
[ERROR] missing-description: (unnamed) has no 'description'
[ERROR] missing-name: no-frontmatter/SKILL.md has no 'name'
[WARN ] frontmatter-parse: no-frontmatter/SKILL.md missing frontmatter block
[WARN ] no-version: (unnamed) has no 'version' in frontmatter
Summary: 5 error(s), 2 warning(s), 5 skill(s).

Demo transcript copied exactly from the skill-audit README ("Demo"). A docs/demo.svg rendering of this output also ships in the repo.

Install

# 1. Clone
git clone https://github.com/techdevfun/skill-audit.git
cd skill-audit

# 2. No dependencies to install (Python 3.9+ stdlib only).
#    Optional: install the `skill-audit` command
pip install -e .

# 3. Audit your skills folder
PYTHONPATH=src python -m skill_audit check --path ~/.claude/skills

Quick start copied exactly from the skill-audit README. The check command also accepts --format json for scripts and dashboards.

Usage

# Clean pack — should pass
PYTHONPATH=src python -m skill_audit check --path examples/good

# Messy pack — should fail with errors
PYTHONPATH=src python -m skill_audit check --path examples/messy || true

# List what was found
PYTHONPATH=src python -m skill_audit list --path examples/good

# JSON for scripts / CI
PYTHONPATH=src python -m skill_audit check --path examples/messy --format json

Commands copied exactly from the skill-audit README ("Try it on the examples"). The list subcommand enumerates the skills found in a pack; check is the audit gate.

CI gate

- name: Audit skills pack
  run: PYTHONPATH=src python -m skill_audit check --path skills --format text

Snippet copied exactly from the skill-audit README. The repo itself runs the same checks in .github/workflows/ci.yml on Python 3.9, 3.11 and 3.12; a ready wrapper lives at examples/ci/check.sh.

What this is NOT — and where rivals beat us

skill-audit does not add a single skill to your pack — it audits what you already have. Skill packs that ship new skills complement it; this tool only answers "is my pack healthy".
It audits, it does not fix: the --fix mode (suggest a renamed duplicate, rewrite a description) is on the README roadmap, not shipped. What ships today is a report with file, line and evidence — you decide the change.
Its lane is pack health, and that lane only: duplicate names, overlapping triggers, missing metadata. It does not run your skills, it does not judge skill quality beyond the checks above, and it does not track which skills your agent actually uses (needs usage logs — roadmap, not shipped).

Source + README on GitHub → · Report an issue → · ask@techdev.fun

Limits

Overlapping descriptions are detected by token overlap (Jaccard, ≥70%) — two descriptions that mean the same thing in different words can slip under it, and two that share boilerplate wording can be flagged. Each finding shows its evidence; you decide.
Frontmatter is parsed for name, description and version only. Checking allowed-tools / permission fields for risky tool grants, and reporting skills that are never triggered, are on the README roadmap — not shipped.
skill-audit reads skill folders; it does not install, run or verify the skills' behaviour.

License

MIT — see LICENSE in the repository.

Have a say

Vote for this tool, suggest a feature, or discuss it with other operators on the community board.