A skill nobody can find in time is a skill you don’t have.

A skill description is not a summary. It is a filter. Its job is to help an agent decide, in a glance, whether to open the file. Everything else belongs inside the file.

TL;DR: Write every skill description in three sentences: when to read it, when to use it, and what it does.

The common mistake

People write skill descriptions as one long paragraph. They list every feature, parameter, and edge case. The description grows the same way a function grows: until nobody remembers the original job.

An agent may scan dozens or hundreds of descriptions before picking one. If yours cannot be ruled in or out immediately, the agent skips it, opens a competing skill, or loads the whole file just to check. That burns the context budget that progressive disclosure was meant to protect. You have reinvented the problem the description was supposed to solve.

What goes wrong

• Long or numerous descriptions make routing expensive. The router spends tokens deciding which file to open.
• A description that only says what the skill does cannot exclude itself early, so every similar candidate stays in play.
• Overlapping skills written in similar prose become indistinguishable. The agent picks the wrong one or asks which you meant.
• A skill that only fires when you name it is not a library. The point of a skill list is that the agent finds the right one on its own.
• This gets worse in large skill sets with similar names.

How to write it

1. Name the skill after the moment someone reaches for it, not the topic it covers.
2. Open the description with a sentence that repeats that trigger moment.
3. Write a second sentence for the exact situation that calls for the skill.
4. Close with a third sentence that states what the skill does — nothing more.
5. Reread the three sentences. Cut one if two answer the same question.
6. Stay at three. A fourth sentence is usually a hedge.
7. Test it cold on an agent that has never seen the skill. See whether it opens the file on its own.

Why this works

• Faster routing. The agent can decide without reading the body first.
• Fewer wrong picks. A sharp trigger keeps adjacent skills from colliding.
• Lower context cost. Closed skills leave more budget for actual work.
• Easier maintenance. Three sentences stay cheap to update after model changes. A paragraph invites rot.
• Cleaner libraries. If you cannot compress the description to three sentences, the skill probably does too much and should split.

Context

A skill is a router before it is a document. Its first job is whether to open the file, not how to explain the work once open.

That trigger lives in two places: the name, and the first line of the description. Everything after the first sentence only confirms the decision.

Do not smuggle implementation steps or persona into the trigger. Those belong in the file. Descriptions rot the same way unpruned rule files rot. Keep them durable, and rewrite them instead of patching them forever.

Why three, not one or five?

One sentence collapses “when to read,” “when to use,” and “what it does.” The trigger usually dies first. Five sentences drift back into a feature dump. Three is the smallest number that keeps those questions separate.

Example

Weak

---
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.
---

Stronger

---
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 wraps the library behind one consistent interface so you do not hand-roll each call.
---

The weak version lists capabilities. The strong version answers the router’s three questions.

Caveats

Three sentences is a target, not a law. A fourth is fine if it adds a real constraint.

The rule assumes one skill per file and one clear trigger. Several unrelated triggers usually means two skills.

Compression takes more editing than a first draft. Budget a second pass.

Do not put voice or persona in the description. The router only glances at it.

This tip covers the description field, not the body. A perfect trigger on a messy file still wastes tokens once opened. Different harnesses weight descriptions differently, so you may need to retune. Prose still cannot match a scripted rule for guaranteed routing. And no wording saves a skill that never appears high enough in a list the agent actually scans.

Bottom line

Give the description three jobs: when to read it, when to use it, what it does.

Anything more belongs inside the file. Anything less leaves a question unanswered at the moment it matters.

Nobody grades SKILL.md on style. The router grades it on speed, and it does not give partial credit.