Write a skill description your agent actually uses

You wrote a skill, the description reads well, and the agent still does something else. Nothing errors and nothing logs, which is what makes this hard to chase: the skill simply never loads, and you find out because the work came back wrong.

The description is usually why. Here is what to put in it, and how to check it against real prompts before you rely on it.

What the description is up against

Your agent loads one skill out of everything installed, and the description is the only text it reads when it decides. It reads yours next to every other installed skill description at the same moment, then picks one.

The description is the description: line in your skill's SKILL.md front matter, sitting next to its name. Those two lines are what the agent sees. The body it does not open until after it has already chosen.

So that choice is a competition, and it is settled before a word of your body is read.

Which gives the description one reader that matters: the agent making the pick. Write it for that reader first. A description written for a person explains what the skill is. A description written for an agent gives it something to match a prompt against. Those are different sentences, and only one of them gets your skill used.

5 rules for a good skill description

Write the situation, not the capability. The agent is matching a user's prompt against your description, so a description that explains what the skill is leaves it nothing to match on. "Guidance for distinctive visual design" describes a skill. "redesign our homepage, it feels generic" is what somebody types at 4pm. Write the second kind: the situations a person is in when they need this, phrased the way they would phrase it.

Use the words a person actually types. Open your description, then open the last 5 prompts you sent your agent. If none of the vocabulary overlaps, the skill will not fire, however accurate the description is. This one catches careful writers, because the more precisely you name something in your own domain language, the further you drift from what a user types. Nobody asks for "aesthetic direction." They say the page looks generic.

Name every capability you want reachable. Because the body is only opened after the decision, a capability documented there but missing from the description is invisible to anyone who does not already know to ask for that skill by name. Every section of your skill needs a matching claim up top, in the words someone would use to ask for it.

Get specific where a neighbor overlaps you. When 2 skills cover the same ground they compete for every prompt in it, and the more specific claim wins. If a neighbor's description says "UX copy, error states" and yours says "interface work," those prompts go to the neighbor and nothing tells you. Name your ground in nouns: "empty states," "load sequences," "button labels." To find out who you are up against, open the directory your tool loads skills from (~/.claude/skills for Claude Code, ~/.agents/skills for Codex, ~/.cursor/skills for Cursor) and read the description: line of every skill in it. Expect to win some of that ground back rather than all of it, since the other skill is still making its claim too.

Keep it readable. Write about the skill rather than as it ("Gives a page a distinctive visual direction," not "I will help you design"), and stay under 1024 characters. Naming your capabilities in plain phrases is not keyword stuffing; a comma-separated heap of search terms is. The agent is the reader that decides, but a person reads this text too when they are choosing what to install.

What that looks like on a real skill

Here is a well-written skill that breaks the third rule, and what it costs. The frontend-design skill in anthropics/skills, as of July 2026, ships this description:

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

It reads well. Its body also has a full section on interface copy, down to specific advice on button labels: write "Save changes" instead of "Submit." None of that reaches the description, which never mentions copy at all. Ask this skill to fix your button labels and it does not trigger, because nothing in the text it was matched on suggests it handles them.

Here is the same skill after one tuning pass, with the description changed and nothing else:

Gives a page or UI a distinctive visual and verbal direction: palette, typography, layout, hero and section composition, motion and load sequences, and the interface copy on buttons, empty states, and error messages. Use when building new UI or reshaping existing UI that reads as templated or AI-generated, when choosing fonts or colors, when a hero or landing page needs a stronger idea, or when button labels and empty-state text need rewriting.

Both versions were tested the same way: 14 prompts the description had never been tuned against, half of them work the skill should take and half it should leave alone, run 3 times each, with a second design skill installed alongside it throughout. Out of those 42 decisions the original got 26 right. The rewrite got 34.

The gap is not subtle. Three things the skill can do never appeared in the text the agent was matching on:

Those 3 are the prompts it lost every run. Typography and the templated-look framing were named in the old description already, and those prompts kept landing.

The second description is the uglier sentence. It is also the one that gets used.

Tune your description against real prompts

Rereading your own description tells you almost nothing, because what decides is how it reads beside every other one installed. You have to put prompts through it and watch where they land.

Goodeye keeps your skills in one place and has a command for exactly this. Ask your agent to run it against the skill you are working on:

goodeye skills optimize-description my-skill

What the command returns is a set of instructions your agent then carries out, so the work happens in your own session rather than on somebody's server. Your agent:

• writes a batch of test prompts, some that should load the skill and some near-misses that should not
• takes the right answers from your skill body instead of the description being tested, so a vague description cannot quietly set its own pass mark
• judges each prompt without seeing those answers

It comes back with a row per prompt showing which skill actually loaded. The wrong rows are the edit list: each one names ground you failed to claim, or claimed too broadly. Your agent proposes a rewrite from that, tests it again, and repeats. Nothing but the description changes, and nothing saves until you approve it. Details are in optimizing a trigger description.

One thing to give it yourself: the near-misses it writes come from your own skills, which catches you competing with yourself. It cannot know about the skill a teammate installed last week, and that is often the one costing you prompts, so name that one for it.

Before you publish your skill

Answer these against your own description. Anything you answer no to is your next edit.

• Does your description share vocabulary with the last 5 prompts you actually typed?
• Is every capability in the body named in the description, in the words a person would use for it?
• Which installed skills overlap yours, and have you named your ground more specifically than they name theirs?
• Has your agent tested it against real prompts, with the neighboring skills in the room, and shown you where they landed?

If the skill also has to run the same way for everyone on your team, write an AI agent skill your team can rely on covers getting it onto their machines and keeping it current.