Module 5 — Skills: teaching Claude a procedure

← Module 4 | Index | Next: Module 6 →

A skill is a reusable packet of know-how. It teaches Claude how to do a specific kind of task — make a PowerPoint, fill a PDF form, follow your company’s report format — including any step-by-step instructions and helper scripts it needs.

What a skill is, physically

A folder containing a file named SKILL.md, plus optionally some scripts, templates, or reference files. The SKILL.md starts with a small header (called “frontmatter”) and then the instructions:

---
name: weekly-report
description: Use when the user wants to generate the
  weekly sales report in the company's standard format.
---

Step 1: Pull the numbers from the sales sheet...
Step 2: Format them into the template at ./template.docx...

The two header fields matter enormously:

name — a short identifier.
description — a plain-English summary of when this skill should be used. This is the part Claude reads to decide whether the skill is relevant.

How does Claude decide which skill to load?

The mechanism is called progressive disclosure, and it’s clever precisely because of the context-window limits from Module 4. Here’s the flow:

At the start, Claude only sees the names and descriptions of the available skills — not their full contents. This is cheap: a list of one-line summaries barely uses any desk space.
When your request comes in, Claude matches it against those descriptions. If you ask “make me a slide deck of Q3 results,” and there’s a skill whose description says “use this when creating presentations,” that’s a match.
Only then does Claude load the full skill — opening the complete SKILL.md and pulling its detailed instructions onto the desk. The heavy content arrives only when needed.

This is why a good description is everything. The skill could contain perfect instructions, but if its description doesn’t clearly say when to use it, Claude won’t know to reach for it. Writing skills is really an exercise in writing sharp descriptions.

A few more facts

Skills are model-invoked. Claude decides to use them based on the match above — you don’t have to name a skill explicitly (though you can).
Skills can bundle scripts. A skill isn’t limited to text instructions; it can ship a Python script that Claude runs. This is how, for example, the spreadsheet skill reliably produces real .xlsx files instead of guessing.
Skills stack with everything else. A skill might tell Claude to use a particular tool, or follow a format defined in a template file sitting next to it.
Where they live: your own skills go in .claude/skills/; others arrive via plugins (Module 11). Both Claude Code and Cowork support them.

The mental model

A skill is a recipe card in a box. Claude reads the labels on all the cards (descriptions), and only pulls out the full recipe (the SKILL.md body) for the dish you actually ordered.

← Module 4 | Index | Next: Module 6 →