Claude Code skills: what they are and how to write one

Most people I talk to use Claude Code the same way every day. They open a session, paste the same context, explain the same process, and fix the same mistakes in the output. Then they do it again tomorrow.

A skill ends that loop. You write the explanation once, in a file, and Claude picks it up whenever the task comes back.

This guide covers what a Claude Code skill is, how to write one, how to get Claude to actually use it, and which tasks I would turn into skills first.

What is a Claude Code skill?

A Claude Code skill is a folder with a SKILL.md file that teaches Claude how to do one specific task. The file starts with a short YAML header (a name and a description) and continues with plain instructions. Next to it you can put anything the task needs: a template, a checklist, an example of good output, a script.

Anthropic introduced Agent Skills in October 2025, and they now work across Claude Code, the Claude apps and the API. In Claude Code, custom slash commands were folded into skills too. A skill called weekly-update gives you a /weekly-update command for free.

The clever part is how little it costs to have one. At the start of a session, Claude only reads the name and description of each skill. The full instructions load when a request matches, and supporting files load only when the instructions point to them. Anthropic calls this progressive disclosure. In practice it means you can keep a whole library of skills installed without them eating your context.

How is a skill different from CLAUDE.md, subagents and MCP?

A skill holds the procedure for one job, CLAUDE.md holds what is always true, a subagent does work in a separate context, and MCP connects Claude to outside tools. They solve different problems, and a good setup uses all four.

My rule of thumb: if it is true on every task, it goes in CLAUDE.md. If it is a way of doing one task, it becomes a skill. I wrote more about the skill versus subagent split in my guide to Claude Code subagents.

Where do Claude Code skills live?

Claude Code skills live in a skills folder, and the folder you pick decides who gets the skill. Each skill gets its own subfolder named after the skill, with SKILL.md inside.

For business work I keep most skills personal. For anything a team should do the same way, like a release checklist or a client report, the project folder is the better home. Then the procedure lives in the repo instead of in one person's head.

How do you write your first skill?

You write a skill by creating the folder, adding a SKILL.md with a name and description, and putting the steps underneath in plain language. Here is the order I would follow.

1. Pick one recurring task. Something you do at least weekly and already explain the same way every time.
2. Do it once with Claude, out loud. Run the task in a normal session and correct Claude until the output is right. Those corrections are your skill.
3. Create the folder. For example ~/.claude/skills/weekly-client-update/.
4. Write the frontmatter. A name in lowercase with hyphens, and a description that says what the skill does and when to use it.
5. Write the steps. Numbered, short, specific. Include what good output looks like and what to never do.
6. Add supporting files. A template or a real example of a good result works better than three paragraphs describing one.
7. Test it both ways. Ask for the task in your own words and check that Claude picks the skill. Then call it with /weekly-client-update directly.

Here is what that could look like. Say you run a small agency and send every client a short update on Fridays. This is an example, not my own setup:

---
name: weekly-client-update
description: Writes the Friday status update for a client. Use when asked for a weekly update, client update or status email for a specific client.
---

# Weekly client update

1. Ask which client if it is not clear from the request.
2. Read the client's notes in clients/<client>.md and this week's tasks.
3. Write the update using template.md in this folder.
4. Keep it under 150 words. Lead with what shipped, then what is next, then anything we need from them.
5. Never promise dates that are not in the task list.
6. Return a draft. Do not send anything.

Put template.md next to it with the structure of a good update. Claude reads it only when it gets to step 3.

Anthropic's own documentation sets a few limits worth knowing. The name can be up to 64 characters, using lowercase letters, numbers and hyphens. The description can be up to 1,024 characters. And Anthropic recommends keeping the body of SKILL.md under 500 lines, moving longer reference material into separate files. If your skill is getting longer than that, it is usually two skills.

Why does the description matter so much?

The description is the only part of a skill Claude sees before deciding to use it, so a vague description means a skill that never runs. Claude matches your request against every description it has. If yours says "helps with emails", it competes with everything else that touches email and usually loses.

A good description answers two questions: what does this do, and when should it be used? Write the second part in the words you actually type. If you say "prep me for my 2 o'clock", put "meeting prep" and "prepare for a call" in the description, not "calendar-based briefing generation".

Two settings help when Claude gets it wrong. If a skill fires when it should not, for example one that sends something or deploys something, set disable-model-invocation: true in the frontmatter. Then it only runs when you type the command. And if a skill should only read, not write, allowed-tools limits what it can touch while it is active. Start narrow. I explain why in why AI agents break in production: access that is far too wide is one of the five patterns I see again and again.

Which skills should you build first?

The first skills to build are the tasks you repeat every week and already explain the same way each time. Those have the clearest steps and the fastest payback.

For business work, the candidates usually look like this:

• Meeting prep: who the person is, what was said last time, what you want from the call.
• Email in your voice: tone, length, sign-off, what you never say.
• Proposals and quotes: your structure, your pricing logic, your standard terms.
• Content: how a LinkedIn post or newsletter of yours is built.
• Task review: what is overdue, what is urgent, what to do first.

That last one is where a lot of people start. My free resources include a Claude Code TASKS skill template you can copy and adapt. If you want to see how skills, memory and connected tools fit together in a whole business, I described my setup in how I run my business with Claude Code.

What goes wrong with skills?

Most skill problems come from writing too much, too early, or from skills that quietly go out of date. A few I see often:

• The everything skill. One giant skill for "marketing". Claude cannot tell when to use it, and when it does, it loads a wall of text. Split it per task.
• Facts in skills. Your prices or your team list end up copied into five skills. Then one changes. Keep facts in CLAUDE.md or a single reference file and point to it.
• No example of good output. Describing a good result takes paragraphs. Showing one takes a file.
• Never updated. A skill is a written process. When the process changes and the skill does not, Claude follows the old one with full confidence.

This matters more than it seems. In the Stack Overflow 2025 Developer Survey, 84% of respondents said they use or plan to use AI tools, yet 46% said they do not trust the accuracy of the output. A lot of that distrust is generic output from a model that was never told how the work is done. Skills are the fix for that part: you stop hoping Claude guesses your process and start writing it down.

Is it worth the effort?

Yes, if you pick the right task. A skill takes a focused hour to write well, and it pays that back the third or fourth time the task comes up. More important, it makes the output consistent. The same process every time, whether you are sharp on a Monday morning or tired on a Friday.

Start with one. Watch where Claude still needs correcting, and put each correction into the skill. After a few weeks you will have written down how your work is actually done. That document is worth having even without the AI.