What are skills in Claude Code?

The folder that turns a workflow you ran once into a capability Claude executes on command, forever.

Last week I typed /learn in my Desk Theory folder. Claude read the difference between yesterday's draft and the version I shipped, extracted four new voice-profile principles from my edits, appended them to the right sections of voice-profile.md, bumped the version number, and committed the change. I did not write the code that does that. I wrote a skill called learn (actually, Claude wrote it for me) once, three months ago, and Claude has been running it for me ever since.

Once you understand what a skill is, the way you use Claude Code improves dramatically.

What it is

A skill is a folder Claude Code reads at startup that turns a named capability into something Claude can use on command.

The folder usually lives at ~/.claude/skills/{skill-name}/. The one file that has to be in it is SKILL.md. The SKILL.md describes the capability in plain English: what it does, when Claude should use it, what inputs it needs, what the output should look like.

Around the SKILL.md, a skill folder can hold whatever supporting material the capability needs: reference docs, examples, paste-ready prompts, even small scripts. Claude reads the skill catalog when you open a session and knows what skills exist plus when to use them.

You invoke a skill in one of two ways. By name: type /skill-name and Claude runs it. On its own: Claude reads your prompt, recognizes the pattern the SKILL.md describes, and uses the skill without being asked. Most useful skills get used both ways.

How you make one: just ask Claude

You do not write the SKILL.md by hand. You ask Claude to write it for you.

Open a Claude Code session. Describe the workflow you want skilled. "I want a skill that, every time I commit a new article, reads my edits and updates voice-profile.md with the new patterns. Call it /learn." Claude asks a few clarifying questions, writes the SKILL.md, sets up the folder, and tests it on a recent edit.

I have written every skill I run this way. The leverage is recursive: Claude is the thing that helps you build the next thing that gives you leverage on Claude.

Why it matters

Without skills, every Claude Code session is you describing the workflow you want done. You write the same five-paragraph prompt every Monday morning for the pipeline pull. By Friday afternoon you have written it again, with slightly different wording, for the team digest. You are paying the prompt-design tax every single time.

With skills, you call the workflow by name. The workflow you ran twice last week becomes the capability you call by one keystroke this week and every week after. The compounding is real because the marginal cost of building the second skill is fifteen minutes; the marginal cost of building the fifth one is ten.

There is also a quieter unlock. Skills make the agent's behavior legible. The skill folder is on your disk; you can read it. When the output is wrong, you do not have to remember how you prompted Claude last time. You open the SKILL.md and edit it (or ask Claude to edit it for you). The skill is the source of truth, not your memory of last week's chat.

The pairing matters: a good [CLAUDE.md][1] gives Claude the brief. A good skill catalog gives Claude the verbs. Together they shift Claude Code from a chatbot that needs constant briefing to an operator that already knows your business and how to act in it.

What a good skill looks like

The anchor is /learn. I run it after every Desk Theory article I edit, to turn each hand-edit into a permanent improvement to my voice profile.

What it does: it reads the difference between the AI draft and my final version, picks out new patterns in my edits (word choices I preferred, phrasing I cut, sections I restructured), checks them against my existing voice profile so it does not re-add a rule that already lives there, and appends the new principles to the right sections of voice-profile.md. Then it bumps the version number and commits the change. Every step is described in plain English in the SKILL.md file. Claude reads the file, follows the description, does the work.

Why this is a skill and not a prompt. Because it gets reused (every article edit). Because the inputs and outputs are stable (diff in, voice-profile bullets out). And because every time it runs, the next run gets sharper: the voice profile improves, the next AI draft is closer to what I would have written by hand, the next diff is smaller. That is the durable definition. A skill earns its keep when every run makes the next run easier. If you cannot say that about a candidate skill, it is probably just a prompt.

Common mistakes

Building a skill for a one-time task. If you are only going to run the workflow once, just prompt Claude directly. Skills earn their cost only through reuse; a skill you will never call again is just an expensive prompt.

Making the SKILL.md too long. Same rule as CLAUDE.md: every word costs context window. Aim for under 200 lines. If your skill needs more, move the long content into supporting files in the folder that Claude reads only when the skill is invoked.

Hiding the trigger. If Claude cannot tell from the SKILL.md when to use the skill, it will not. Be explicit: "Run this when..." beats "This skill is for..." every time.

Not iterating after the first run. The first version of a skill is rarely the final one. Use it for a week, notice the failure patterns, ask Claude to edit the SKILL.md. The skills I use most have been edited eight or ten times since I first wrote them.

Skills are portable across harnesses

Skills follow an open standard called agentskills.io SKILL.md. The same skill folder works in Claude Code and in [OpenCLAW][2], the open-source [harness][4] I run on Headphones.com. Other open-source harnesses are converging on the same standard.

For the CEO reader, this means the skill catalog you build today is portable. The hours you invest writing skills are not locked into one vendor. If you switch the harness underneath, the skills come with you.

Do this next

Pick the workflow you ran twice last week. Open a Claude Code session in the relevant folder. Tell Claude what the workflow does and ask Claude to make a skill for it. Then run it. The how-to companion is [Make a skill in Claude Code][3]. Tell me what you would name your first skill. I love seeing the first one people build.

[1]: /articles/what-is-a-claude-md-file [2]: /articles/what-is-openclaw [3]: /workflows/make-a-skill-in-claude-code [4]: /articles/what-is-a-harness