Claude Skills: What They Are and How Teams Should Use Them (2026)

TL;DR

A Claude Skill is a folder containing a SKILL.md file with instructions, plus any scripts or reference files it needs, that Claude loads on demand when the task matches. Anthropic describes the mechanism as progressive disclosure: the name and description stay in context, and the full body loads only when relevant, so a team can maintain many skills without paying for all of them on every request. Skills are excellent at encoding a repeatable procedure. They do not hold facts about your company, and confusing the two is the most common way teams get disappointed by them. This guide covers what belongs in a skill, what does not, and how skills relate to memory and MCP.

What is a Claude Skill, mechanically?

A skill is a directory with a SKILL.md at its root. The file carries frontmatter with a name and a description, then a body of instructions in markdown. Supporting files, scripts and templates can sit alongside it and be referenced from the body.

The loading behaviour is the part worth understanding:

1. Only metadata is always in context. The skill's name and description are visible so the model can decide whether the skill applies. The body is not loaded until it does.

2. The body loads when the task matches. This is why descriptions matter more than the instructions themselves. A perfect skill with a vague description never fires.

3. Referenced files load on demand. A skill can point at a large reference document without that document sitting in context permanently.

4. Skills can carry executable code. Scripts in the folder can be run, which is what makes a skill able to do a procedure rather than only describe one.

The result is that skills scale where a single instruction file does not. A CLAUDE.md that grows to cover twenty procedures is paid for on every request. Twenty skills cost their descriptions.

What belongs in a skill, and what does not?

The dividing line is procedures versus facts.

Good candidates, because they are repeatable procedures

1. A multi-step workflow with a fixed order, such as a release checklist or a review process where skipping a step causes real problems.

2. A house format, such as how your team writes design documents, incident reports or customer-facing copy.

3. A task requiring a specific tool invocation, where the script can live in the skill folder rather than being reconstructed each time.

4. Anything you have explained to the model more than three times. That repetition is the signal.

Poor candidates, because they are facts that change

1. Current system ownership, which changes with every reorganisation and will be silently wrong the week after you write it.

2. Customer or account state, which is different by the time anyone reads it.

3. Decisions and their rationale, which need provenance and a date to be trustworthy, and a markdown file provides neither.

4. Anything another system is the source of truth for, because a copy in a skill file is a fork that will drift.

The failure mode is predictable: a team writes a skill containing organizational facts, the facts go stale, the model confidently asserts them, and trust in skills collapses. Skills have no concept of a fact expiring.

Skills, MCP, and memory: which does what?

These three get conflated constantly, and they are not alternatives.

The clean mental model: a skill is how to do something, MCP is how to reach something, and a memory layer is what is currently true. A mature setup uses all three, and the skill body should point at the memory layer for facts rather than restating them.

How should a team structure its skills?

Five rules that separate skill libraries that get used from ones that get abandoned:

1. Write the description for a matcher, not a human. Include the phrases someone would actually say when they want this skill. Most skills that never fire have descriptions written as titles.

2. Keep the body imperative and short. Instructions the model must follow, not context it might enjoy. Long preamble dilutes the actual rules.

3. Put facts behind a lookup, not in the file. Where a procedure needs current state, the skill should say where to get it. That single discipline prevents almost all skill rot.

4. Version them with the code they describe. A skill about your deploy process belongs in the repository that deploys, so it changes in the same pull request.

5. Delete aggressively. A skill that fired once in three months is noise in the matcher and makes the others less likely to fire correctly.

FAQ

The decision rule

Write a skill when you have explained the same procedure more than three times and the procedure is stable. Keep every fact that can change out of it, and point at the system that owns that fact instead, because a skill that goes quietly stale costs more trust than it ever saved effort.