Teach Claude your workflow once — in a folder of plain Markdown — and benefit from it every conversation after.
Imagine you hire the single most capable analyst in the world. Brilliant, tireless, knows every framework, writes flawless code. There's exactly one catch: every morning they wake up with total amnesia. They've forgotten your company's brand colors. Forgotten that your sprint tickets always need a "T-shirt size" estimate. Forgotten that your research reports always open with a one-paragraph TL;DR and end with an open-questions section.
So every single morning, before they can do anything useful, you sit them down and re-explain all of it. Again. The brand guide. The ticket format. The report structure. By the time you've finished briefing them, half the morning is gone — and tomorrow you'll do it all again.
That analyst is Claude. The amnesia is the blank context window at the start of every conversation. And the morning briefing you keep re-typing is what we'll call the context tax — the tokens, time, and patience you spend re-explaining your specific processes, over and over, because the model has no memory of them between chats.
A skill is the cure. It is a small folder of instructions you write once that teaches Claude how to handle a specific task or workflow. Instead of re-explaining your preferences, processes, and domain expertise in every conversation, you teach Claude once and benefit every time. The morning briefing becomes a file the model reads for itself, exactly when it's needed.
Before we touch a single line of YAML, let's feel the problem the skill solves. The widget below is a meter for the context tax. Drag the sliders to match your own situation — how big is the stuff you keep re-pasting, and how often do you start a fresh conversation?
Left bar: tokens you re-paste every conversation, forever. Right bar: a one-time cost — you write the skill once, and from then on Claude loads it for itself. Drag both sliders and watch the gap.
Let's put real numbers on it. Suppose your morning briefing — brand guide plus ticket format plus report skeleton — is about 800 tokens. You start a fresh conversation roughly 40 times a week. Over a single month (4 weeks) that is:
One hundred and twenty-eight thousand tokens — a small novel — spent every month re-teaching the same handful of rules to an amnesiac genius. And that's just one workflow. Most teams have a dozen. The skill replaces that entire recurring bill with a single up-front payment: write the folder once.
Here's the punchline that the rest of the lesson unpacks: a skill is "a set of instructions packaged as a simple folder that teaches Claude how to handle specific tasks or workflows." Skills work identically across Claude.ai, Claude Code, and the API — write once, run everywhere. They compose: you can have many loaded at once and they cooperate rather than collide. And, crucially, they stay out of your way until the moment they're relevant.
The word "skill" sounds like it might involve a model, a training run, or at least a clever program. It doesn't. A skill is something you could create with the "New Folder" button and a text editor. Demystifying this is the whole job of this chapter, because everything later gets easier once you internalize: a skill is a folder on disk, and nothing more.
Here is the complete anatomy. A skill is a folder containing up to four things, only the first of which is required:
--- lines) followed by the actual instructions in plain Markdown prose.That's it. The smallest legal skill in the world is a folder with a single SKILL.md in it and not one other file. No code, no dependencies, no build step. If you can write Markdown, you can write a skill.
Click through the folder below. Each part lights up with what it's for, when it gets loaded (we'll make "when" precise in the next chapter), and a concrete example of what lives inside.
A real example: a sprint-planner skill. Tap any row to inspect it. Notice that only SKILL.md is mandatory; everything else is there because this particular skill happens to need it.
Walk through a concrete sprint-planner example so the abstraction has flesh on it. The folder might look exactly like this:
folder layout sprint-planner/ ├── SKILL.md # required — metadata + instructions ├── scripts/ │ └── estimate.py # deterministic story-point math ├── references/ │ └── velocity.md # how we compute team velocity └── assets/ └── ticket.md # the ticket template we paste into Linear
The instructions in SKILL.md can point at the other files in plain English: "Before estimating, read references/velocity.md." Or: "Run python scripts/estimate.py --tasks tasks.json." Or: "Format each ticket using assets/ticket.md." The model follows those pointers the way you'd follow a recipe that says "see page 14 for the sauce."
SKILL.md. The reason you don't is the single most important idea in this entire lesson, and it gets its own chapter next: the model shouldn't pay for context it isn't using right now. The folder structure exists so that the velocity formula, the estimation script, and the ticket template can each be loaded only at the moment they're needed — not dumped into the conversation up front.
scripts/ folder is optional and many excellent skills have none. Anthropic's own frontend-design skill, for instance, uses no external tools at all — it's instructions and embedded style guidance, riding on Claude's built-in abilities. Reach for a script only when a step must be deterministic (a validation check, a precise calculation) — code always gives the same answer; language interpretation doesn't.
Two naming rules will save you a frustrating afternoon, so meet them now (we'll see the exact error messages in Chapter 6):
SKILL.md — case-sensitive. Not skill.md, not SKILL.MD, not Skill.md. The uploader looks for that precise string and nothing else.sprint-planner. No spaces, no capitals, no underscores.And one thing that does not belong in the folder: a README.md. All human-and-model-facing documentation goes in SKILL.md or references/. (When you later publish a skill on GitHub for people to browse, you'll add a repo-level README outside the skill folder — but that's a separate file for a separate audience, covered in Chapter 9.)
This is the heart of the whole design. If you understand this chapter, every "why is it structured that way?" question for the rest of the lesson answers itself. So let's manufacture the need for it before stating the answer.
Picture the model's context window as a desk of fixed size — the working surface where everything the model is currently "thinking about" has to fit. Now suppose you've installed thirty skills: a sprint planner, a brand-design helper, a legal-doc reviewer, a data-cleaning tool, and so on. If every skill dumped its full instructions onto the desk the moment it was installed, the desk would vanish under paper before you'd typed a single word. There'd be no room left to actually work.
So the naive approach — "load every skill, fully, always" — cannot work at scale. We need a way for thirty skills to be available without thirty skills being present. That mechanism is progressive disclosure: information is revealed in levels, and each level is loaded only when it earns its place.
There are three levels:
name + description. Always in the system prompt. Tiny — tens of tokens. Just enough for the model to know when this skill is relevant.references/, scripts/, assets/. Loaded on demand, file by file, only if a step actually reaches for them.The reason Level 1 has to be tiny is now obvious: it is the one part that is always resident, for every installed skill, whether or not you use it. It's the standing cost. Levels 2 and 3 are pay-as-you-go.
The visualizer below makes the desk literal. The bar is the model's context budget. Choose how many skills are installed, and pick how "deep" the active skill currently is — idle (only its Level 1 is loaded), triggered (Level 1 + 2), or deep in a task (Level 1 + 2 + 3). Compare it against the naive "load everything, always" world.
The tall bar is your context budget. Watch how little the "always-on" cost is under progressive disclosure even with many skills installed — and how the naive approach blows the budget almost immediately.
Let's do the arithmetic the picture is showing. Say a skill's Level 1 frontmatter is about 40 tokens and a full Level 2 body is about 5,000 tokens. With 30 skills installed:
Twelve hundred tokens versus a hundred and fifty thousand. The first leaves almost your entire desk free for actual work; the second doesn't fit on most desks at all. And notice the lovely property: when you actually use one skill, you pay its 5,000-token body — once, for that one skill — while the other twenty-nine stay at 40 tokens each. You only ever pay full price for the skill you're actively holding.
SKILL.md is always better." It feels thorough to pour every edge case into the body. But remember: the body is Level 2 — once the skill triggers, all of it lands on the desk. A bloated body means every invocation drags in pages you rarely need. The fix is to keep SKILL.md focused on the core workflow and push the rarely-needed detail down to Level 3 (references/), linked by name. A good rule of thumb: keep SKILL.md under ~5,000 words. Detail isn't lost — it's deferred.
This single idea — three levels, each loaded only when it earns its place — is why the folder has the shape it does, why the description matters so much (it's the always-on Level 1, our next chapter), and why testing later focuses on "does the right layer load at the right time."
We just established that Level 1 — the frontmatter — is the always-resident sliver of every skill. Now we zoom into it, because Level 1 carries the most consequential field you will ever write: the description. Get it right and your skill fires exactly when it should. Get it wrong and a perfect, beautifully-instructed skill sits in its folder, never loading, while you wonder why nothing happens.
Here's the mechanism, stated plainly so there's no mystery. When you give Claude a task, it does not read every installed skill to decide which to use — that would defeat progressive disclosure entirely. It reads only the descriptions (Level 1) and asks, for each: "does this description sound like it's about the task in front of me?" The skills whose descriptions match get their bodies (Level 2) loaded. The rest stay dormant.
This has a stark consequence worth pausing on: if a trigger word isn't in the description, the skill is effectively invisible for that query. The model can't match on instructions it never reads. So the description isn't marketing copy — it's the routing table. Every kind of request you want this skill to handle must leave a fingerprint in the description.
A good description has three parts:
The when is the part beginners skip and the part that matters most. "When to use it" should contain the literal phrases a user would actually type. Look at a strong example:
good — specific, with real trigger phrases
description: Analyzes Figma design files and generates developer
handoff documentation. Use when user uploads .fig files, asks for
"design specs", "component documentation", or "design-to-code handoff".
Notice it names the file type (.fig) and quotes the exact phrases ("design specs", "design-to-code handoff") a user says. Now the failures:
bad — three ways to be invisible description: Helps with projects. # too vague — matches everything and nothing description: Creates multi-page docs. # missing triggers — no "when" description: Implements the Project entity. # too technical — no phrase a user would type
Play with the mechanism directly. Below is a tiny "router": three installed skills, each with a description, and a box where you pick a user query. The simulator scores each description against the query (by shared keywords) and lights up the ones that fire. Then toggle the data-skill's description between vague and specific and watch its behavior flip.
Pick a query. Green = the skill's description matched and it loads; grey = dormant. This is a simplified keyword model of the real relevance judgement, but the lesson is exact: matches happen against the description, not the body.
Try the query "clean up this messy CSV" with the data-skill set to specific (its description mentions "CSV", "data cleaning", "dataset") — it fires. Now flip it to vague ("Helps with data") and run the same query — it goes dark, because "messy CSV" no longer overlaps with anything in the description. Same skill, same body, same task. The only thing that changed was the routing table, and the routing table is all the model gets to see at decision time.
SKILL.md body can rescue a description that lacks the user's trigger words. Write the body for the model that has already decided to use the skill; write the description for the model that is deciding whether to.
One more constraint, because the description lives in the system prompt: it must stay under 1024 characters and may contain no angle brackets (< or >). We'll see exactly why those characters are banned when we reach security in Chapter 9 — for now, just know the limit exists.
Notice the order we're doing things in. We understood the loading mechanism (Chapter 2) and the routing field (Chapter 3) before we wrote a word of instructions. That's deliberate, and it mirrors the single best piece of planning advice for skills: before writing any code, identify 2–3 concrete use cases your skill should enable. The use cases drive everything — the description, the instructions, even whether you need scripts at all.
What does a "concrete use case" look like? It's specific enough to test. Here's the canonical shape:
use case definition
Use Case: Project Sprint Planning
Trigger: User says "help me plan this sprint" or "create sprint tasks"
Steps:
1. Fetch current project status from Linear (via MCP)
2. Analyze team velocity and capacity
3. Suggest task prioritization
4. Create tasks in Linear with proper labels and estimates
Result: Fully planned sprint with tasks created
See how much falls out of this one card. The Trigger line is a first draft of your description's "when." The Steps are the spine of your instructions. Step 2 ("analyze velocity") hints you might want a references/velocity.md; the estimates in step 4 hint at a scripts/estimate.py. The use case is the seed the whole folder grows from.
To write a good use case, interrogate it with four questions: What does the user want to accomplish? What multi-step workflow does it require? Which tools are needed — built-in or MCP? What domain knowledge or best practices should be embedded? If you can answer those four, you can write the skill.
Anthropic observed that almost every skill falls into one of three categories. Knowing which one you're building tells you which techniques matter. The classifier below gives you example skills — drop each into the right bucket and see if your instinct matches.
Tap a category for the current example skill. Get it right and the next example appears.
Here are the three categories in full:
| Category | Used for | Real example | Key techniques |
|---|---|---|---|
| 1. Document & Asset Creation | Consistent, high-quality output: docs, slides, apps, designs, code. | frontend-design; the docx/pptx/xlsx skills. | Embedded style guides, template structures, quality checklists, no external tools needed. |
| 2. Workflow Automation | Multi-step processes that benefit from a consistent method, often spanning MCP servers. | skill-creator itself. | Step-by-step workflow with validation gates, templates, built-in review loops. |
| 3. MCP Enhancement | Workflow guidance layered on top of an MCP server's raw tool access. | Sentry's sentry-code-review. | Coordinates multiple MCP calls in sequence, embeds domain expertise, handles common MCP errors. |
Category 3 is where the MCP relationship from Chapter 0 becomes concrete. Think of it with the kitchen analogy: MCP is the professional kitchen — it gives Claude access to the tools, ingredients, and equipment (your Linear, your Notion, your database). A skill is the recipe — the step-by-step method for turning that raw access into something valuable. A connected MCP server with no skill is a fully-stocked kitchen handed to someone who's never cooked: all capability, no method. The skill supplies the method.
frontend-design skill produces polished UI from a spec using only Claude's built-in abilities — no MCP, no external tools. Which category is it?The skill has triggered. Its body — Level 2 — is now on the desk, and Claude is reading your instructions. This chapter is about making those instructions ones the model actually follows, because "the skill loads but Claude ignores it" is one of the most common complaints, and it's almost always a writing problem, not a model problem.
The body comes after the frontmatter. A workable skeleton:
SKILL.md body structure
# Your Skill Name
## Instructions
### Step 1: [First major step]
Clear explanation of exactly what happens.
## Examples
Example 1: [common scenario] → actions → result
## Troubleshooting
Error: [common message] → Cause → Solution
The governing rule for every line is: be specific and actionable. Compare these two ways of saying the same thing:
bad — vague
Validate the data before proceeding.
good — specific and actionable
Run `python scripts/validate.py --input {filename}` to check data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)
"Validate the data" leaves the model guessing what "validate" means, how, and what to do if it fails. The specific version names the exact command, the placeholder to fill in, and the recovery path for the two failures that actually happen. There is nothing left to interpret — and an instruction with nothing to interpret is an instruction that gets followed.
The widget below lets you feel this. Drag the "specificity" slider on a sample instruction and watch a (stylized) "Claude follows it correctly" rate respond. Vague instructions get interpreted differently each run; specific ones converge.
Slide from vague to specific and watch the instruction rewrite itself — and watch the consistency meter climb. (The meter is illustrative, but the relationship is real: ambiguity is variance.)
Four more techniques turn "loads but ignored" into "loads and obeyed":
## Important or ## Critical headers, and don't be shy about repeating a load-bearing rule.create_project, verify: project name is non-empty; at least one team member assigned; start date is not in the past."## Common Issues section that says, for "Connection refused": verify the MCP server is running, confirm the API key, reconnect — turns a dead end into a recovery.references/api-patterns.md for rate limiting, pagination, and error codes." This is progressive disclosure in action — the body stays lean and the detail loads only when reached.scripts/validate.py returns the same verdict every single time. This is exactly why the Office skills (docx, xlsx) lean on bundled scripts for their must-not-fail steps. Language for guidance; code for guarantees.
references/. (And note: nudges like "take your time, quality over speed, don't skip steps" tend to work better in the user's prompt than baked into SKILL.md.)
Everything so far — the folder, the three levels, the description, the categories, the instructions — comes together here. The Forge is a live skill builder. You type a name and a description, and it does what the real uploader does: validates every rule, shows you the exact error when you break one, and renders a preview of the resulting SKILL.md plus a picture of what loads at each level.
This is the moment to break things on purpose. Type a name with a capital letter or a space. Put an angle bracket in the description. Strip out the "when" so there are no triggers. The validators will turn red with the precise message the real system gives — the same messages you'll meet in the wild. Then fix them one by one and watch the skill go green and assemble itself.
name)SKILL.md preview:The Forge checks the rules we've accumulated, plus the few that live only in the fine print:
| Rule | Why it exists |
|---|---|
name is kebab-case | Lowercase + hyphens only. No spaces, capitals, or underscores — the folder and frontmatter must agree and parse cleanly. |
name isn't reserved | It must not start with claude or anthropic — those prefixes are reserved. |
No < or > anywhere in frontmatter | Security: frontmatter is injected into the system prompt, so angle brackets are banned to prevent instruction injection (Chapter 9). |
| Description has WHAT and WHEN | Without the "when" (trigger phrases), the skill under-triggers — it never loads when it should (Chapter 3). |
| Description < 1024 characters | It lives in the always-on system prompt; it has to stay small. |
File is named SKILL.md | Exact, case-sensitive. The uploader matches that precise string. |
Notice what the Forge does not ask you for: a model, a training set, an API key, a server. A skill that passes these checks is complete. That's the quiet radicalism of the format — the barrier to teaching Claude a new workflow is "can you write a paragraph and follow six naming rules," not "can you train a model."
(No quiz here — the Forge is the test. If you can drive every check to green and explain why each one exists, you've mastered Chapters 1–5.)
You have a skill that passes the Forge. Is it any good? "Passes validation" and "works well" are different claims, and the gap between them is testing. The reassuring news: skills are easy to test, because the unit of testing is just "run a query and watch." You can do it by hand in Claude.ai with zero setup, script it in Claude Code for repeatability, or build full evaluation suites via the skills API — pick the rigor that matches your stakes. A skill for your team of five needs less than one shipped to ten thousand enterprise users.
Effective testing covers three areas. The first — and the one most worth automating — is triggering: does the skill load at the right times? You write a set of queries that should fire it and a set that should not, and you measure. This is where the description from Chapter 3 lives or dies, so let's make the iterate-on-the-description loop tangible.
Below is a triggering test harness. There's a fixed suite: some "should trigger" queries and some "should NOT trigger" queries. You edit the skill's description — toggle keywords on, add a negative trigger — and the harness re-scores every query and reports your pass rate. Your job: get it to 100% green by tuning only the description.
Each row is a test query. A green check means the skill behaved correctly on it (fired when it should, stayed quiet when it shouldn't). Flip the description controls and watch the score move.
Run the math the harness is doing. With ten test queries, if nine behave correctly, your trigger accuracy is:
The aspirational target is roughly 90%+ on relevant queries. The two ways to fail map onto the two controls in the harness, and onto the two signals you watch for in the wild:
| Symptom | Signal | Fix |
|---|---|---|
| Under-triggering | Skill doesn't load when it should; users keep enabling it by hand; "when do I use this?" questions. | Add detail and nuance to the description — especially the keywords and technical terms users actually type. |
| Over-triggering | Skill fires on unrelated queries; users disable it; confusion about its purpose. | Add negative triggers and be more specific: "Do NOT use for simple data exploration; use the data-viz skill instead." |
The other two test areas round it out. Functional tests verify the skill produces correct outputs: valid results generated, API calls succeed, error handling works, edge cases covered. Performance comparison proves the skill actually beats the no-skill baseline — and the numbers here are the entire reason skills exist. A real before/after:
| Without skill | With skill | |
|---|---|---|
| Back-and-forth messages | 15 | 2 clarifying questions |
| Failed API calls | 3 (each needing retry) | 0 |
| Tokens consumed | 12,000 | 6,000 |
Half the tokens, zero failed calls, thirteen fewer round-trips — for the same task. That table is the context-tax meter from Chapter 0, finally paid off.
And skills are living documents. The skill-creator skill — built into Claude.ai and available for Claude Code — can generate a first draft from a description, flag vague descriptions and missing triggers, and help you fold real-world failures back in: "Use the issues identified in this chat to improve how the skill handles [edge case]." Iterate; don't expect perfection on draft one.
You now know how to build a skill. But certain shapes recur so often that early builders converged on five named patterns. These aren't rigid templates — they're proven approaches you can lean on. Before them, one framing choice that decides which pattern fits.
Think of Home Depot. You can walk in with a problem — "I need to fix a kitchen cabinet" — and an employee points you to the right tools. Or you can walk in already holding a tool — "I bought this drill" — and ask how to use it for your job. Skills split the same way. Problem-first: "set up a project workspace" → the skill orchestrates the right MCP calls in the right order; the user describes outcomes. Tool-first: "I have Notion connected" → the skill teaches the optimal workflows on top of access the user already has. Most skills lean one way; knowing which guides your pattern choice.
Step through each pattern in the explorer. Pick a pattern; the diagram animates its phases so you can watch the data and control flow.
Choose a pattern, then press Step to advance through its phases. Watch where data passes from one stage to the next.
The five, with when each fits:
scripts/check_report.py → fix the issues it flags → re-validate → repeat until the quality bar is met. Key techniques: explicit quality criteria, a validation script, and — crucially — knowing when to stop iterating.The onboarding example (pattern 1) hides the detail that makes sequential workflows non-trivial: dependencies. Step 3, "create subscription," needs the customer_id produced back in step 1, "create account." That data dependency is exactly why the steps can't be reordered or run in parallel — and why "explicit step ordering" and "validation at each stage" are listed as the key techniques. The skill's job is to thread that customer_id from step 1 through to step 3 without dropping it.
Your skill works. Now you get it into hands — safely — and we close with a one-page cheat sheet. Three distribution routes exist today (January 2026). For an individual user: download the skill folder, zip it if needed, and upload via Claude.ai → Settings → Capabilities → Skills — or drop it in your Claude Code skills directory. For an organization: admins can deploy skills workspace-wide, with automatic updates and centralized management. For applications: the API exposes a /v1/skills endpoint and a container.skills parameter on Messages requests (it requires the Code Execution Tool beta, the secure sandbox skills run in), and it works with the Claude Agent SDK.
When to use which? End users, manual testing, and ad-hoc work belong on Claude.ai or Claude Code. Programmatic use, production deployments at scale, and automated agent pipelines belong on the API. Anthropic has also published Agent Skills as an open standard — like MCP, the same skill should work across tools and platforms; a skill that depends on one platform's features can say so in its compatibility field.
Now the security model, because it explains a rule we've deferred twice. Recall that the frontmatter (Level 1) is always injected into Claude's system prompt. That makes it a sensitive surface: anything in it is, in effect, an instruction the model sees with high trust. So two restrictions are enforced:
<...> content could be crafted to look like an injected instruction or tag and hijack the model's behavior. Banning < and > outright removes that attack surface. The parser also uses safe YAML (no code execution), and names beginning with claude or anthropic are reserved so a skill can't impersonate a first-party one. These aren't arbitrary style rules — each one closes a specific injection or spoofing door.
One more operational caution: large-context issues. If responses feel slow or degraded, the usual causes are a SKILL.md that's too large (keep it under ~5,000 words; push detail to references/), too many skills enabled at once (re-evaluate if you're past ~20–50), or content that isn't using progressive disclosure properly. The whole architecture only pays off if you keep Level 1 lean and let Levels 2–3 load on demand.
Before you ship, run the pre-flight checklist. Tick each box — the meter fills as you go.
The real before/after-upload checklist. Tap items you've done; the readiness ring fills.
| Thing | The rule |
|---|---|
| What a skill is | A folder. SKILL.md (required) + optional scripts/, references/, assets/. |
| Progressive disclosure | L1 frontmatter (always loaded, tiny) → L2 body (when relevant) → L3 files (on demand). |
| The description | WHAT + WHEN + capabilities. Only part read at routing time. < 1024 chars, no < >. |
| Name rules | kebab-case, no spaces/caps/underscores, not starting with claude/anthropic. |
| Three categories | Asset creation · Workflow automation · MCP enhancement. |
| Instructions | Specific & actionable, critical stuff on top, error handling, link references. Code for guarantees. |
| Under-triggering | Add keywords & nuance to the description. |
| Over-triggering | Add negative triggers; be more specific. |
| MCP + Skills | MCP = the kitchen (tools). Skill = the recipe (method). What vs. how. |
| Five patterns | Sequential · Multi-MCP · Iterative refinement · Context-aware selection · Domain intelligence. |
Skills are the knowledge layer of the AI harness. The pieces around them:
SKILL.md body.references/ layer.SKILL.md, a description that triggers on the right phrases and stays quiet on the wrong ones, lean instructions with detail pushed to references/, the right pattern for the job — and explain why each rule exists down to "the frontmatter is in the system prompt, so no angle brackets," then you can teach this. That was the whole goal: not to know about skills, but to be able to build one.
"Teach Claude once and benefit every time." — the entire premise, in seven words.
< >) in a skill's frontmatter?