A Claude Code skill is a folder containing a SKILL.md file — YAML frontmatter plus Markdown instructions — that teaches Claude how to perform a specific, repeatable task. Claude reads the skill and follows it inside your current session. The instructions load only when the skill is relevant, so a long procedure costs almost nothing until you actually need it.
That single sentence covers most of what people are confused about. The rest of this piece unpacks the anatomy, then draws the lines between skills, plugins, subagents, and MCP — the four terms that get tangled together most often.
I maintain lich-skills, an open collection of skills for Claude Code, Codex, and Gemini CLI, and curate the OrangeBot skills directory. So this is the insider version: what a skill is, and — just as important — what it is not.
Anatomy of a Skill
A skill lives in a directory, typically .claude/skills/<skill-name>/, and the one required file is SKILL.md. Per the official docs, that file has two parts:
- YAML frontmatter between
---markers. The two fields that matter most arenameanddescription. Thedescriptionis load-bearing: it is the short blurb Claude scans to decide whether to pull the skill in. Metadata is cheap to read; the body is expensive to load — keeping them separate is the whole design. - A Markdown body with the actual step-by-step instructions, examples, and any gotchas.
A skill folder can also hold supporting files — scripts, templates, reference docs — that the instructions point to. This is often called progressive disclosure: Claude sees the description first, loads the body when the task matches, and only reaches for bundled files when a step calls for them.
You invoke a skill directly by typing /skill-name, or Claude loads it automatically when the description matches what you are doing. (As of 2026, Claude Code's custom slash commands and skills have effectively merged — a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both give you /deploy.) Claude Code follows the Agent Skills open standard, so the same SKILL.md can work across multiple tools, with Claude Code layering on extras like invocation control and subagent execution. Exact optional-field names and any size limits shift between releases, so check the docs for the version you are on rather than trusting a blog snapshot.
Skills vs Plugins vs Subagents vs MCP
Here is the mental model that untangles it: skills, subagents, and MCP are capabilities; a plugin is how you package and ship them. They are not competitors on one axis.
| What it is | Where it runs | Best for | |
|---|---|---|---|
| Skill | A SKILL.md procedure Claude reads and follows | Your current session (same context) | Teaching Claude how to do a repeatable task |
| Subagent | A separate worker with its own context and token budget | An isolated context; returns only a summary | Offloading heavy work so your main thread stays clean |
| MCP server | A protocol connection to an external system | An outside service Claude talks to | Giving Claude access to data or tools (DBs, APIs) |
| Plugin | A package bundling skills, subagents, hooks, and MCP configs | Installed once from a marketplace | Distributing the above to other projects or teammates |
Two distinctions do most of the work:
- Skill vs subagent. A skill runs in your session — whatever it reads stays in your main context. A subagent is handed a task, works in its own context with its own tools, and hands back only a result. Use a skill to teach Claude a method; use a subagent when you want the work done elsewhere so your thread does not fill up with intermediate noise.
- Skill vs MCP. A skill is knowledge — instructions in Markdown. MCP is transport — a live connection to something external. A skill can tell Claude how to use an MCP server, but it cannot replace one; if Claude needs to reach your database, that is MCP's job, not a skill's.
And what are Claude Code plugins? A plugin solves distribution. When your skill is good enough that you want it in a second project or on a teammate's machine, you wrap it — plus any subagents, hooks, or MCP servers it depends on — into a plugin and install it with one command. For a deeper take on the transport layer, see what is an MCP server.
When to Use a Skill
Reach for a skill the moment you notice yourself pasting the same instructions into chat more than twice. Concrete triggers:
- You keep re-explaining your commit-message format or release checklist.
- A section of
CLAUDE.mdhas quietly grown from a fact into a multi-step procedure. - You have a workflow — a migration, a deploy sequence, a report format — that Claude should follow the same way every time.
A skill is the right tool when the value is knowing how. If the value is fresh external data, you want MCP. If the value is isolation, you want a subagent. And if the value is sharing, you want a plugin around your skill.
Where to Find and Install Skills
You do not have to write every skill from scratch. Browse the OrangeBot skills directory for curated, working examples you can read, adapt, and install — each one is a real SKILL.md you can learn the format from by inspection.
To go deeper:
- Building your own? Start with how to write a Claude Code skill for the frontmatter, the description-writing craft, and the folder layout.
- Looking for the good ones? See the best Claude Code skills of 2026 for a hand-picked shortlist.
The short version: a skill is the cheapest, most portable way to hand Claude a repeatable procedure. It is not a subagent, not an MCP server, and not a plugin — it is the knowledge those things carry, package, or connect to.
Want a weekly, hype-free read on Claude Code skills, agentic tooling, and what actually shipped? Subscribe to the OrangeBot Weekly — one calm digest, no inbox spam.