Write a SKILL.md Description Your AI Agent Actually Uses

Your agent decides whether to open a SKILL.md file in the half-second it reads the name and description, before it ever sees the steps. Most skills get ignored not because the steps are wrong, but because the description is too vague to signal relevance. This guide shows how to write frontmatter descriptions that get your skills loaded, how much to put in the name versus the description, and how to keep a skill from triggering when it should stay out of scope.

The mechanics matter more than people expect. An agent keeps each skill's name, description,and tags in context and loads the full body only when those fields match the task at hand. So the description is effectively your skill's entire advertisement; getting it wrong means the skill exists but never runs. If the file format itself is new to you,our primer on what a SKILL.md file is covers the parts of a skill before we tune the wording

State What the Skill Does and When to Use It

The winning description formula is `` when ``, what the skill executes,plus the exact situation where it belongs. A description that only lists the action, such as ``Processes invoice workflows``,gives the agent nothing to match against. The same workflow described as ``Use when an approved invoice needs to be matched, paid in the AP portal,and archived`` lets the agent recognize the task precisely and load the file with confidence

Name the concrete trigger objects and states,not abstracts. Mention the actual tool name, such as AP portal,CRM,or HRIS,and the concrete state that signals it is time, such as ``when a new lead is routed to the queue`` or ``after month-end books are locked``. The more the description resembles the phrasing your team actually uses to talk about the task,the more reliably the agent maps words to work. That pairing of a task and a concrete trigger is also what makes a skill behave like a well-scoped process rather than an unruly prompt; see why AI assistants are only as good as your SOPs for the same logic applied at the process level

Keep the Name Short,the Description Specific

Use the name for fast scanning and the description for full matching;don't cram everything into one field. Names should be short noun phrases, such as ``invoice-payment`` or ``lead-routing``,that read well in a list, while descriptions carry the detail. A common mistake is stuffing the whole procedure into the description field;that bloats the always-in-context metadataand makes every skill expensivefor the agent to keep in mind

Tags,whenthe format supports them,add a cheap retrieval layer but never a replacement for a good description. Keep tags to a handful of stable categories you can reuse across the library,such as auth, finance, support,and operations,so adjacent skills share vocabularyandthe agent can generalize. This naming-and-structure discipline mirrors what keeps a broad skill library coherent overall;the Agent Skills open standard spells out how names,descriptions,and files move together across Claude,Codex,and Cursor

Use Negative Scope to Keep a Skill Out of the Way

A skill that triggers too often is worse than one that never triggers;add explicit negative scope to restrain it. If your skill only applies to one department or one region,say so in the description,such as ``Only for the EU entity`` or ``Not for ad-hoc invoicing``. That boundary keeps the agent from loading the file for out-of-scope workand prevents overlapping skills from fighting overthe same task

Then validate empirically: run a few real tasks and check which skills the agent actually loads. A skill you expected to fire that never appears likely has a description mismatch; rewrite it toward the trigger language your team uses,not the words you would use in a doc title. Because the description is what does the matching,small wording changes can flip whether a skill loads,which is exactly why,when you build skills from recorded workflows,tuning the description matters as much as the steps themselves. Our guide to recording once and automating forever shows how to get accurate steps cheaply,andthe frontmatter is where you decide whether anyone,or any agent,actually reaches them

Rewrite Against Real Trigger Language

The most reliable way to tune a description is to watch what actually fires on real tasks,and rewrite toward the words your team really uses. Run a handful of representative jobs through your agent with the skill library active,and capture which skills load on which tasks. A skill you expected to fire but never appears is a mismatch between its description and how people actually describe that work. Pull the phrasing from your customers,and from your own chat logs and tickets,and feed it back into the description rather than guessing at formal names.

A proven tactic is to write the description the way you would ask a colleague who knows the process — the concrete name of the tool,the specific object,andthe moment the task starts — then trim until it reads like a line item your team would recognize. Keep adjacent skills from overlapping by making their negative scopes explicit,andrecheck after any workflow change;how people talk about a process shifts as tools and UI change,andstale trigger language right now will quietly stop your skills from firingin a few quarters. That is the same erosion that makes written process docs go stale,but with skills the cost is immediate:an agent that cannot match a task simply runs without the procedure,or worse, improvises with a half-loaded skill. Naming skills from recorded workflows rather than from memory keeps the description anchored in real trigger language from the start,so fewer rewrites drift in later. It is the cheapest way to keep every skill filed where an agent can actually discover it, and the whole library discoverable in the process.

FAQ: SKILL.md Descriptions

A well-named,well-described skill folder is the difference between a library that is genuinely usefuland a graveyard of files your agent never opens. Write every description as `` when ``,keep names scannable,add negative scope to stay out of the way,andvalidate by watching what fires. The steps matter,but the description is what lets anyone,human or agent,find them in the first place