Hi friends
This is a follow-up to my post about structuring CLAUDE.md, skills and agents. A comment on that post pointed at a failure layer I had completely skipped, and it deserves its own write-up: your skill bodies can be perfect and the agent still never reads them.
Skills load lazily, that's the whole point. Until one triggers, the only thing the model can see is the one-line description
in the frontmatter. Which means routing accuracy is bounded by how well a single sentence discriminates between neighboring skills.
You can audit every body, verify every code example against the codebase, run retrieval tests on the content... and none of it matters if the model picks the wrong skill, or no skill, or decides the sentence already told it everything it needs.
Two failure modes to check for.
description: Verifies finished work by running tests, checking the diff
for weakened assertions, and reporting pass/fail
The model reads that sentence, feels it already knows the procedure, and executes a shallow version from memory: run tests, glance at diff, report. It never opens the body, where the actual teeth live ("diff each changed assertion against the base branch; a widened tolerance counts as failure").
The skill "fired", but the one check that mattered didn't happen. And it looks like success in your logs.
description: Use when a refactor or bugfix is complete and you are about
to report it as done. NOT for doc-only changes.
Now the sentence contains nothing executable, so the model has to read the body to know what to do. The description's only job is routing.
description: Testing best practices for this repo
description: Testing best practices - integration harness, DB fixtures, fake upstreams
Both start with the same phrase. Every testing task matches A first, and the deeper B never loads. Here's the trap: rewriting the bodies changes nothing, the model never gets past the sentence. You can polish skill B forever and it stays invisible.
Fix it at the description level, with discriminating triggers:
description: Use when writing or fixing unit tests for components or pure
functions. NOT for endpoint or database tests.
description: Use when testing HTTP endpoints against a real database or
faked upstream services (integration tests).
In the previous post I ran retrieval tests against doc bodies: give a subagent only the docs, no repo access, make it answer implementation questions, grade against the codebase. The extension: run a second version against the descriptions alone.
Give a subagent just the list of skill descriptions, nothing else, and feed it real task prompts:
"Write an integration test for the orders endpoint."
"A refactor is done, wrap it up."
"Fix this flaky unit test."
Ask one question: which skill would you load, and why? Grade the routing. If the wrong skill wins, or none triggers, or the model says "no need to load anything, the description tells me what to do" - your descriptions failed the test. Fix the sentences, not the bodies.
The description answers "should I load this skill right now?", never "what will it do once loaded?"
If you can execute the description, it's carrying content that belongs in the body. A quick checklist for each skill:
One sentence of frontmatter is doing the routing for everything underneath it. Test it like it matters, because it does.
Hope that helped!
Hash