Back to search
skill-listing-auditor
SkillWorks with Claude CodeGitHub
Shows which Claude Code skills your agent has quietly stopped seeing.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/divyanshtomar1610--skill-listing-auditor)HTML
<a href="/listings/divyanshtomar1610--skill-listing-auditor"><img src="/api/listings/divyanshtomar1610--skill-listing-auditor/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 111 lines
- # Skill listing auditor
- A single Python script that estimates how much of the Claude Code skill listing budget your installed skills use, and shows which skills have no usable description. Needs Python 3.9 or later; nothing to install.
- **Why I built this.** I found my own install at over 300 skills, far past the listing budget, and no built-in report showed which descriptions were being dropped. A skill with no description never matches a request. This is the check I wanted that day.
- **A real run** (my own machine, 2026-11-20): 322 listed skills, about 37,000 tokens of listing, over the 1% budget on a 200k window by about 35,000 tokens; one more skill hidden from the listing by `disable-model-invocation`, none without a description. That is the number this script exists to show you.
- ## What it is for
- Claude Code puts every skill's name and description into context so it can match a skill to what you ask. That listing has a budget that scales at 1% of the context window. When the listing goes over budget, names are kept and descriptions are dropped, starting with the skills you invoke least. A skill with no description can still be called by name, but it can no longer be matched to a request, and nothing tells you this happened.
- Two other things fail the same quiet way. Each entry is capped at 1,536 characters (`skillListingMaxDescChars`), so the tail of a long description is cut. And frontmatter is read only when `---` is the first line of `SKILL.md`: put a heading above it and the description is never read, although the file looks correct.
- This script shows the size of your listing against the budget, the skills with a broken or missing description, the entries over the cap, duplicate names, and the skills whose descriptions overlap so much that they compete for the same requests.
- ## Run it in one minute
- You need Python 3.9 or later. There is nothing to install.
- 1. Download `skill_audit.py` into the project folder you use with Claude Code.
- 2. Open a terminal in that folder. On Windows, type `python` or `py` where this page says `python3`.
- 3. Run it:
- ```bash
- python3 skill_audit.py
- ```
- It reads three places: `~/.claude/skills`, `.claude/skills` in the current folder, and the newest cached version of each plugin under `~/.claude/plugins/cache`. It only reads files. It changes nothing and sends nothing over the network.
- Other modes:
- ```bash
- python3 skill_audit.py --test "tidy up this spreadsheet and remove duplicates"
- python3 skill_audit.py --collisions
- python3 skill_audit.py --json
- python3 skill_audit.py --project /path/to/another/project
- ```
- | Option | What it does |
- |---|---|
- | (none) | Inventory by scope, budget check, health findings |
- | `--test "PROMPT"` | Ranks the skills whose name and description share words with your prompt |
- | `--collisions` | Lists pairs of skills whose descriptions overlap by 75% or more |
- | `--json` | Prints the inventory as JSON |
- | `--project PATH` | Audits the `.claude/skills` folder of another project |
- ## How to check it worked
- The default run prints a report like this one (from a test folder with five small skills; the explanatory notes and the closing `Next` hint are left out and the file path is shortened):
- ```text
- SKILL LISTING AUDIT
- ==============================================================
- Inventory by scope (listed skills only; each entry counted up to the 1536-char cap)
- personal 2 skills 309 chars ~ 77 tokens
- project 3 skills 190 chars ~ 47 tokens
- TOTAL 5 skills 499 chars ~ 124 tokens
- Budget check (listing budget = fraction x context window)
- 200k window @ 1% budget ~ 2,000 tokens OK
- 200k window @ 2% budget ~ 4,000 tokens OK
- 1M window @ 1% budget ~ 10,000 tokens OK
- 1M window @ 2% budget ~ 20,000 tokens OK
- Health
- BROKEN frontmatter : 1 <-- fix these first
- - broken-example [project]
- /path/to/project/.claude/skills/broken-example/SKILL.md
- Skills with NO description : 2
- - broken-example [project]
- - no-description [project]
- Entries over the 1536-char cap : 0
- Duplicate skill names : 0
- ```
- Check three things:
- - The skill count in `TOTAL` is close to the number of skills you expect. If it prints `No skills found`, it lists the three folders it checked.
- - The budget lines say `OK` or `OVER by ~N` for your context window size.
- - To prove the health check can find a problem, add a blank line above the `---` in one `SKILL.md`, run the script again, and confirm that skill appears under `BROKEN frontmatter`. Then undo the change.
- `--test` prints a ranked list, or `NO SKILL MATCHES` when no description contains the words in your prompt.
- ## What to do with the result
- - Broken frontmatter: move `---` to the first line of the file.
- - No description: add one that uses the words you would type when you want that skill.
- - Over the cap: shorten the description so the important words come first.
- - Over budget: remove skills you do not use, shorten descriptions, or raise `skillListingBudgetFraction` in your Claude Code settings.
- - Collisions: rewrite the two descriptions so each one names what only it does.
- ## Limits
- - The numbers are estimates. The script counts characters and divides by four to get tokens. Run `/doctor` inside Claude Code for its own estimate of the listing's cost.
- - It cannot tell you which descriptions were dropped. Claude Code drops the least-invoked skills first, and the script does not know your invocation counts. It tells you whether you are likely over budget, not who lost out.
- - It counts every `SKILL.md` it finds in the three folders above. It does not read your settings, so it cannot tell whether a skill or plugin is switched off, and it does not look in any other location.
- - The budget check assumes a 200k or a 1M context window, at 1% and 2%. Other window sizes and fractions are not shown.
- - `--test` is a word-overlap score, not the way Claude chooses a skill. Use it to find descriptions that lack your vocabulary. A high rank does not guarantee the skill is picked.
- - The frontmatter reader is a small built-in parser, not a full YAML parser. Unusual YAML may be read differently than Claude Code reads it.
- - Tested on Python 3.9 and 3.14 on macOS only.
- - The facts about the budget, the cap and the settings names were checked against the Claude Code documentation at https://code.claude.com/docs/en/skills on 2026-11-20. They can change in later versions.
- ## Credit
- The trigger-test idea is adapted from the routing eval in [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills).
- ## Licence
- MIT. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.