Ask ten people what a "Claude Skill" is and you'll get ten different guesses — a prompt template, a plugin, an MCP server with a different name. It's none of those. A Skill is a folder Claude only opens when the task actually calls for it.
What a Skill actually is
A Skill is a package: a SKILL.md file with instructions, plus (optionally) scripts, templates, or reference docs sitting next to it. Claude sees a one-line description of every Skill it has access to up front — cheap, small, always in context. It only reads the full SKILL.md (and any bundled files) when the current task matches that description. That's the whole trick: progressive disclosure. You can hand Claude a hundred procedures without paying the context cost of a hundred procedures on every single turn.
Compare that to a system prompt. A system prompt is always loaded, on every request, whether the current task needs it or not — so it's the wrong place for "here's exactly how we format a quarterly report" if quarterly reports come up once a month. A Skill sits there at near-zero cost until the one turn where it's relevant, then loads in full.
Skills vs MCP — different jobs
These get confused because both showed up in the same era of Claude tooling, but they solve different problems:
- MCP (Model Context Protocol) connects Claude to something external and live — a database, a ticketing system, a file server, an API. It's a protocol: you run a server, Claude talks to it over that protocol, and it can call tools or read resources the server exposes. See Connecting Claude Code to anything with MCP and Build your first MCP server in 30 minutes for the hands-on version.
- A Skill packages procedural knowledge — how you want a task done, written by you, read by Claude when relevant. No server, no protocol, no external system. It's closer to a very well-organized internal wiki page than an integration.
A useful rule of thumb: if the thing lives outside Claude and changes independently (your CRM, your codebase, a live API), that's MCP. If the thing is "here's our house style for X" or "here's the exact sequence of steps for Y," that's a Skill.
They compose, too — a Skill's instructions can tell Claude to reach for a specific MCP tool at the right step. Neither replaces the other.
Where you'll run into them
In Claude Code, Skills live in your project or personal config, and Claude reaches for one automatically when your request matches its description — no slash command required, though some teams also expose a Skill as one (see 10 Claude Code slash commands you should know). It's the mechanism behind Claude Code "knowing how you like things done" without you re-explaining it every session.
On the API, the Skills API itself — uploading and managing skill packages via client.skills.* — is fully out of beta, no special header required. Using a skill inside a live request currently rides on the code execution surface: you pass container: {"skills": [...]} on client.beta.messages.create, along with the code_execution tool and its beta header. This is how Claude generates a real .docx, .pptx, or .xlsx file mid-conversation instead of describing one in text — the sandbox has python-docx, python-pptx, and friends pre-installed, and the Skill tells it the house format to use.
When to actually write one
Write a Skill when you catch yourself re-explaining the same procedure to Claude across sessions — a specific report format, a checklist your team always runs, a "here's how we structure a PR description" convention. If you're only using it once, it's not worth packaging. If it's the fifth time you've typed some version of the same instructions, that's the signal.
Where to go next
- Connecting Claude Code to anything with MCP — the protocol-based counterpart to Skills.
- Claude Agent SDK vs Claude API — how much do you build yourself? — Skills show up in both layers; this is the broader decision this piece sits inside.
- Automate your workflow with Claude Code hooks — the other main way to make Claude Code repeat what you want, without a Skill.