My Claude skill registry had 89 custom skills. I use them for Chrome extensions, a WordPress site, desktop tools, and court e-filing automation at the legal process serving firm I work at. Last week I merged them into 38.
This post is about the reasoning behind it. The goal was two things at once: spend less on every turn, and lose no ability. Those pull in opposite directions, and how they pulled shaped the whole design.
What is the difference between efficacy and capability?
Capability is what the system can do. Efficacy is how much it costs to get it done, and how often it gets done right.
With AI skills, the two trade against each other in one specific place. Every skill's description sits in the prompt on every turn, so the model knows the skill exists. Each description is a small, permanent tax. Delete a skill and the tax goes down, but so does capability. Keep everything and capability stays, but the tax grows with every skill you add.
I wanted the tax down and the capability untouched.
Why didn't my last cleanup help?
In August I cut the registry from 107 skills to 80. The always-on description text dropped 16%, less than the 20.6% I projected. More importantly, routing did not get better, and nothing in my failure log had been caused by the number of skills.
That was the useful result. It told me what the problem was not.
What was actually causing repeat failures?
When I went through the failure log, the recurring problems were contracts split across files:
- A state board named one skill as a writer, and that skill's own file never mentioned the board, so the field never got written.
- A pre-ship gate's check count appeared in three files with three different numbers.
- Skill pairs that had to be installed together were uploaded one half at a time, and the installed half pointed at a partner that did not exist yet.
Cutting skills fixes none of that. Putting both halves of each contract in one file does.
Why merge instead of delete?
Merging keeps capability intact and removes the seams.
Each merged skill holds the full, unedited text of every skill it absorbed, split into named modes. You call it by skill and mode, for example verify:claim or verify:instrument, and the model reads only that mode's section. Nothing was paraphrased or summarised away.
The boundaries came from the failure log, not from tidiness:
- The state board and the loop that writes it became one skill.
- The pre-ship gate and its extension checks became one skill, so the check count exists in one place.
- Claim verification and the rule that measuring tools must first prove they can fail became one skill. As a separate skill, that second rule had missed nine chances in a row to fire.
The final shape is 31 merged skills, 7 standalone skills, and 107 modes, under a hard cap of 50.
How does the router still find everything?
The router skill carries a map of all 38 skills, their modes and what each is for. It deliberately leaves out version numbers, because an embedded list with versions had drifted out of date once before.
It also carries a table of all 80 old names, so anything typed from habit still lands on the right mode. A patch waiting to be installed also routes 31 platform and vendor skills that had no route at all, with a note on which custom skill each must not displace.
What happened to my instructions file?
My standing instructions to Claude load on every turn too, so they got the same treatment. Any rule a skill already enforces moved into that skill and out of the instructions. The rewrite takes it from 6,837 characters to 3,881.
What stayed are the rules that have to apply before any skill loads:
- how to state evidence
- the three terminal states every piece of work must end in
- the rule for async handlers
- the requirement that install state be checked against two sources
There is a trade-off here. A rule that lives only in a skill fires only when that skill loads. So I kept the rules whose whole job is to catch me before anything else runs.
Did it work?
On what I set out to change, yes. Per-turn skill descriptions dropped from 70,918 characters to 33,962, a 52% cut. Every cross-file contract that caused repeat failures now sits in one file. Every skill and every mode token is routed.
The cost moved rather than vanished. Six merged skills are over 80 KB and load whole when they fire, so splitting them per mode is next. Confirming the installed versions still needs one more check in a fresh session, and 64 old section references that were broken before the merge are still broken.
What would I tell someone doing the same?
Measure what is actually failing before you trim. Count is easy to reduce, and it was not my problem.
Merge along the lines where your failures cross files. Keep the original text whole inside modes instead of rewriting it.
Build the checks before the change, and break each one on purpose before you trust it. Two of mine had blind spots I only found that way.
