What Are Claude Skills? A Plain-English Explainer
Claude skills are reusable SKILL.md modules that teach Claude how to do one kind of work. They load on demand, persist across sessions, and follow the open Agent Skills standard.
A Claude skill is a reusable module (a SKILL.md file plus optional references and scripts) that teaches Claude how to do one kind of work. It loads on demand: metadata stays in context always, the body arrives when the trigger fires, and supporting files load only when the skill asks for them. Skills persist across sessions, version in git, and follow the open Agent Skills standard.
If you want to go straight to building one, the complete guide to creating Claude skills covers the full anatomy.
What a Claude skill actually is
A skill is not a prompt. It is a versioned, file-based module that lives in your project’s .claude/skills/ directory (or ~/.claude/skills/ for skills you want globally available). The core file is SKILL.md, a markdown document that gives the agent a name, a one-line description, and instructions for how to work. References, scripts, and asset files sit alongside it.
The description is the triggering mechanism. At session start, Claude reads the name and description of every skill in scope. When the description matches your intent, the skill body loads. No match, no load. Nothing fires unless the cue is there.
Progressive disclosure handles the rest.
Why skills exist: LLMs are stateless
Every Claude session starts blank. There is no memory, no carry-over from yesterday’s work, no awareness of decisions made last week. That is a design property of LLMs, not a bug in Claude specifically.
Without skills, that statelessness forces one of two bad outcomes. You paste the same long context block every session (prompt debt that grows and drifts over time) or you accept that the agent’s behavior will vary session to session because the instructions are not always there.
A skill is the answer to both. Write the method once, in a versioned file, and it loads precisely when the work fits. Skills exist for anything you do repeatedly but do not want to re-explain: code review, offer evaluation, content formatting, git workflows, SEO audits. The constraint is only that the task has a consistent shape. If you can describe it in one sentence, you can skill it.
How a skill loads: three tiers
The loading model is what separates a skill from a markdown file you paste into context. Three tiers, each conditional on the one before it.
The three loading tiers
- T1
Metadata: always in context
The skill's name and description load at the start of every session. This is how the model knows a skill exists and what kind of work it handles. It costs almost nothing, a line or two per skill.
- T2
SKILL.md body: loads on trigger
When the description matches the user's intent, the full SKILL.md body loads. This is where instructions, output modes, and the reference loading map live: the method the agent will follow.
- T3
References and scripts: loads on demand
Supporting files (distilled knowledge, decision checklists, templates, scripts) load only when SKILL.md's loading map tells the model to fetch them. Nothing auto-loads. The skill decides.
A skill with twenty reference files costs one metadata line per session until it fires. Then only the references the current task needs enter context. The loading map tells the model exactly what to read. Everything else stays on disk.
What goes inside a skill
Most skills have three parts: the router (SKILL.md), the knowledge base (references/), and optional automation (scripts/). The router is mandatory. The rest grow as the skill matures.
Skill anatomy
- 1
- SKILL.md
- 1-20
- references/
- 0+
- scripts/
- 0+
- assets/
the router: name, description, instructions, loading map
distilled knowledge split by decision domain
shell or Python helpers the skill can invoke
templates, schemas, or example output files
Inside SKILL.md, the loading map is the part most people skip and then wonder why the skill underperforms. It is a table (or a short list) that maps types of questions to the reference files that answer them. Pricing question loads the pricing reference. Code review loads the review checklist. Without the map, the agent guesses.
The description line is the other thing worth getting exactly right. It is a trigger phrase, not documentation. Write it to match the sentence you would naturally say when you need this skill. Vague descriptions miss. Precise ones fire every time.
Skills follow an open standard
Claude skills implement the open Agent Skills standard, which means the architecture is not proprietary to Claude Code. The same SKILL.md module (same name, description, references, and loading map) is portable to any agent runtime that supports the standard.
I have been building skills in my own library at ~/Work/my-second-brain/.agents/skills/. Persona skills like alex-hormozi handle offer evaluation. A lifeos-* system covers personal operating tasks: weekly reviews, planning rhythms, decision logs. Each one is a self-contained module: one router, a handful of distilled references, a tight loading map. None of them are clever. They are just method that loads on demand.
For real examples of what these look like, see Claude skill examples from my own library. For the boundary between skills and MCP subagents (a question that comes up fast once you start building), see Claude skills vs MCP subagents.
The short version
A Claude skill is a versioned, file-based module that teaches an agent how to do one kind of work. Metadata in context. Body on trigger. References on demand. No prompt debt, no session drift, no re-explaining the same thing every Monday.
Skills exist because LLMs forget. A good skill does not.
If you are ready to build your first one, the complete guide to creating Claude skills walks through every decision: file structure, loading map, references, and how to test whether any of it actually worked.
Frequently asked questions
What is a Claude skill in plain English?
A Claude skill is a reusable module (a SKILL.md file plus optional references and scripts) that teaches Claude how to do one kind of work. It loads on demand, persists across sessions, and versions in git like any other file.
The method persists in a file. It enters context only when the work needs it.
What is the difference between a Claude skill and a prompt?
A prompt is a session instruction: you paste it, use it, and paste it again next time. A skill is a persistent, file-based module that loads automatically when the description matches your intent.
The prompt decays between sessions. The skill persists.
How does Claude know when to trigger a skill?
The description line in SKILL.md is the trigger. Claude reads all skill metadata at session start. When the description matches the user's intent, the full SKILL.md body loads. No match, no load.
What is 'progressive disclosure' in the context of Claude skills?
Progressive disclosure is the loading model: metadata (name and description) stays in context always; the SKILL.md body loads when the trigger fires; reference files load only when the skill's loading map says to fetch them.
Nothing auto-loads. Only what the current task needs enters context.
What goes inside a SKILL.md file?
At minimum: a name, a one-line description (the trigger), and instructions for the agent. A mature skill also includes a loading map, a table that routes types of questions to the reference files that answer them. The loading map is the part most people skip and later regret.
Can I use Claude skills outside Claude Code?
Yes. Skills follow the open Agent Skills standard, which means the same SKILL.md module is portable to any agent runtime that supports the standard.
The method lives in the file, not in the tool.
Where does Claude look for skills?
Project-level skills live in the project's .claude/skills/ directory and are scoped to that project. User-level skills live in ~/.claude/skills/ and are available in every session. Both are plain markdown files the agent reads at session start.
Do skills slow down the model or burn through context?
No more than they need to. Metadata is minimal: a name and description per skill. The SKILL.md body loads only on trigger. Reference files load only when the loading map calls for them.
A skill with twenty reference files costs roughly one metadata line per session until it fires. Then only the relevant references enter context.
What kinds of tasks are worth building a skill for?
Anything you do repeatedly with a consistent shape: code review, offer evaluation, content formatting, SEO audits, git workflows, weekly planning. If you can describe the task in one sentence and you have done it more than a handful of times, it is worth a skill.
One-off tasks are not worth it. The payoff is reuse across sessions.