Claude Code skills, and when they beat a prompt

Claude Code skills are directories containing a markdown file with a name, a description, and a body of instructions. The description is the part that matters most, because that is what the model reads when deciding whether to load the rest. Everything else stays out of context until the skill is invoked. That is the whole design: procedural knowledge you pay for only when you use it.

Compare that to putting the same content in your project memory file. There it is loaded on every turn, competing for attention with the actual task. A team we worked with had a 700-line project file covering deploy steps, test conventions, and a release checklist. Three of those belonged in skills. Moving them cut the standing context by about two thirds and made the remaining rules stick better.

Where teams get skills wrong

The failure is almost always the description. Engineers write the body carefully and then describe the skill as "helps with deployments". The model never fires it, the author concludes skills do not work, and the folder sits dead in the repo for a quarter.

Write the description as a trigger list, not a summary. Name the words a person would actually type.

• Bad: "Assists with database work."
• Better: "Run a schema migration against staging or production. Use when the user says migrate, alter table, add a column, or backfill."
• Include the failure phrasing too. People type "the migration broke" more often than they type "run a migration".

The second common mistake is length. A skill that is 400 lines is a document, and the model will skim it the same way you would. Keep the body to the steps that are non-obvious, and link out to reference files inside the skill folder for detail the agent can read if it needs to.

What Claude Code skills do badly

They do not enforce anything. A skill is advice, and the model can ignore it, particularly late in a long session when the instructions are competing with a wall of tool output. If you need something to happen every time without exception, a hook is the right mechanism, because the harness runs it rather than the model choosing to.

They also drift silently. Nothing tells you when a skill describes a command that no longer exists. We have opened repos where the deploy skill referenced a script deleted eight months earlier, and the agent had been improvising around it ever since. Nobody noticed because the improvisation mostly worked.

And discovery is fuzzy. With thirty skills installed, two with overlapping descriptions, you cannot fully predict which one loads. Keep the set small and the boundaries sharp.

A skill worth writing first

Start with the task your team explains to every new joiner in person. In most codebases that is "how to add a new endpoint" or "how we run and debug the test suite". Write it as a numbered procedure with real commands:

npm run test -- --runInBand path/to/file.test.ts

Then include the two or three mistakes people actually make. That is the part general knowledge cannot supply, and it is what turns a skill from a wrapper around the model's defaults into something with your team's experience baked in.

What to do next

Take your largest project instruction file. Mark every block that only applies to one kind of task. Move the biggest one into a skill, write the description as trigger phrases, then work normally for a week and check whether it fires. If it does not, the description is wrong, not the idea. Fix it once and the pattern will be obvious for the rest.

If you want help putting this into practice, talk to us.