Skip to main content

Your agents' skills are too long (mine were too)

• AI,Claude Code,agents,tools
Two panes side by side. Left, labeled 'before · 3,569 words', a dense wall of skill instructions. Right, labeled 'after · 1,711 words', the same skill cut in half, with an eval report underneath reading 'candidate vs source: every assertion matched — PASS' and a red line showing the deliberately-broken control run failing.
The ask skill, before and after: half the words, the same behavior — and the eval proves it.

Anthropic recently cut Claude Code’s system prompt by about 80%. In a new interview with Peter Yang, Thariq — from the Claude Code team, whose HTML post I’ve written about before — explained why: as models get smarter, they need less direction, fewer constraints, and fewer examples. He says a fuller post is coming on applying this to your own skills and system prompts.

I just went through exactly that with my own core skills — act, ask, surface, and reach. Preparing them for public release was the first time I actually read them end to end — the skills, the docs, the reference files — and they felt too long. Anthropic’s Fable prompting guide says it outright: skills written for prior models “are often too prescriptive for Claude Fable 5 and can degrade output quality.”

The bloat had a clear source. Agents write my skills and prompts (as they should) — but agents also reviewed these, and gave feedback after using them, and addressing all of that made them longer every time. Every line looked like it was there for a reason, because it was; that’s how it got there. The result felt unnecessary, and honestly a little embarrassing to ship. But I didn’t want to just start cutting: without evals, a cut that breaks something slips by unnoticed — and for skills I was releasing publicly (and am now writing about), I wanted the cuts backed by data.

So I worked with my agents to build skillmin, a skill minimizer that proves every cut safe with an eval. (Its instructions to itself include: The thesis of this tool is minimalism. If a step below starts to feel baroque, stop and flag it rather than building it out.)

How it works:

  • One agent writes an eval against the original skill and freezes it — prompts, assertions, and deterministic checks on real outputs (did the commit carry the marker, did the tracker mutate, is the wire format intact). None of my skills had evals before this — the agents wrote those too, which takes away most of the excuse for not having them.
  • A second agent — which never sees the eval — cuts the skill as hard as it can, keeping exact commands, flags, and formats unchanged.
  • The frozen eval then runs original and candidate side by side, several runs each, and the cut only lands if the candidate is behaviorally indistinguishable from the source.

(Each eval also had to prove it could fail — we’d break the skill on purpose and confirm the eval catches it. An eval that can’t detect a real break certifies nothing.)

The results: ask’s always-on body went from 3,569 words to 1,711 (−52%), reach’s from 4,419 to 2,713 (−39%), surface’s from 3,411 to 2,220 (−35%). act only dropped 19% — we’d already trimmed a lot of fat preparing it for its public release. Every cut certified against the original with no change in behavior the evals could detect.

One finding I suspect holds for plenty of skills in the wild: on numerous occasions, removing a line the minimizing agent expected to matter changed nothing — even lines we deliberately cut trying to make the skill fail. The models just figure it out and do the right thing. skillmin’s instructions ask it outright before breaking anything on purpose — would a competent model produce this behavior without the instruction? — and that’s a test you can run over any line of any skill, no tooling required. You can likely cut more than you think.

The skills are model-agnostic — whatever model I’m running picks up the same files — and the reduced versions have held up everywhere: the eval runs that certified them mostly executed on Sonnet, and Fable and Opus have been driving them daily since, with no regressions. All four reduced skills are released — they’re what a fresh install of act, ask, surface, or reach gets you today.

Minimizing skills saves tokens on every trigger — and removes instructions the model would have been better off without. I’m interested to see Thariq’s post on how Anthropic approaches it. skillmin itself is released as source — deliberately not as an installable. Parts of any tool like this are specific to one machine: where your skills live, how they ship, what eval machinery your harness has. So rather than packaging around that, the release is the files themselves — hand them to your agent and have it adapt them to your setup.

This post was drafted with the assistance of AI.