AI Coding Tip 035 - Write Skill Descriptions in Three Sentences
A skill nobody finds in time is a skill you don't have.
I’m a senior software engineer loving clean code, and declarative designs. S.O.L.I.D. and agile methodologies fan.
TL;DR: Split every skill description into three sentences: when to read it, when to use it, and what it does.
Common Mistake ❌
You write a skill description as one long paragraph.
It explains everything the skill does.
You list every feature, every parameter, every edge case it handles.
That's the same way a function keeps growing, until nobody remembers its original job.
An agent scans a hundred skill descriptions to pick one.
It can't tell in a glance whether yours applies.
So it skips your skill for one with a sharper trigger.
Or it opens the whole file just to check.
That's the exact context cost progressive disclosure was invented to avoid.
Congratulations, you've reinvented the problem it was supposed to solve.
Problems Addressed 😔
- Too many skills, or overly long descriptions, degrade agent performance, since the router itself burns precious context deciding which one to open.
- A description that only states what a skill does can't rule itself out early, so every candidate stays in play too long, like a job application listing every tool you've touched instead of the one job you want.
- Two skills covering overlapping topics with similar prose become indistinguishable at a glance, and that confusion breeds mistakes: the agent picks the wrong one or asks which you meant.
- A skill you can't trigger without naming it might as well not exist, since a discoverable library's whole point is that the agent finds it on its own, not because you pointed the way.
- This is a special problem on large skill codebases with many similar names.
How to Do It 🛠️
Name the skill after the moment someone reaches for it, not the topic it covers.
Open the description with a first sentence that repeats that same trigger moment.
Write a second sentence naming the exact situation that calls for the skill.
Close with a third sentence stating what the skill does, nothing more.
Reread the three sentences, and cut one if two answer the same question.
Keep it to three sentences; a fourth is usually a hedge in disguise.
Test it cold on an agent that has never seen the skill, and see if it opens the file on its own.
Benefits 🎯
Faster routing: The agent decides to open your skill without reading its whole body first.
Fewer wrong picks: A sharp trigger sentence keeps adjacent skills from colliding on the same task.
Lower context cost: Skills that stay closed until needed leave more of the context budget for your actual code.
Easier maintenance: Three sentences are trivial to update after every model release, while a paragraph invites you to leave it stale.
Cleaner libraries: A description you can't compress to three sentences is usually a sign the skill itself does too much and should split into two.
Context 🧠
A skill acts as a router before it's a document.
Its only job is deciding whether to open the file, not explaining anything once it's open.
That trigger lives in two places: the name, and the first line of the description.
Everything after that first sentence just confirms the decision.
The same restraint applies to the rest of the skill: you shouldn't over-specify it, and you shouldn't smuggle implementation steps into the trigger.
Skills rot the same way an unpruned AGENTS.md rots.
You need to treat the description the same way: keep it durable, and regenerate it instead of patching it forever.
Why Three, Not One or Five?
One sentence collapses when to read, when to use, and what it does into a single clause, and the trigger usually gets dropped.
Five sentences drift back toward the feature-dump paragraph this tip is trying to kill.
Three is the smallest magic number that keeps those questions separate.
Prompt Reference 📝
Bad Prompt 🚫
---
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.
---
Good prompt 👉
---
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.
---
Considerations ⚠️
Three sentences is a target, not a hard limit.
A fourth sentence is fine if it adds a genuine constraint.
The rule assumes one skill per file, with one clear trigger.
A skill covering several unrelated triggers should probably split into two.
Compressing a description takes more editing time than writing five loose sentences.
Budget for a second pass instead of shipping the first draft.
The three sentences aren't the place to give the skill a voice either.
That framing belongs inside the file, not in the trigger a router only glances at.
Type 📝
[X] Semi-Automatic
Limitations ⚠️
This tip covers the description field, not the skill's body.
A tight trigger on a badly organized file still wastes tokens once the agent opens it, and it doesn't document what happens when the skill fails halfway through.
Different harnesses parse and weight descriptions differently, so a trigger tuned for one runtime may need retuning for another.
A three-sentence trigger is still prose, so it can't guarantee routing the way a scripted rule can, though it does make the prose easier for a model to act on correctly.
A skill can have a perfect trigger and still get skipped if the agent's list of available skills is too long to scan, and no amount of clever wording fixes a router that never reads that far down the list.
Tags 🏷️
- Knowledge Management
Level 🔋
[X] Intermediate
Related Tips 🔗
https://maximilianocontieri.com/ai-coding-tip-004-use-modular-skills
https://maximilianocontieri.com/ai-coding-tip-009-compact-your-context
https://maximilianocontieri.com/ai-coding-tip-013-use-progressive-disclosure
https://maximilianocontieri.com/ai-coding-tip-019-tell-the-ai-why-not-just-what
https://maximilianocontieri.com/ai-coding-tip-025-pair-every-skill-with-a-pitfalls-file
https://maximilianocontieri.com/ai-coding-tip-026-assign-a-persona-to-every-skill-definition
https://maximilianocontieri.com/ai-coding-tip-030-script-your-skills-not-your-prompts
https://maximilianocontieri.com/ai-coding-tip-034-stop-hoarding-rules-in-your-agents-md
Conclusion 🏁
A skill description isn't a summary.
It's a filter.
Give it three jobs: when to read it, when to use it, what it does.
Anything more belongs inside the file.
Anything less leaves one of those questions unanswered, right when it matters.
Nobody grades your SKILL.md on prose style.
The router grades it on speed, and it doesn't hand out partial credit.
More Information ℹ️
Agent Skills documentation, Claude Platform Docs
Also Known As 🎭
- Three-Sentence-Skill-Rule
- Skill-Trigger-Writing
- Progressive-Disclosure-Descriptions
Tools 🧰
The description field in a Claude Code SKILL.md frontmatter block is the only part an agent reads before deciding to open the file.
Whatever wisdom lives in the other 400 lines never gets a chance if that field reads like a shrug.
Disclaimer 📢
The views expressed here are my own.
I am a human who writes as best as possible for other humans.
I use AI proofreading tools to improve some texts.
Most AI detectors will flag this article as AI-generated. That's expected. It's a technical article. It has a rigid format and clear steps to follow.
That's exactly the pattern those tools are trained to catch. I've apparently been "writing like an AI" for decades, long before AI existed. This is a technical article, not a novel.
I welcome constructive criticism and dialogue.
I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.
This article is part of the AI Coding Tip series.
