{"slug": "coding-agents-your-skill-bodies-are-fine-your-descriptions-are-broken", "title": "Coding agents: Your skill bodies are fine, your descriptions are broken", "summary": "A developer known as Hash warns that AI coding agents often fail because skill descriptions are written as procedures rather than routing triggers. The developer explains that since skills load lazily, the model only sees the one-line description until a skill is triggered, so a description that contains executable steps can cause the agent to skip the skill body entirely. Hash advises testing descriptions in isolation to ensure they only answer \"should I load this skill?\" and never \"what will it do?", "body_md": "Hi friends\n\nThis is a follow-up to my post about [structuring CLAUDE.md, skills and agents](https://dev.to/hash01/how-to-structure-claudemd-skills-and-agents-2p7a). 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.\n\nSkills load lazily, that's the whole point. Until one triggers, the only thing the model can see is the one-line `description`\n\nin the frontmatter. Which means routing accuracy is bounded by how well a single sentence discriminates between neighboring skills.\n\nYou 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.\n\nTwo failure modes to check for.\n\n```\n# BAD - the description IS a procedure\ndescription: Verifies finished work by running tests, checking the diff\n  for weakened assertions, and reporting pass/fail\n```\n\nThe 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\").\n\nThe skill \"fired\", but the one check that mattered didn't happen. And it looks like success in your logs.\n\n```\n# GOOD - trigger only, zero procedure\ndescription: Use when a refactor or bugfix is complete and you are about\n  to report it as done. NOT for doc-only changes.\n```\n\nNow 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.\n\n```\n# skill A\ndescription: Testing best practices for this repo\n# skill B\ndescription: Testing best practices - integration harness, DB fixtures, fake upstreams\n```\n\nBoth 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.\n\nFix it at the description level, with discriminating triggers:\n\n```\n# skill A\ndescription: Use when writing or fixing unit tests for components or pure\n  functions. NOT for endpoint or database tests.\n# skill B\ndescription: Use when testing HTTP endpoints against a real database or\n  faked upstream services (integration tests).\n```\n\nIn 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**.\n\nGive a subagent just the list of skill descriptions, nothing else, and feed it real task prompts:\n\n```\n\"Write an integration test for the orders endpoint.\"\n\"A refactor is done, wrap it up.\"\n\"Fix this flaky unit test.\"\n```\n\nAsk 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.\n\n**The description answers \"should I load this skill right now?\", never \"what will it do once loaded?\"**\n\nIf you can execute the description, it's carrying content that belongs in the body. A quick checklist for each skill:\n\nOne sentence of frontmatter is doing the routing for everything underneath it. Test it like it matters, because it does.\n\nHope that helped!\n\nHash", "url": "https://wpnews.pro/news/coding-agents-your-skill-bodies-are-fine-your-descriptions-are-broken", "canonical_source": "https://dev.to/hash01/claude-skill-description-o9n", "published_at": "2026-07-28 17:36:00+00:00", "updated_at": "2026-07-28 18:06:08.212362+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "developer-tools"], "entities": ["Hash"], "alternates": {"html": "https://wpnews.pro/news/coding-agents-your-skill-bodies-are-fine-your-descriptions-are-broken", "markdown": "https://wpnews.pro/news/coding-agents-your-skill-bodies-are-fine-your-descriptions-are-broken.md", "text": "https://wpnews.pro/news/coding-agents-your-skill-bodies-are-fine-your-descriptions-are-broken.txt", "jsonld": "https://wpnews.pro/news/coding-agents-your-skill-bodies-are-fine-your-descriptions-are-broken.jsonld"}}