Anthropic's Agent Skills: how to create, install, and version skills for Claude Code

Anthropic documents Agent Skills as packages of instructions and scripts that Claude loads on demand. We compared the structure of a Skill with an equivalent MCP server to understand where each approach pays off.

Anthropic's official documentation (docs.claude.com) already treats Agent Skills as a standard part of the Claude Platform: on claude.ai, in the API, in Claude Code, and, via the Skills API, also on Claude Platform on AWS and on Microsoft Foundry. With the feature consolidated across these surfaces, the question that matters to developers is no longer "what is this," but "when is it worth using instead of an MCP server."

The short answer, in practice: a Skill is a knowledge package; MCP is integration with an external system. The long answer requires understanding how Claude loads that package under the hood.

What an Agent Skill actually is

A Skill is a filesystem directory that Claude accesses with bash, as if browsing folders on your computer. Inside it lives at least one SKILL.md file with YAML frontmatter (name and description), which may include additional markdown files, executable scripts, and reference materials (schemas, templates, API documentation).

The key difference from a reusable prompt is that a Skill doesn't need to be pasted manually into every conversation: once installed, Claude decides on its own when to use it, matching the user's request against the description field in the frontmatter.

The three loading levels

The documentation calls this progressive disclosure, and it's the concept that underpins the whole context-efficiency proposal:

In practice, this means it's possible to install dozens of Skills without a context penalty: only the name and description stay resident. The body of SKILL.md only enters the window when the user's request matches the description, and a script like validate_form.py runs in full via bash without its code ever appearing in context, only the output.

Creating a Skill for Claude Code: the roadmap

In a typical project, the path I'd follow to package an API review rule would start with the directory structure, inside .claude/skills/ at the root of the repository:

api-contract-check/
  SKILL.md
  REFERENCE.md
  scripts/
    validate_contract.py

The SKILL.md would look like this:

---
name: api-contract-check
description: Checks whether changes to a route comply with the contract defined in openapi.yaml. Use when the request involves changing parameters, response types, or status codes of a REST endpoint.
---

# API contract check

## Instructions
1. Read `openapi.yaml` at the root of the repository.
2. Run `scripts/validate_contract.py` passing the diff of the changed endpoint.
3. If the script reports a contract break, list the affected fields before proceeding with the change.

## Reference
For API versioning exceptions, see REFERENCE.md.

The name follows Anthropic's rules: up to 64 characters, lowercase letters, numbers, and hyphens only, without the words "claude" or "anthropic". The description is the field that decides whether the Skill fires or not, so it needs to say what and when, not just what.

With the file saved in .claude/skills/api-contract-check/, Claude Code discovers and uses the Skill automatically in the next session, with no upload and no API endpoint: it's just a filesystem read.

Versioning a Skill means versioning a file

This is where Claude Code sets itself apart from the other surfaces. Since the Skill lives inside the repository itself (.claude/skills/), it goes into git add, shows up in the pull request diff, and gets reviewed like any other configuration file in the project.

This solves a real problem with the other two distribution methods the documentation describes. On claude.ai, Skills are per-user, with no centralized admin management. In the API, Skills are shared across an entire workspace, but require uploading via /v1/skills every time they change. Neither one syncs with the other: Anthropic is explicit about this, calling the lack of synchronization between claude.ai, the API, and Claude Code "cross-surface availability."

To share a Claude Code Skill beyond the team that clones the repository, the documentation points to Claude Code Plugins as the distribution mechanism, but that's already another layer of packaging on top of the same idea of a directory with a SKILL.md.

Skill or MCP server?

An MCP server solves a different problem: it exposes tools, resources, and prompts through a protocol, usually running as a separate process (stdio or HTTP), with a validated input schema and, in most implementations, network access and state between calls. It's the right piece when Claude needs to talk to a live system: a database, a third-party API, a message queue.

A Skill doesn't replace that. It doesn't maintain a connection, doesn't expose a typed schema, and, in the API, runs in a sandboxed container with no network access and no package installation at runtime, according to the documentation's own limitations section.

In short: if the goal is "do this task the same way every time, with the same steps," it's a Skill. If the goal is "talk to this system that changes in real time," it's MCP.

Where each approach breaks down

A Skill breaks down when the problem requires network access or state that the environment doesn't offer. In the API, any script that depends on an external HTTP call fails, because the Skills container runs with no internet access; and any Python package that isn't pre-installed also fails, because there's no runtime installation. On claude.ai, network access varies depending on the administrator's configuration, so a Skill that works for one user might not work for another.

An MCP server breaks down in a different way: it requires keeping a process running, handling authentication, dealing with timeouts and protocol versioning, and all that boilerplate exists even to expose a simple business rule that a ten-line SKILL.md would solve without any server at all.

A trait, not a flaw: installing a malicious Skill carries the same risk as installing a malicious MCP server, but auditing is simpler in the former case. The documentation recommends treating Skills like software installation, reviewing the SKILL.md, scripts, and any embedded network calls before using them in production, especially when the source isn't Anthropic itself.

What remains open

Anthropic lists Skill content scanning as a feature available only to Enterprise organizations, and only for uploads via claude.ai and Claude Cowork, not for the Skills API or the Claude Console. That leaves smaller teams relying on manual review, exactly the point where a custom MCP server, by running on its own infrastructure, can offer more access control.

For those who already use Claude Code day to day, the .claude/skills/ structure versioned in git looks like the cheapest path to standardizing team workflows: it doesn't require spinning up a server, doesn't require a separate API account, and the SKILL.md stays readable in any code review.