Claude Code Skills Have Changed: Build Short Files That Point.

Claude Code skills have changed shape. A skill used to be one long file of instructions. A good one now is a short file that points to the detail, with tight scripts for the steps that break and loose guidance for the calls that need judgement.

We checked 1,311 of our own skills against that standard. 229 failed a rule a script can test. Here is what changed, the five rules, and the one thing to do next.

---

How Claude Code skills used to be built

One file. Everything in it.

You wrote a SKILL.md, put the whole method inside, and kept adding. A new edge case got a paragraph. A mistake got a rule. The file only ever grew.

It felt safe. More instructions should mean fewer mistakes.

The trouble is where those lines go. When a skill fires, the whole body of that file lands in the same window as your chat and your request. Anthropic's guide puts it in one line: "The context window is a public good." A long skill crowds out the work it was written to help with.

If skills are new to you, start with what a Claude skill is and come back.

---

What changed: a short file that points

Skills load in stages. Anthropic calls it progressive disclosure, and laid it out when it introduced Agent Skills in October 2025.

1. At startup, Claude sees only the name and description of each skill.
2. When the skill is relevant, it reads the body of SKILL.md.
3. When the job needs it, it opens the extra files that SKILL.md points to.

That third stage is the one that changes how you build. A reference file costs nothing until Claude opens it. So the detail can wait.

The job of SKILL.md is now different. It says what the skill is for and where the detail lives. Everything else sits in a reference file until the task calls for it. The Agent Skills overview covers the loading model, and the Claude Code skills docs cover where the folders go.

---

Claude skills best practices: the five rules in brief

All five come from Anthropic's skill authoring best practices. Read the full page. It is the source.

Rule	The test
Size	Is the body of SKILL.md under 500 lines?
One level deep	Is every reference file linked straight from SKILL.md?
Contents list	Does every reference file over 100 lines open with a list of its sections?
Degrees of freedom	Are fragile steps exact scripts, and judgement calls given room?
Dead weight	Does every line tell Claude something it did not already know?

The first three are counting jobs. A script can check them. The last two need someone to read the skill and think about what it is for.

One level deep catches people out. If a reference file links to another reference file, Claude may only preview the second one and miss half of it. And a reference file that SKILL.md never mentions is never read at all.

---

Tight scripts for fragile steps, loose guidance for judgement

This is the rule most people get half right.

Anthropic's picture is a narrow bridge against an open field. On the bridge there is one safe way across, so you give exact instructions. A deploy or a database migration is a bridge. In the field there are many good routes, so you give direction and trust the model. Writing and review are a field.

Most audits only look for skills that are too loose. Ours found both kinds.

• 238 fragile steps written as loose prose where a script should be.
• 17 judgement calls locked into rigid steps.

The second kind is rarer, and it is easy to miss because a rigid step list looks careful. Hand a writing task a rigid checklist and you get writing that reads like a checklist.

---

What we found when we checked our own

We ran the audit across a large, real stack. These are the numbers.

Measure	Result
Skill folders on disk	17,538
Real skills, once copies were removed	1,311
Failed a rule a script can test	229
Skill files over 500 lines	62
Reference files the skill never mentions	44
Skills read for the judgement rules	561
Passed clean / small trims / needs rework	189 / 313 / 59

One caveat. The judgement pass had one reviewer per skill and no second check, so treat the last two rows as a strong first read. It also flagged about 13,900 lines as removable. That figure is an estimate.

Two things stood out.

Copies hide the real count. 17,538 folders turned out to be 1,311 skills. One skill copied 70 times shows up as 70 failures. Find the copy the others came from, fix that one, then push it back out.

The safe fix is dull. One skill ran to 1,207 lines. It now runs to 494. Nine sections moved into reference files and the wording did not change. Move the text word for word, leave a pointer, and save the editing for another day. Tidy up while you move and a rule goes missing without anyone noticing.

---

Why this matters if you run the business, not the code

Skills are where your method lives.

I map an AI setup to a body. Wikis are the brain. Skills are the muscle. Routines are the heartbeat. The meeting wiki build walks through all three. When the muscle carries dead weight, everything it does gets slower and sloppier.

Here is what a skill is worth when it works. One weekly cohort report took up to four hours by hand. Built as a skill, the same report ran in 22 minutes.

It is also why a pack of 50 skills bought off the internet lets you down. They were not built for your business. The lines that matter in a skill are the ones only you could write: your names, your thresholds, your house rules. Those stay. The audit removes the rest.

The same discipline applies to the other files Claude reads. Njin's guide to writing a CLAUDE.md for your sales method covers the file that sits above your skills. If Claude Code itself is new to you, DevWiz has a complete guide to Claude Code. And once you run skills across more than one project, build your own AI stack shows how to keep track of them.

---

The one next step: audit your skills

Do not rewrite anything yet. Check first.

We turned the whole audit into a guide. It takes the five rules and gives each one a test. It explains the two passes, a script for the counting and a read for the judgement. It lists the eight traps we hit. And it ends with one prompt you paste into Claude or Codex, which changes nothing until you approve the table it hands back.

Run the Claude skills audit.