Writing a skill worth keeping

A skill that never fires produces no error. It sits in the folder, your tool does the thing badly the way it always did, and you conclude skills do not work. So the order of difficulty is not what people expect. Getting it to trigger is the hard part. Writing good content is the easy part, and most of the advice you will read is about the easy part.

The description is the whole trigger

Your tool holds the description of every installed skill in context at all times. It does not hold the bodies. When you ask for something, it matches your request against those descriptions, and only then reads the one it picked. That has two consequences, and they pull in opposite directions. The description has to be specific enough to match, and short enough that carrying it costs nothing. The body can be as long as it needs to be, because it is only paid for when used.

The test is mechanical. Take the last three things you typed that should have triggered the skill, and ask whether the description obviously matches them. If you have to argue for it, your tool will not make the leap either. Include the words people get wrong on purpose. If your team says "ship it" and means deploy, put both in.

What goes in the body

The useful content is whatever your tool would otherwise get wrong, and only that. It already knows how SQL works, what a migration is, and general good practice. Writing that down costs you context and earns nothing. What it does not know is that your migrations have to grant table privileges explicitly, or that this codebase puts queries in one layer and never calls the database from a component. The heuristic: if a competent stranger would get it right without being told, cut it.

Skill, instructions file, or nothing

Three places a rule can live, and the choice is about when it is relevant, not how important it is. Always relevant → your instructions file. Build commands, project layout, the conventions that apply to everything. It loads every session, which is right for things that always apply and wasteful for things that rarely do. Sometimes relevant → a skill. Release checklists, how to write a migration, the review you do before touching payments. Costs a line of description when idle. Once → just say it. Not everything needs to be a file. A rule you wrote for a situation that happened once is a rule you will be confused by later.

Test it like a change, not like a document

Two questions, in order, and the first one is the one people skip. Does it fire? Start a fresh session, phrase a request the way you normally would, and see whether it picks the skill up without being told to. If you have to name the skill, the description is wrong — asking for it by name proves nothing except that the file exists. Does it change the answer? Run the same request with the skill and without. If the output is the same, the skill is telling your tool something it already knew.

The second prompt is uncomfortable and worth running. Most skills are twice as long as they need to be, and the extra half is the part being paid for on every use.

Keeping them

Skills rot the way documentation rots, with one difference: nobody reads them, so nobody notices. The moment to update one is when you correct your tool on something the skill was supposed to cover. That correction is the signal. It means the skill fired and was wrong, or did not fire and should have, and both are fixable in the minute you have just spent being annoyed.

• Skills: teaching your tool your way of working
• Browse skills
• Global or project: where config lives
• AGENTS.md: a README for your coding agent