A Claude Code Skill is a set of instructions saved as a file, which Claude Code loads when it needs them — or when you type its name as a slash command. If you keep pasting the same checklist or procedure into your sessions, that is a Skill waiting to be written. This guide explains Claude Code Skills in plain terms and builds one from scratch.
It assumes you have used Claude Code for a few sessions. If not, start with the Claude Code beginner's guide.
What a Skill is
Anthropic's documentation puts it simply: "Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name."
So a Skill has two ways in:
- You call it by typing
/and its name, like a command. - Claude calls it when your request matches the Skill's description. Ask "what did I change today?" and a Skill described as summarising changes may load on its own.
A Skill is a folder containing at least one file, SKILL.md. It can also hold supporting files — a template, a style guide, an example — that the instructions refer to.
Skills follow an open standard called Agent Skills, which other AI tools also support, and Claude Code adds its own options on top. Older Claude Code guides talk about "custom commands" in a .claude/commands folder; those have been merged into Skills and still work.
Skills vs CLAUDE.md vs MCP
Three features that beginners often confuse:
| What goes in it | When it loads | |
|---|---|---|
CLAUDE.md | Facts about a project: what it is, conventions, what to avoid | At the start of every session in that folder |
| Skill | A procedure: how to do one particular job | Only when invoked or relevant |
| MCP server | A connection to an outside tool or service | When Claude needs one of its tools |
The documentation's rule of thumb: create a Skill "when a section of CLAUDE.md has grown into a procedure rather than a fact". Because a Skill's body loads only when used, long instructions cost almost nothing until they are needed — unlike CLAUDE.md, which is read every session.
Skills and MCP combine naturally: a Skill can describe how to produce your weekly report using data from an MCP server. The Claude Code MCP guide covers the connection side.
Skills that come built in
Claude Code ships with bundled Skills, such as /code-review, /debug and /loop. They are prompt-based: they give Claude detailed instructions and let it do the work with its usual tools. Type / in a session to see what is available on your version.
Where Skill files live
| Location | Path | Available in |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects on this computer |
| Project | .claude/skills/<name>/SKILL.md | That project, for anyone who shares it |
| Plugin | Inside an installed plugin | Wherever the plugin is enabled, as /plugin-name:skill-name |
The folder name becomes the command name. A Skill in ~/.claude/skills/weekly-report/ is invoked with /weekly-report.
Source: Claude Code documentation — Extend Claude with skills.
Build your first Skill
Here is a small, genuinely useful one: a Skill that tidies a meeting-notes file into a consistent format. You can ask Claude Code to create it for you — "create a personal skill called tidy-notes that…" — but writing it by hand once shows you there is no magic.
Step 1: Make the folder
On Mac or Linux, in a terminal:
mkdir -p ~/.claude/skills/tidy-notesOn Windows, create the folder tidy-notes inside %USERPROFILE%\.claude\skills using File Explorer or PowerShell.
Step 2: Write SKILL.md
Create SKILL.md in that folder with this content:
---
description: Tidies raw meeting notes into a standard format. Use when the user asks to clean up, format or organise meeting notes.
---
Rewrite the meeting notes file the user names into this format:
## Meeting: [title] — [date]
**Attendees:** comma-separated list
### Decisions
- one line per decision
### Actions
- [ ] task — owner — due date (write "no date" if none given)
### Notes
- anything else, shortened
Rules:
- Keep every fact. Do not invent owners or dates.
- Save the result as a new file ending in -tidy.md; never overwrite the original.
- Finish by listing anything you were unsure about.The part between the --- lines is the frontmatter. description is the only field the documentation recommends: it is how Claude decides when the Skill is relevant, so write it as "what it does, and when to use it".
Step 3: Try it
Start Claude Code in a folder with a notes file and type:
/tidy-notes notes-monday.mdOr simply ask, "can you clean up my meeting notes from Monday?" and watch whether Claude picks the Skill up by itself. If it does not, make the description more specific.
Useful options, when you need them
disable-model-invocation: true— only you can run the Skill. Use it for anything with side effects, such as a Skill that sends or publishes something. You do not want Claude deciding it is time to publish.user-invocable: false— only Claude can use it. Good for background knowledge that is not a meaningful command.- Arguments — text you type after the command name is passed to the Skill, so
/tidy-notes notes-monday.mdcan target a specific file. - Supporting files — put a template or example next to
SKILL.mdand refer to it in the instructions.
Good first Skills for non-programmers
- A house style for everything you write: tone, spelling, words to avoid.
- A monthly routine: "process this month's invoices" as one command.
- A report format you produce every week.
- A checklist to run before sending anything to a client.
Any job from our list of things to automate with Claude Code is a candidate once it works reliably as a prompt. And the beginner prompts list is full of instructions that become Skills the second time you need them.
Common mistakes
- A vague description. "Helps with documents" will trigger at the wrong times or never. Say what it does and when.
- Facts in a Skill, procedures in CLAUDE.md. Swap them.
- Letting Claude auto-run Skills that act on the outside world. Set
disable-model-invocation: true. - One enormous Skill. Several small ones are easier to trigger correctly and easier to fix.
Skills have their own chapter in Claude Code for Beginners, which covers where they live, why loading on demand matters, and how to create and manage them — followed by chapters on MCP and custom agents, the other two features that turn Claude Code into a system. The book's free toolkit on the Claude Code for Beginners page includes prompts you can convert straight into Skills.
Frequently asked questions
Do I need to code to write a Skill?
No. A Skill is written in plain English with a few lines of settings at the top.
What is the difference between a Skill and a subagent?
A Skill is instructions that run in your current conversation. A subagent is a separate helper with its own context window and tools. See Claude Code agents explained.
Can I share a Skill?
Yes. Put it in a project's .claude/skills folder and share the project, or distribute it as part of a plugin.