Claude Code Skills: What They Are and How to Write One

A skill is a description of a procedure that the agent picks up by itself when it meets a matching task. It is not a set of functions or a plugin: it is a plain text file explaining how a particular thing is done in your project.

What a skill is

The easy way to think about it: a skill is a written procedure for the agent.

There are things you explain to every new person on a project: how a release is cut, how a new entity is added to the data model, what else has to change when the database schema does. You explain the same things to an agent, and for the same reason - none of it is written in the code.

The difference between explaining it in chat and writing a skill is that the skill lives in the repository, is versioned with the code, and behaves the same for everyone.

What a skill consists of

The core is a description file with two parts.

A metadata header. A name and a short description of when this skill applies. That description matters more than it looks: the agent uses it to decide whether the skill is relevant to the current task. A vague description means the skill either never fires or fires everywhere.

The body - the instruction itself. What to do, in what order, what to verify at the end. Written the way you would write it for a person: concretely, with examples, with the edge cases named.

Supporting files can sit alongside it - templates, checklists, scripts - referenced from the instruction. That is convenient when the procedure involves generating similar files.

When a skill beats a prompt

Three signs it is time to move an explanation into a skill:

You are explaining it for the third time. Once is normal, twice is coincidence, three times is a procedure.
The explanation is longer than the task. If stating the problem takes more text than the result, the statement should live somewhere else.
More than one person does this. What one developer knows and another does not is the main source of drift.

And the counter-sign: if the procedure is slightly different every time and decisions are made in context, a skill only gets in the way. It fixes one variant where flexibility was the point.

It is also worth separating a skill from the project description file. That file describes the project as a whole and is always read: stack, commands, conventions. A skill describes one procedure and loads when relevant. Stuffing procedures into the shared file makes it grow until it occupies context in every task, including the ones that do not need it - see limits.

Writing your own, step by step

Take a real task: adding a new article to a blog on a static site. Repeatable, and nowhere described in code.

Step 1. Describe the procedure in words. How you do it by hand: two files for two locales with the same slug, the required frontmatter fields, the build as the check, a link to a neighbouring article.

Step 2. State when the skill applies. “When adding or editing an article in the blog or the wiki” is a usable description. “Content work” is not - far too broad.

Step 3. Write the steps in order and add what is easy to forget: which fields are mandatory, what must not appear in the text, what verifies the result.

Step 4. Add a definition of done. This matters more than the rest. “The build passes and the link check finds nothing broken” is verifiable. “The article is good” is not.

Step 5. Test it on a real task and write down whatever the agent got wrong. A first version of a skill is always incomplete: you learn what you failed to mention only by seeing the output.

The common mistake

Skills get written too generically, and then they change nothing. The value of a skill is exactly what is specific to your project: not “write good code” but “migrations in this repository live here, are named like this, and must always have a down step”.

The model already knows the general advice. It does not know your project.

Skills combine well with subagents - a procedure becomes a task you can delegate whole. Team rollout has its own article. The overview is in the Claude Code guide.

FAQ

How is a skill different from a prompt?

You write a prompt from scratch every time, and slightly differently every time. A skill lives in the project, gets picked up on its own when a task resembles it, and behaves identically for the whole team. The difference is that between telling a new hire how something works and writing it down.

Where are skills stored?

In a settings directory: either inside the project, where they are shared with the team and versioned alongside the code, or in your user profile, where they are personal and available in every project. Project-specific procedures belong in the project.

When is a skill not worth it?

When the procedure runs twice a year, or looks different every time. Skills pay off through repetition. A one-off is cheaper to explain in words than to encode in a document that will go stale before it is needed again.