Claude Skills – Anthropic's tool framework explained
Technical scope Major labs & flagship models, anthropic, vendor-analysis
Claude Skills is Anthropic's framework for packaging a reusable capability – a set of instructions, reference material and code – into a folder that Claude loads on demand when the task at hand calls for it. The mechanism is deliberately plain: a folder contains a Markdown file called SKILL.md, plus whatever supporting files the capability needs, and Claude reads the SKILL.md when the model judges it relevant to what you are asking. That design choice, favouring prose and files over bespoke protocol plumbing, is what separates Skills from the other two ways you can extend Claude, and it is the reason a developer needs a clear mental model of where Skills sit before deciding to build one.
Anthropic introduced Skills in late 2025 as a way to give Claude durable, portable competence that survives across conversations and across the surfaces where Claude runs – the Claude apps, the API, and the agentic coding tool Claude Code. Because the feature is new and still evolving, treat specific availability, pricing and tier details here as time-sensitive and check the current Claude Skills documentation before you commit a design to them.
Claude Skills in one paragraph
A Skill is a folder. Inside it sits a SKILL.md file written in Markdown, with a short block of metadata at the top – a name and a description – followed by instructions in plain prose. Alongside SKILL.md you can place anything else the capability needs: additional reference documents, example files, scripts, templates. When you give Claude a task, the model scans the descriptions of the Skills available to it, decides which are relevant, and pulls the matching SKILL.md into context to follow its instructions. The developer does not call a Skill explicitly on each request; relevance drives loading. That single idea – capability as a self-describing folder, auto-selected by the model – is the whole of Skills.
How Skills work architecturally
The architecture rewards understanding because it explains both the strengths and the limits of the framework.
At the top of SKILL.md is a metadata header, typically YAML front matter, carrying at minimum a name and a description. The description is load-bearing: it is what Claude reads first, cheaply, to decide whether the Skill is worth opening at all. Think of it as the index entry rather than the chapter. A vague description ("helps with documents") will be matched inconsistently; a precise one ("generates branded PDF invoices from a line-item list, following the ACME finance template") gives the model a sharp signal about when to reach for it.
Below the header comes the body, which is instruction text Claude follows once the Skill is loaded. This is where you encode the workflow: the steps, the conventions, the gotchas, the preferred output format. Because it is prose, you write it the way you would brief a competent colleague, not the way you would define a JSON schema.
The supporting files matter for a subtler reason – progressive disclosure. Rather than cramming everything into one enormous SKILL.md that burns context whether or not the detail is needed, you can keep the main file lean and point to deeper reference files that Claude reads only when it needs them. A Skill for, say, a company's brand guidelines might have a short SKILL.md that describes the task and tells Claude to consult colours.md or tone-of-voice.md when relevant. This keeps the always-loaded footprint small while letting the full corpus of knowledge sit one hop away. The pattern matters because context is finite and expensive, and a Skill that loads its entire library on every invocation is a Skill that competes with the user's actual task for room in the window.
Where Skills can execute code – in environments that provide a sandbox, such as Claude Code or the code-execution settings in the apps – the supporting files can include scripts Claude runs rather than merely reads. That turns a Skill from documentation into a small, packaged tool. The availability of execution depends on the surface and its configuration, so verify what your target environment permits.
Skills vs MCP vs function calling
The most common confusion among developers evaluating Skills is to treat them as a competitor to Model Context Protocol or to classic function calling. They are not competitors; they operate at different layers, and a sophisticated system often uses all three.
Function calling – sometimes called tool use – is the lowest layer. On a given request, you hand the model a set of tool definitions with typed parameters, the model decides whether to call one, emits a structured call, your code executes it, and you feed the result back. It is per-request, schema-driven, and ephemeral: the tools exist for the duration of that exchange because you supplied them in that exchange. Function calling is how Claude touches the outside world within a single turn.
Model Context Protocol, covered in depth in our explainer on MCP, is a connection layer. An MCP server exposes tools, resources and prompts over a standard protocol, and any MCP-aware client – Claude among them – can connect to it and discover what it offers. MCP standardises how a model reaches a live system: a database, a ticketing platform, a file store, an internal API. The point of MCP is interoperability and persistent connection to running services. Under the hood, the tools an MCP server exposes are still surfaced to the model through the function-calling mechanism; MCP is the plumbing that gets them there in a vendor-neutral way.
Skills are the content-and-instruction layer. A Skill does not, in itself, open a socket to a running server or define a typed function signature. It packages knowledge and procedure – how to do a thing, in what order, to what convention – as text and files the model reads. The distinction is cleanest stated as a sentence an engineer can keep in mind: function calling is what the model can do this turn, MCP is what live systems the model can reach, and a Skill is what the model knows about how to do the job well.
These compose naturally. A Skill for reconciling invoices might instruct Claude to query an accounting system – reached over MCP – and format the output as a report, with the formatting conventions and edge-case handling spelled out in the SKILL.md and its reference files. The Skill supplies the expertise and the method; MCP supplies the connection; function calling carries the individual actions. Choosing between them is therefore the wrong framing. The right question is which layer your need lives on.
What Skills can package
Four kinds of content sit comfortably in a Skill, and most useful Skills blend them.
The first is instructions: the step-by-step procedure for a workflow, written as guidance. This is the core of almost every Skill – the sequence of decisions and actions that turns a general-purpose model into something that reliably performs a specific job your way.
The second is reference documentation: domain knowledge the model would not otherwise have, or would have imprecisely. Internal terminology, a style guide, a regulatory checklist, the schema of a proprietary data format, the quirks of a legacy system. This is where progressive disclosure earns its keep, with deep reference held in supporting files.
The third is code: scripts and helpers Claude can run in an execution-capable environment, or read and adapt. A Skill that generates a particular report format might ship the generator itself rather than ask the model to reconstruct it each time, which improves both reliability and speed.
The fourth is examples: worked instances of the input and the desired output. Few-shot examples embedded in a Skill anchor the model's behaviour far more effectively than abstract description alone, particularly for format-sensitive tasks where tone, structure and layout matter.
When to create a Skill
Build a Skill when a capability is reusable, specific and conventional – when you find yourself pasting the same long preamble into prompt after prompt, or correcting the model toward the same house style again and again.
Three patterns justify a Skill cleanly. A reusable workflow – something you perform repeatedly with the same steps – belongs in a Skill so the procedure lives once and improves in one place. Domain expertise that the base model lacks or garbles – your internal data model, a niche standard, a body of institutional knowledge – belongs in a Skill so Claude can draw on it without you re-teaching it each session. And format conventions – the exact way your organisation wants documents, code, or reports to look – belong in a Skill because they are precisely the kind of persistent, specific constraint that prose instructions capture well.
The inverse is equally worth stating. Do not reach for a Skill when you need a live connection to a running service; that is MCP's job. Do not reach for a Skill for a one-off instruction you will never repeat; just say it in the prompt. And do not reach for a Skill when what you actually need is a typed, deterministic function call your own code controls. The framework is for packaged, reusable competence, not for every extension of the model.
For builders
Writing a SKILL.md well is closer to technical writing than to programming. Start with the description, and make it precise about both what the Skill does and when it should fire, because that string is the model's entire basis for selecting it. Then write the body as you would brief a capable new hire: state the goal, give the steps, flag the edge cases, show the desired output. Keep the main file lean and push depth into supporting files that the body references by name, so the always-loaded cost stays low.
Testing is where discipline pays. Because loading is driven by the model's judgement of relevance, the first thing to test is selection: does Claude actually pick up the Skill when it should, and leave it alone when it should not? Run representative prompts that ought to trigger it and prompts that ought not, and tune the description until selection is reliable. Then test execution: does the model follow the instructions faithfully, handle the awkward inputs, and produce output in the expected form? Treat a Skill like code under test, with a small suite of cases you re-run after every edit, because a change to the description or the ordering of instructions can shift behaviour in ways that are not obvious from reading the diff.
Distribution follows from where your users run Claude. A Skill can live with a single developer, be shared across a team, or be packaged for wider use. The folder-based design makes Skills portable by construction – a Skill is just files – which means version control, code review and the ordinary machinery of software collaboration apply directly. Keep Skills in a repository, review changes, and treat the SKILL.md as a reviewed artefact rather than a scratch note, especially once more than one person depends on it. This also matters for safety: a Skill is instructions a model will follow, so a malicious or careless Skill is a vector worth governing, a theme consistent with Anthropic's broader safety-first posture.
The Skills ecosystem
Anthropic ships a set of official Skills – the kind that handle common, well-defined jobs such as producing documents in standard office formats – and these serve double duty as working examples of how a Skill is meant to be structured. Reading a well-made official Skill teaches the conventions faster than any specification: how terse the description should be, how the body is sequenced, how supporting files are referenced.
Beyond the official set, a community pattern is forming, as it did around MCP servers and around prompt libraries before that. Developers publish Skills, often in public repositories, and the folder format makes them trivial to copy and adapt. The open question, as of this writing, is whether a genuine marketplace emerges – a curated, discoverable, perhaps monetised distribution channel – or whether Skills remain a loosely shared, repository-driven practice. Either outcome has precedent in Anthropic's own recent history, and the trajectory of the wider agentic AI ecosystem suggests appetite for both.
For a developer deciding today, the practical counsel is to treat the ecosystem as a source of patterns rather than a dependency. Study the official Skills, borrow from good community examples, but own the Skills your product relies on – review them, test them, version them – because a Skill is, in the end, instructions your users' model will follow, and that is a responsibility worth keeping close. Watch the official documentation for changes to how Skills are discovered, scoped and secured; this is a young feature, and the surface around it will move faster than the core idea, which is likely to stay exactly as simple as a folder with a Markdown file inside.