What A Claude Skill Actually Is
A Skill is packaged, reusable behavior Claude loads only when a task needs it, instead of being crammed into every prompt. Learn what belongs in one.
The problem Skills solve
If you have used Claude for more than a week of real work, you have felt this pain: you keep pasting the same instructions into chat. The same tone rules, the same escalation policy, the same "always include a next-step line" reminder. You tried stuffing it all into one giant system prompt or an 800-line CLAUDE.md, and now every single request pays the token cost of every rule, whether the task needs it or not. As the prompt grows, behavior gets less predictable, and updating one rule means hunting through prompts scattered across your system.
An Agent Skill is Anthropic's answer. At its simplest, a Skill is a directory containing a SKILL.md file. The file starts with YAML frontmatter (a name and a description) followed by markdown instructions. That is the entire format. No SDK, no build step, no server process. Skills work in Claude Code, claude.ai, and the Claude API, and the SKILL.md format is an open standard also supported by other agent tools, so a Skill you write today is portable.
A real SKILL.md
Here is the support-reply example as an actual, working Skill you could drop into .claude/skills/support-reply/SKILL.md today:
---
name: support-reply
description: >
Drafts customer support replies in our house voice. Use when the
user asks to answer a support ticket, reply to a customer email,
or draft a response to a complaint or question from a customer.
---
# Support Reply
## Rules (always apply)
- Open by acknowledging the customer's specific issue in one sentence
- Never promise a delivery date or a refund amount
- Every reply ends with a clear next-step line ("You can expect...")
- Anything mentioning refunds, legal action, or data loss:
stop and flag for human review instead of drafting
## Workflow
1. Read the customer message and identify the single core issue
2. Draft the reply following examples/good-replies.md
3. Check every rule above before returning the draft
## Tone
Match examples/good-replies.md. Warm, direct, no corporate filler.
Two frontmatter fields matter. The open Agent Skills specification requires both: name is 1-64 lowercase letters, numbers and hyphens and matches the folder name, and description is 1-1,024 characters. Claude Code itself is more lenient (every field is optional, name defaults to the folder name, and the description plus any when_to_use text is truncated at 1,536 characters in the skill listing), but writing to the stricter spec keeps a Skill portable. The description does two jobs at once: it says what the Skill does AND when to trigger it, including the literal phrases a user might say. That matters because of how loading works.
Progressive disclosure: why this scales
Skills stay cheap through three tiers of loading:
- Tier 1 - Discovery. At session start, Claude loads only the name and description of every installed Skill. That costs roughly 100 tokens per Skill, so 20 installed Skills cost about 2,000 tokens total.
- Tier 2 - Activation. When Claude decides a Skill matches the task (or you invoke it directly with
/support-reply), it reads the full SKILL.md body into context. Keep this body under about 5,000 tokens. - Tier 3 - Execution. Supporting files like
examples/good-replies.mdcost nothing until Claude actually opens them, which it does only when the task calls for it.
How Skills compare to the things people confuse them with
| Dimension | System prompt / CLAUDE.md | Agent Skill | MCP server |
|---|---|---|---|
| What it is | Static text loaded every message | Folder + SKILL.md loaded on demand | Running process Claude calls via JSON-RPC |
| Token cost | Full cost, always | ~100 tokens until activated | Tool definitions in context, plus call results |
| Best for | Short, always-relevant facts | Procedures, conventions, workflows | Live data access and external actions |
| Setup effort | None | Write a markdown file | Install or run a server, configure auth |
The one-line summary to internalize: Skills teach Claude how, MCP gives Claude access, the system prompt tells Claude who it is.
What lives inside a good Skill
A Skill answers "how should Claude behave when doing this kind of work." A good one contains instructions written as clear steps, hard constraints it must not break, and examples showing what correct output looks like. The folder for the support-reply Skill looks like this:
.claude/skills/support-reply/
├── SKILL.md
└── examples/
└── good-replies.md
A Skill does not hold your whole system prompt or every rule your company has. It holds the behavior for one recognizable kind of task, so Claude can load it, apply it, and move on. When Claude handles a support message, it loads this Skill and behaves consistently, every time, without you repeating yourself.
Why this matters
Skills give you three things a long prompt cannot. Behavior stays consistent because the same package applies every time the task appears. Updates happen in one place, so fixing a rule fixes it everywhere, for every teammate. And each request stays focused, because Claude is not wading through instructions for tasks it is not doing right now. There is a deeper shift too: every correction you make in chat evaporates, while every correction you encode in a SKILL.md compounds. The file becomes version-controlled institutional knowledge.
Where Skills live, and which one wins
A Skill is only useful if the right people get it, and that is decided entirely by which directory it sits in. There are three homes, and they are read in order of specificity.
~/.claude/skills/<name>/SKILL.md # personal - follows you, not the repo
<repo>/.claude/skills/<name>/SKILL.md # project - committed, everyone gets it
<plugin>/skills/<name>/SKILL.md # distributed - shipped across many repos
The practical consequence is a decision you should make consciously every time you write one: is this how I work, or how the team works? Personal Skills are where your own habits go - the way you like commits phrased, the review checklist you run before you push. Project Skills are conventions the codebase enforces, and because they are committed, a new joiner inherits every one of them on their first clone without anyone writing an onboarding doc. That last point is the underrated one. A repo with a well-kept .claude/skills/ directory onboards agents and humans with the same artefact.
When names collide, the more specific location wins. That is a feature, not a hazard: a developer can override a team Skill locally while they work out whether a change is an improvement, then propose it as a commit once it is proven.
The description field, dissected
Everything above hangs on one field. At discovery time Claude sees names and descriptions only, so the description is not documentation - it is the routing table. Almost every "my Skill never fires" report is a description problem.
A weak description and a strong one, on the same Skill:
# Weak - accurate, and useless for routing
description: Helps with support tickets.
# Strong - names the job, the artefacts, and the words a user says
description: >
Drafts customer support replies in our house voice, applying the
escalation policy. Use when the user asks to answer a support
ticket, reply to a customer email, respond to a complaint,
handle an angry customer, or draft a response to a refund request.
Three habits produce the second one. Write the trigger phrases literally, in the user's words rather than yours - people say "angry customer", not "negative-sentiment inbound". Name the artefacts the task involves (ticket, email, complaint, refund request), because those nouns are what a request actually contains. And state the boundary when two of your Skills are neighbours: if you have both a support-reply Skill and a support-escalation Skill, each description should say what it is not for, or Claude will pick between them on a coin flip.
One more habit that costs nothing: write the description last. You cannot describe when a Skill should fire until you have written what it does.
Measure the token cost yourself
Progressive disclosure is the reason Skills scale, but treat the per-Skill figures above as the order of magnitude they are, not as a budget you can plan against - your descriptions are not the same length as anyone else's, and the number moves as you edit them. The measurement is trivial to do on your own Skills:
# rough proxy: characters / 4 is a serviceable token estimate for English
for f in ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md; do
desc=$(sed -n '/^---$/,/^---$/p' "$f" | wc -c)
body=$(wc -c < "$f")
echo "$((desc/4)) $((body/4)) $f" # discovery cost, activation cost
done | sort -rn
Sort that output and you will usually find one or two Skills with descriptions three times longer than the rest, and they are almost always the ones somebody pasted a paragraph of rationale into. Rationale belongs in the body, or in a supporting file, or nowhere. The description pays rent on every single session.
The activation column is worth watching too. A SKILL.md body that has grown past a few pages is a signal to split: move reference material into supporting files that Claude opens only when the task reaches them, and leave the body as the procedure. That is Tier 3 doing its job, and it is the difference between a Skill that stays cheap at twenty installed and one that does not.
Four things people confuse with Skills
The table above covers the three big neighbours. In practice a fourth keeps coming up, so here is the full set in one pass:
- CLAUDE.md is context that is true always - the stack, the conventions, where things live. It is loaded every message, which is exactly why it should stay short. Anything task-specific in there is paying rent it does not owe.
- A Skill is a procedure for one recognizable kind of task, loaded when that task appears. Behaviour, not access.
- A subagent is a separate context window doing a delegated job and reporting back. You reach for one when the work would otherwise flood your main context - a broad search, a long log trawl - or when you want a genuinely independent pass over something. A Skill changes how work is done; a subagent changes where it is done. They compose, and the later modules of this course are largely about composing them.
- An MCP server is access: live data and real actions in external systems. No amount of instruction text can substitute for it, and no MCP server can substitute for the judgment a Skill encodes.
The failure mode this list prevents is the most expensive one in the whole topic: trying to solve an access problem with better instructions. If Claude cannot see the order records, no Skill will help. Write the MCP server, then write a Skill that says how to interpret what it returns.
What a Skill cannot do
Being precise about the limits saves a lot of wasted effort:
- It is not a permission boundary. A SKILL.md that says "never delete anything" is an instruction, not a guardrail. Real enforcement lives in tool permissions and hooks, and this course covers both. Write the instruction anyway - it makes intent legible - but do not mistake it for a control.
- It cannot fetch anything by itself. A Skill can tell Claude to run a command or read a file, which works because Claude already has those tools. The Skill is not doing the fetching.
- It does not guarantee activation. Automatic discovery is a model judgment about relevance. When correctness matters more than convenience, invoke it explicitly and take the guesswork out.
- It does not make a vague task crisp. If you cannot state the finish line, the Skill will produce mush consistently instead of mush randomly.
Setup: install one and prove it works, in five minutes
Reading about the format is not the same as watching one fire. There is no installer and no build step, so the whole setup is three commands and a text file. Run these from the root of any repo you are working in - as of August 2026 this is the project-scoped location, committed with the code, so everyone on the repo gets it.
mkdir -p .claude/skills/release-notes
$EDITOR .claude/skills/release-notes/SKILL.md
Put exactly this in the file. It is deliberately short, because your first one should be small enough that you can tell whether it fired from the shape of the output alone:
---
name: release-notes
description: >
Writes release notes from a range of git commits in our house
format. Use when the user asks for release notes, a changelog,
a summary of what shipped, or notes for a version or tag.
---
# Release Notes
## Workflow
1. Run git log --oneline for the range the user names.
If they name no range, ask before assuming.
2. Group commits under exactly these headings, omitting empty ones:
Added, Changed, Fixed, Removed.
3. One line per user-visible change. Merge commits, dependency
bumps and formatting-only commits are dropped, not listed.
## Rules
- Write for a customer, not a developer. No file paths, no commit
SHAs, no internal ticket numbers in the output.
- Every line starts with a verb in the past tense.
- If a change alters behaviour people depend on, prefix the line
with **Breaking:** - this is the one thing never to omit.
## Output
Markdown, headings as above, nothing else. No preamble, no summary
paragraph, no offer to make further changes.
Now verify it in three checks, in this order, because each one isolates a different failure:
- Does the file parse? Start a fresh session in that directory and invoke the Skill explicitly by name. If the tooling cannot see it at all, the fault is the location or the frontmatter - the two
---lines must be the very first and third-ish lines of the file, with no blank line above the first one, and if you setname, keep it identical to the folder name so the command you expect is the one you get. - Does it change the output? Ask for release notes with the Skill invoked explicitly. Then start another fresh session, and ask for release notes without invoking it, with the Skill folder temporarily renamed to
release-notes.off. Compare. If the two outputs are indistinguishable, your Skill is not saying anything the model was not already going to do, which is a real result and means you should make the rules more opinionated. - Does it fire on its own? Restore the folder, start a fresh session, and ask in the words a colleague would actually use: "can you write up what shipped since v2.3?" - note that the phrase "what shipped" appears verbatim in the description. That is not a coincidence, and it is the whole technique.
Check two is the one people skip, and it is the one that keeps a Skills directory honest. A Skill that does not change the output is pure cost: it pays its discovery tokens on every session and buys nothing.
Worked example: splitting a bloated CLAUDE.md
The most common starting point is not an empty directory, it is a CLAUDE.md that grew for six months. Here is the split done properly on an illustrative 180-line file, so you can see the sorting rule applied rather than described.
BEFORE - CLAUDE.md, 180 lines, loaded on every single message
L1-12 Stack: Next.js, Postgres, deployed on Fly
L13-24 Where things live: src/app, src/lib, tests alongside
L25-31 Never commit to main; branch naming convention
L32-78 How to write a database migration (47 lines, with
the rollback checklist and three worked examples)
L79-96 Our PR description format, with an example
L97-134 How to add a new API route: validation, auth check,
error envelope, the four tests it must have
L135-158 Release notes format and the changelog conventions
L159-172 Tone rules for anything customer-facing
L173-180 Don't run the dev server, port 3002 is held
Apply one question to each block: is this true for every request, or only when a particular kind of task appears?
| Block | True always? | Home |
|---|---|---|
| Stack, layout, branch rules, dev-server warning (L1-31, L173-180) | Yes - shapes every answer | Stays in CLAUDE.md. About 40 lines |
| Migrations (L32-78) | No - only when writing one | skills/db-migration/, worked examples into a supporting file |
| PR descriptions (L79-96) | No - only at PR time | skills/pr-description/ |
| New API route (L97-134) | No - only when adding one | skills/api-route/ |
| Release notes (L135-158) | No - a few times a month | skills/release-notes/ |
| Customer-facing tone (L159-172) | Contested - see below | Split: two lines stay, the detail moves |
AFTER
CLAUDE.md ~40 lines, loaded every message
.claude/skills/
db-migration/SKILL.md + examples/three-migrations.md
pr-description/SKILL.md
api-route/SKILL.md + examples/route-with-tests.ts
release-notes/SKILL.md
Two judgment calls in that split are worth spelling out. The migration examples went into a supporting file rather than the SKILL.md body, because they are long and are only needed once the task is already underway - that is Tier 3 earning its keep. And the tone block got split rather than moved wholesale: the two sentences that constrain any customer-visible string stayed in CLAUDE.md, while the detailed voice guidance moved into the Skills that produce customer-facing text. Resist the urge to make the split clean at the cost of making it wrong; a rule that genuinely applies everywhere belongs in the file that loads everywhere, however tempting it is to empty that file out.
The gain is not primarily tokens, although the always-loaded file dropping to roughly a fifth of its size is real. The gain is that each rule now has one obvious home, so the next person who wants to change the migration checklist knows where to look and does not have to read 180 lines of unrelated context to find it.
Troubleshooting: why a Skill did not fire
| Symptom | Cause | Fix |
|---|---|---|
| The Skill is not listed at all | Wrong location, wrong filename, or the frontmatter did not parse | Confirm the path ends skills/<name>/SKILL.md, filename in capitals, and that the file opens with --- on line 1 with no blank line before it |
| Listed, but explicit invocation is the only thing that works | The description describes rather than routes | Add the literal phrases users say. Say the request out loud, write down your own words, put those words in the description |
| Fires, but the output ignores half the rules | The body reads as background, so the rules are buried in prose | Convert every rule to an imperative bullet. Delete every sentence explaining why - it costs tokens on every activation and changes no behaviour |
| The wrong one of two related Skills fires | Neighbouring descriptions overlap | Give each description an explicit exclusion: "Not for escalations - use support-escalation for those" |
| Works for you, not for a teammate | It is in your personal directory, not the repo | Move it to the project location and commit it. This is the most common "it works on my machine" in the whole topic |
| Edits to SKILL.md seem to have no effect | The old version was already loaded into the running session | Start a fresh session before judging any edit. Test Skills in new sessions only |
| Output is identical with the Skill on and off | The Skill only says what the model would do anyway | Either make it more opinionated, or delete it. A Skill that changes nothing is a permanent cost with no return |
Common mistakes
- Building one enormous Skill that tries to cover every task, which defeats progressive disclosure and recreates the giant-prompt problem you were escaping.
- Writing a description like "Support helper" that says what the Skill is but not when to use it. At Tier 1 the description is all Claude sees, so it must route.
- Filling the body with background and rationale instead of operating instructions. Every explanatory sentence costs tokens on every activation and buys no behavior change.
- Leaving out examples, so Claude has rules but no picture of what a good result actually looks like.
What you should be able to do now
- Explain what a Skill is in one sentence: a folder with a SKILL.md, frontmatter plus markdown instructions.
- Name the three tiers of progressive disclosure and roughly what each costs.
- Write a two-field frontmatter block whose description states both what the Skill does and when to trigger it.
- Decide whether a given piece of knowledge belongs in CLAUDE.md, a Skill, or an MCP server.
Where this goes next
This lesson and Writing your first Skill are the free part of the course. Together they get you to a working, committed Skill that fires on the right requests - which is genuinely most of the value, and you should go and build one before reading further.
The paid lessons are about everything that happens after the first Skill works. Structuring supporting files so Tier 3 stays cheap as the Skill grows, subagents and when delegating to a fresh context beats doing the work inline, passing state between a subagent and the session that spawned it, hooks and permissions as the enforcement layer that instructions cannot be, connecting MCP servers so Skills have real data to reason over, and packaging the whole set as a plugin you can install across repos or hand to a client. Every lesson ships the files.
If the goal is a system running in your business rather than a skill set, that is work we do directly - see AI automation services, or take the free automation audit to find which of your repeated tasks is worth encoding first. The system prompt and MCP glossary entries are useful if you are explaining the distinction to someone else.
The box below emails you the free lessons along with the SKILL.md files used in them, so you have working examples of the format rather than retyping from a web page.
Key takeaways
What to remember from this lesson
- A Skill is just a directory with a SKILL.md: YAML frontmatter (name, description) plus markdown instructions. No SDK, no build step.
- The description is the routing decision. At Tier 1 it is all Claude sees, so it must say what the Skill does AND the literal phrases that should trigger it.
- Progressive disclosure keeps Skills cheap: ~100 tokens per Skill at discovery, the full body only on activation, supporting files only when opened.
- Skills teach Claude how, MCP gives Claude access, the system prompt tells Claude who it is. Put each piece of knowledge in the right one.
- One Skill covers one recognizable kind of task. A Skill that covers everything defeats progressive disclosure and recreates the giant-prompt problem.
Try it yourself
Validate a SKILL.md before it fails to load
A Skill that never activates almost always has a frontmatter problem, and frontmatter problems are silent. Write the validator you would run before installing one. The SKILL.md strings the check feeds you are fixtures written for this exercise, not files read from disk.
Check yourself
Skill, MCP, or system prompt?
Your agent needs to read tickets out of your helpdesk, which lives behind an API. Where does that capability belong?
Every release note you get back needs the same three corrections about format. Where does the fix belong?
A Skill's body is beautifully written but the Skill never activates. What do you fix first?
Answer every question to mark.
Exercise
Sort your own instructions into the right home
- 1Open the longest prompt, CLAUDE.md, or saved instruction block you actually use, and copy it into a scratch file.
- 2Split it into individual rules, one per line. Aim for at least 10 lines.
- 3Label every line with one of three tags: CLAUDE.MD (short, always relevant, true for every request), SKILL (a procedure or convention for one recognizable kind of task), or MCP (needs live data or an external action, which no amount of instruction text can provide).
- 4Group the SKILL lines by task. Any group with three or more lines is a candidate Skill - name it in lowercase-with-hyphens.
- 5For your largest group, write only the frontmatter: a name under 64 characters, and a description that states what it does and names at least two literal phrases a user would say to trigger it.
You are done when Every line of your original prompt carries exactly one of the three tags, and you have a named candidate Skill with a frontmatter description that contains both a what-it-does clause and at least two trigger phrases.
Companion files
The SKILL.md files from this lesson
The support-reply Skill folder as real files - SKILL.md plus its examples directory - so you can drop it into .claude/skills/ and see the format working before you write your own.
The free-preview pack includes 3 files of runnable code and config for What A Claude Skill Actually Is, plus the other free lessons of this course. No email needed.
Free preview pack - 9 KB zipCheck yourself
Answer before you reveal
You install 20 Skills. Roughly what do they cost you before any of them is used?Show answer
About 2,000 tokens total - roughly 100 tokens per Skill, because Tier 1 discovery loads only each Skill's name and description. The bodies stay unloaded until Claude activates one.
Claude never picks up your Skill when you ask naturally, but /your-skill works fine. Where is the bug?Show answer
In the description, not the body. The body is invisible at decision time - Claude routes on the description alone, so it needs the literal phrases users actually say.
Your team wants Claude to read live order records from your database. Skill or MCP server?Show answer
MCP server. Skills teach behavior; they cannot fetch data. A Skill could still tell Claude how to interpret and present the orders once MCP provides access.
