Three-sentence skill descriptions cut AI agent routing errors
If you’re building with Claude Code and your agent keeps picking the wrong skill, the problem is probably in the description field of your SKILL.md file, not in the skill itself.
Software engineer Maxi Contieri, author of Clean Code Cookbook at O’Reilly, published a concrete fix: split every skill description into exactly three sentences. Sentence one covers when to read it. Sentence two names the exact situation that calls for it. Sentence three states what the skill does, nothing more.
Why the description field is the whole game
An agent scanning a library of skills reads the description field before deciding whether to open the full file. A bloated description that lists every feature forces the agent to read the whole thing just to decide if it’s relevant. That burns context budget on routing before a single line of actual work runs.
Contieri’s framing: a skill description isn’t a summary, it’s a filter. Its only job is getting the agent to open the right file at the right moment.
What goes wrong with long descriptions
The failure modes are predictable. Two skills with similar feature-dump prose become indistinguishable to the router, and the agent either picks the wrong one or stalls asking for clarification. A description that only explains what a skill does without stating when to use it keeps every candidate skill in play too long. In large skill codebases with many similarly named files, the problem compounds fast.
The three-sentence pattern in practice
Contieri provides a direct before and after. The bloated version:
---
name: pdf-toolkit
description: >
This skill handles PDF work.
It generates new PDF files from templates.
It merges multiple PDFs into one document.
It adds text or image watermarks to any page.
It extracts text or images from existing files.
It converts pages to PNG or JPEG.
It splits a file by page range.
It rebuilds a file's bookmark structure after edits.
---The tighter version:
---
name: pdf-toolkit
description: >
Read this when a task touches an existing PDF file on disk.
Use it to merge, split, watermark, or extract PDF content.
It saves you from hand-rolling a PDF library call each time.
It wraps the library behind one consistent interface.
---The second version answers when to read it, when to use it, and what it does. The first version answers none of those questions at routing time.
The practical limits of this approach
Contieri is clear on what this tip does not cover. A tight three-sentence trigger on a badly organized skill file still wastes tokens once the agent opens it. Different agent runtimes parse and weight the description field differently, so a trigger tuned for one harness may need adjustment for another. And if the agent’s skill list is simply too long to scan in full, no amount of sharp wording fixes a router that never reaches your skill in the list.
Three sentences is also a target, not a hard rule. A fourth sentence is fine when it adds a genuine constraint. But a description you can’t compress to three sentences usually signals the skill itself covers too many unrelated triggers and should be split into two separate skills.
I’m founder of BizStack at Cagri Sarigoz LLC and a passionate advocate for entrepreneurs.
With over 14 years in tech, marketing, and AI, including my role as Head of SEO at CitizenShipper and co-founder of TaleBot at Intale AI, I’m dedicated to sharing genuine, useful product insights and tips.
At BizStack, I aim to cut through the digital noise to provide clear, actionable advice.
And more than all else, I’m a father to a (always) little girl and a husband.
Contact me at [email protected] for assistance.
