For operators whose skills folder has grown faster than anyone has checked it.
Audit Your Claude Skills
With One Prompt
Skills pile up, get long, then quietly stop working well. No error, no warning, just worse answers each month. Here are the five rules a skill must pass, the traps we hit, and one prompt that runs the audit.
Five rules, one test each
Know in a minute whether a skill passes
Eight traps to skip
Found the hard way, on 1,311 real skills
One prompt to run it
Paste it into Claude or Codex and read the table
That is how it starts. The rest makes more sense once you know the rules it checks.
The Rules
Claude Skills Best Practices: The Five Rules To Test
Size, one level deep, a Contents list, degrees of freedom and dead weight. Each one comes with a test you can run today.
These rules come from Anthropic's skill authoring best practices, the page the people who built skills wrote on how to build them. We turned five of them into checks you can run, because a rule you cannot test is a rule nobody follows.
Size
Keep the body of SKILL.md under 500 lines.
Test. Count the lines after the frontmatter. Over 500 is a fail.
Why. Once a skill fires, every line in it sits in the same window as your chat and your request. A long skill crowds out the work it was written to help with.
One level deep
Every reference file is linked straight from SKILL.md.
Test. Does any reference file link to another reference file? Is any reference file never mentioned at all?
Why. Claude may only preview a file it reaches second hand, reading the top and moving on. Detail two hops away gets half read. Detail with no link is never read.
Contents list
Any reference file over 100 lines opens with a short list of its sections.
Test. Open each long reference file. Is there a Contents list before the first section?
Why. When Claude only previews the top of a file, the list is how it learns what else is in there and whether to keep reading.
Degrees of freedom
Match how tightly you write a step to how easily that step breaks.
Test. Is a fragile step, like a deploy or a migration, an exact script? Is a judgement call, like writing or review, given room and reasons?
Why. Anthropic's picture is a narrow bridge against an open field. On the bridge there is one safe path, so spell it out. In the field, rigid steps only make the answer worse.
Dead weight
Only write down what Claude does not already know.
Test. For each paragraph, ask whether Claude would get it wrong without it. If not, it goes.
Why. The model is already smart. Explaining what a PDF is, or how to write clearly, spends your window on nothing. Your names, paths, thresholds and house rules are the opposite. Keep every one.
What changed: a skill used to be one long file. Now it is a short file that points.
The short file says what the skill is for and where the detail lives. Fragile steps get a tight script. Judgement calls get loose guidance and the reasons behind it. Everything else waits in a reference file until the job needs it, and costs nothing until then.
The Method
One Pass For A Script, One For A Reader
Some of this is counting and some of it is judgement. Mix the two and you get a report nobody trusts.
We ran this audit on a large, real stack. The first thing it taught us is that the check is two different jobs. One is counting. The other is reading.
17,538
skill folders on disk
1,311
real skills, once copies were removed
229
failed a rule a script can check
Pass 1. Mechanical
A script does itSize. One level deep. Contents list.
These are counting jobs. A script counts every file the same way and is exactly as careful on skill 1,300 as on skill one. Ask a model to eyeball a line count and you get a guess.
- 62 skill files over 500 lines
- 39 reference files linking to another reference file
- 176 long reference files with no Contents list
- 44 reference files the skill never mentions
Pass 2. Judgement
Each skill gets readDegrees of freedom. Dead weight. Wiring.
No script can tell you whether a step is fragile, or whether a paragraph tells Claude something it already knew. Something has to read the skill and think about what it is for.
- 639 dead weight findings
- 238 fragile steps left as loose prose
- 17 judgement calls locked too tight
- About 13,900 lines flagged as removable (estimated)
561 skills read in the judgement pass
One caveat, said plainly. The judgement pass had one reviewer per skill and no second check. Treat those figures as a strong first read, not a measurement.
Run the script first. It tells you where to read.
The mechanical pass is fast and cannot be argued with. It also shrinks the pile. Once you know which skills are too long or badly linked, the slow reading goes to the ones that need it. The traps in the next section are what that reading turned up.
Enjoying the guide?
Enter your details to unlock the remaining insights. We'll also send you the complete guide as a reference.
What We Learned
Eight Traps Nobody Warns You About
From running the audit on 1,311 real skills. Each one is built into the prompt, so it does not cost you what it cost us.
The rules are public. What follows is not written down anywhere we could find. Each of these cost us time on the real audit, and each one is now built into the prompt at the end so it does not cost you any.
Copies hide the real count
17,538 folders, 1,311 skillsWhat happens. One skill copied 70 times shows up as 70 failures. The report looks like a disaster and most of it is the same file.
Do this. Find the source copy. Audit that one, fix it once, then redeploy the copies.
Freedom fails in both directions
238 too loose, 17 too tightWhat happens. A deploy written as loose prose is one failure. A writing or strategy task locked into rigid steps is the other. Most audits only look for the first.
Do this. Check both. Script the fragile steps. Give the judgement calls room and reasons.
A Contents list can break a file
Skip templates and promptsWhat happens. Add a Contents list to an output template or a prompt file and it ends up in whatever that file produces.
Do this. Leave out output templates, prompt files and anything with its own frontmatter.
Orphan reference files
44 files never mentionedWhat happens. One level deep has a second half. A reference file the skill never links to is never read. It looks like knowledge and does nothing.
Do this. Link it from SKILL.md with a line on when to read it, or delete it.
Dead weight repeats itself
639 findingsWhat happens. The two most common cases: a when to use section that repeats the description, and an anti-patterns list that repeats rules stated above it.
Do this. Say it once, in the place Claude reads first.
Rewriting while moving loses things
Move first, edit laterWhat happens. Split a long skill and tidy the wording in the same step, and a rule quietly goes missing. Nobody notices until the skill misbehaves.
Do this. Move the text word for word and leave a pointer. Edit afterwards, as its own step.
A good skill nobody is told about never fires
Check the wiringWhat happens. You can build a skill well and still have it sit unused, because no agent or command says when to reach for it.
Do this. Every agent or command that should use it needs a line saying when and how.
Do not edit third-party skills
Report onlyWhat happens. Fix a plugin skill by hand and the next update overwrites your work.
Do this. Report them. Do not fix them.
The one most audits miss: locking a skill too tight is a real failure.
It showed up 17 times against 238 for the loose kind, so it is the rarer problem. It is also the one nobody checks for, because a rigid step list looks careful. Hand a writing task a rigid checklist and you get writing that reads like a checklist.
The Fix
Move It Word For Word
A tidy-up that drops one rule leaves you with a shorter skill that is worse. The safe fix is deliberately boring.
Finding the problems is the easy half. Fixing them is where a careful audit can do real damage, because a tidy-up that drops one rule leaves you with a shorter skill that is worse. So the fix is dull on purpose.
Move the text word for word
Cut the section out of SKILL.md and paste it into a new reference file. Change nothing. Not a comma.
Leave a pointer behind
Keep the section heading in SKILL.md with one line saying when to read the reference file. If the skill depends on it, say it is mandatory.
Fix the source copy only
If the skill lives in 70 places, 69 of them are copies. Fix the one they were copied from.
Redeploy the copies
Push the fixed source back out, then compare the line counts before and after so you can see what moved.
Two real skills, before and after
Nine sections moved into reference files. Wording unchanged.
Long code samples moved into reference files.
The thin line marks 500. Both skills now sit under it, and neither lost a word.
What a pointer looks like
The heading stays so the skill still reads as a whole. The line under it tells Claude when to open the file. This is an example of the shape, not a file from our stack.
Deploying to production Read references/deploy.md before any deploy. Mandatory. It holds the exact commands and the rollback steps. Writing the release note Read references/release-notes.md when the change is user facing.
Moving and editing are two jobs. Keep them apart.
A move you can check: the words are the same and the line counts add up. An edit you have to judge. Do both at once and you cannot tell whether a rule went missing in the move or was cut on purpose. Trim the dead weight later, as its own pass, with the before and after side by side.
The Prompt
The Whole Audit, In One Prompt
Paste it into Claude or Codex. It reads the rules, writes its own script, and hands you one table of what to fix.
Everything above is in here: the five rules, the two passes, the traps and the safe way to fix. It names no tool of ours and no person, so it works on any stack. Copy it as it is.
How to run it
Open Claude Code or Codex in the project whose skills you want checked.
Paste the prompt. It reads Anthropic's guide first, then writes its own script for the counting.
Read the table. Nothing changes until you approve it, and passing skills come back as one number.
The skill audit prompt
Read Anthropic's skill authoring best practices first:
https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
Then audit every skill I have installed: ~/.claude/skills, this project's
.claude/skills, and any plugin skills.
Before you check anything:
- If the same skill exists in several places, find the source copy and audit
that one. Report the copies as a count, not as separate rows.
- Mark third-party and plugin skills as "report only". Never plan edits to them.
Pass 1, mechanical. Write a script for this, do not eyeball it.
1. Size: is the SKILL.md body (after the frontmatter) under 500 lines?
2. One level deep: is every reference file linked straight from SKILL.md?
Flag any reference file that links to another reference file, and any
reference file SKILL.md never mentions.
3. Contents list: does every reference file over 100 lines open with a short
Contents list of its sections? Skip output templates, prompt files and
anything with its own frontmatter. A Contents list would break those.
Pass 2, judgement. Read each skill for this.
4. Degrees of freedom, both directions:
- Too loose: fragile steps (deploys, migrations, API calls, file formats,
destructive commands) described in prose instead of an exact script, or a
repeatable output with no template.
- Too tight: judgement calls (writing, review, design, strategy) locked into
rigid step lists or rules with no reasoning.
5. Dead weight: lines that explain what Claude already knows. Do not flag
facts specific to my setup: names, paths, IDs, thresholds, house rules,
known gotchas.
6. Wiring: is the description specific about when to use the skill, and does
every agent or command that should call it say when and how?
Be strict about false positives. A well-built skill should pass with no findings.
Show me one table of failures only:
Skill | Source location | Copies | Rule failed | Evidence (line or section) | Fix
Give passing skills as a single count. For any skill over 500 lines, name
which sections move to which new reference file and what stays.
Don't change anything until I approve. When I do:
- Move text word for word. Do not rewrite it while moving it.
- Leave the section heading in SKILL.md with one line saying when to read the
reference file. Mark it mandatory if the skill depends on it.
- Fix the source copy only, then tell me which copies need redeploying.
- Show me the before and after line counts.What comes back
One table, failures only. A well-built skill should come back with nothing against it.
AAskillskillthatthatworksworksisishalfhalfdone.done.TheTheotherotherhalfhalfisiskeepingkeepingititshort,short,linkedlinkedproperly,properly,tighttightwherewhereitithashastotobebeandandlooseloosewherewhereititshouldshouldbe.be.RunRunthetheauditauditagainagainwheneverwheneverthethefolderfoldergrows.grows.
Jump back to a section
Want the short version to send to your team first? Read how building Claude Code skills has changed.
Read next
Primary sources