Claude Code skills, and when they beat a prompt

This research library uses AI-assisted source research and drafting. Linked sources support product claims; analysis and proposed exercises are our interpretation. Unless an article documents a test and its results, do not read it as a hands-on review or an independently verified benchmark.

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. If a project file mixes durable conventions with long deploy or release procedures, try moving one procedure into a skill. Compare its activation and task outcome with the previous setup; do not assume a shorter memory file automatically improves compliance.

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". A vague description can make the intended activation harder to recognize.

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. For an enforced check, use a supported hook, permission control or CI gate and test its failure behavior and alternate action paths. A hook that runs after an action cannot prevent that action.

They also drift silently. Nothing tells you when a skill describes a command that no longer exists. A deploy skill can still reference a deleted script unless someone runs its procedure after relevant repository changes.

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.