What Are Claude Skills? How They Actually Work

Claude Skills are folders of instructions, scripts, and reference files that Claude loads automatically the moment a task matches what the skill describes. You write the workflow once — how you format a report, how you structure a proposal, how you want a spreadsheet built — and Claude retrieves it exactly when it is relevant, without you re-explaining it in every new conversation.

This guide covers what skills actually are, how they differ from prompts, Projects, and MCP servers (people mix these up constantly), and how to build your first one in about 10 minutes. If you want the fundamentals of instructing Claude well before you get here, our Claude prompting guide is the right starting point.

What Claude Skills actually are

A skill is a folder that contains at minimum one file — SKILL.md — with a short description of when to use it and a body of instructions for what to do. Claude reads the description at the start of a session, and if your current task matches it, Claude loads the full instructions and follows them. Skills can also bundle scripts, templates, and reference documents that Claude opens only when the instructions tell it to.

The point of a skill is repeatability. A prompt gets your task done once. A skill gets the same kind of task done the same correct way every time, across every conversation, without you rebuilding the instructions from scratch — because the instructions live in a file, not in your memory of what you typed last time.

Skills vs prompts vs Projects vs MCP: what is actually different

A prompt is a one-time instruction for a single conversation. A Project is a persistent workspace with a knowledge base and standing instructions scoped to one body of work. An MCP server gives Claude a new tool or a new data source it did not have before. A skill is portable, reusable expertise — a specific "how" that follows Claude across conversations, Projects, and even different apps, rather than staying locked to one workspace.

The clearest way to separate them: Projects tell Claude what it needs to know about a specific piece of work. MCP gives Claude something it can do — query a database, read a calendar, hit an API. Skills tell Claude how to do a specific kind of task well, and that instruction set is reusable anywhere the skill is installed.

These are not competing choices — most serious setups use all four together. A Project holds the client's files, an MCP connector lets Claude pull live data from a tool you use, and a skill sitting on top tells Claude exactly how to turn that data into the report you want, formatted the way you want it, every time.

How Claude decides which skill to use

Claude does not load every installed skill's full instructions into every conversation — that would waste context on skills you are not using right now. Instead it uses a system called progressive disclosure, which keeps skills nearly free until the moment they are actually needed.

There are three levels. First, the skill's name and description sit in Claude's system prompt at all times, costing roughly 100 tokens per skill regardless of how many you have installed — that is just enough for Claude to recognize "this task matches that skill." Second, once Claude decides a skill applies, it loads the full SKILL.md body: the actual step-by-step instructions. Third, anything the skill bundles beyond that — scripts, templates, longer reference documents — only gets opened if the instructions explicitly point Claude to it. A skill with a 500-line reference file costs you nothing extra unless that specific task needs that specific file.

This is why you can have dozens of skills installed without slowing anything down or degrading response quality on unrelated tasks — the skills you are not using stay dormant at the cost of a single line of metadata each.

What is inside a skill folder

Every skill needs a SKILL.md file with YAML frontmatter — at minimum a name and a description — followed by a markdown body with the instructions Claude follows. That is the entire required structure. More elaborate skills add a scripts/ folder for executable code, a references/ folder for documentation Claude reads only when it needs it, and an assets/ folder for templates or boilerplate files the skill produces.

---
name: weekly-client-report
description: Use when drafting a weekly status report for a client engagement. Formats findings, wins, blockers, and next steps in our standard structure.
---

# Weekly client report

When asked to draft a weekly report, follow this structure exactly:

1. One-paragraph summary — the single most important update first.
2. Wins this week — bullet points, each with a concrete result.
3. Blockers — what is stuck, why, and what is needed to unstick it.
4. Next week's priorities — 3 items maximum, ranked.

Rules:
- No filler sentences. Every line should be information the client needs.
- Pull specific numbers from any data the user pastes in — never round vaguely.
- If a section has nothing to report, write "Nothing to flag" instead of
  inventing content to fill the space.

That is a complete, working skill. Save the description well and Claude will pull this structure into any conversation where you ask for a weekly client report — no re-pasting the format, no forgetting a section, no drift as different team members write reports differently.

Build your first skill in 10 minutes

You do not need to hand-write YAML frontmatter or study a spec to ship a working skill today. The fastest path is to describe the recurring task to Claude in plain English and let it draft the SKILL.md for you, then you refine it.

Here is the prompt for step 2. Fill in the brackets and Claude will return a complete SKILL.md draft you can save and upload directly.

I want to turn a recurring task into a Claude skill. Write a complete
SKILL.md file for it — YAML frontmatter with a name and a description
specific enough that you would know exactly when to load this skill,
followed by clear step-by-step instructions in the body.

THE TASK: [describe what you do repeatedly, e.g. "turning raw meeting
notes into a client follow-up email"]

THE FORMAT I WANT EVERY TIME: [describe the structure, tone, sections,
or rules you always apply — the things you currently have to re-explain]

THINGS THAT GO WRONG WHEN I DO THIS MANUALLY: [common mistakes or
inconsistencies you want the skill to prevent]

Keep the description precise enough to avoid the skill triggering on
unrelated tasks. Return only the finished SKILL.md content.

For a longer walkthrough — including when to add scripts or reference files, and how to structure a skill with multiple sub-tasks — see our dedicated guide on how to build a Claude skill. If you would rather start from something proven than build from zero, our roundup of the best Claude skills covers the ones worth installing first.

Where skills work: claude.ai, Cowork, and Claude Code

Skills are not locked to one product — the same SKILL.md format works across Claude's apps, though the install path differs by surface. In the claude.ai app, skills are managed under your customization settings, where you upload a zipped skill folder and Claude reads the SKILL.md automatically. In Cowork, Anthropic's agentic desktop workspace for non-developers, skills sit alongside folder scoping, connectors, and scheduled tasks as one of the building blocks you combine to automate a job end to end.

Claude Code — the command-line and IDE-integrated coding agent — uses the same skill format for developer workflows: linting conventions, deployment checklists, code review standards, and repo-specific rules. If you write code or run a technical workflow day to day, our Claude Code skills guide goes deeper on that surface specifically, including how project-scoped skills differ from personal ones. The official docs at code.claude.com cover the exact file locations for that environment.

Team and Enterprise plans add one more layer: an organization owner can enable skill sharing so a skill one person builds and refines becomes available to the whole workspace, instead of staying stuck on one person's account.

When to build a skill, and when a skill is the wrong tool

Build a skill when you catch yourself re-explaining the same structure, rules, or format for the third time — that repetition is the signal. A skill is the wrong tool when the task is genuinely one-off (just write the prompt), when what you actually need is Claude reaching a live system it cannot currently touch (that is an MCP connector, not a skill), or when the context is really about one specific client or project rather than a repeatable method (that belongs in a Project's knowledge base instead).

A useful test: if you deleted the skill tomorrow, would you have to retype the same paragraph of instructions into your next ten conversations? If yes, it was worth building. If the task will not come up again, a skill just adds a file you never reopen.

Frequently asked questions

Do I need to know how to code to build a Claude skill?

No. A SKILL.md file is plain markdown with a short YAML header — no programming required. Scripts are optional, and most useful skills for non-technical work are pure instructions with no code at all.

Can a skill call an MCP tool or is that a separate thing?

A skill's instructions can absolutely tell Claude to use a tool an MCP connector provides — the two are complementary, not competing. The MCP server supplies the capability; the skill supplies the procedure for using it correctly and consistently.

Are Claude Skills the same thing as custom instructions?

Not quite. Custom instructions in a Project apply everywhere inside that one Project, all the time. A skill only loads when its description matches the task at hand, and it travels with you outside any single Project — that targeted, portable loading is the whole point of the design.

Will installing many skills slow Claude down?

Not meaningfully. Because of progressive disclosure, an unused skill costs only its short description in the system prompt — roughly 100 tokens — until the moment Claude decides it is relevant. Dozens of installed skills add negligible overhead to unrelated conversations.

Skills are the piece that turns Claude from a tool you re-brief every session into one that already knows how you like things done. Start with the one task you retype most often, draft it with the prompt above, and refine the description once you see how Claude triggers it. Everything else — Projects, MCP, more skills — stacks on top of that foundation once it is working.