Claude skills explained: what they are, how to install them, and how to write your own

A skill is a folder. Inside it is a Markdown file called SKILL.md that tells Claude how to do a specific job, and optionally some scripts and reference documents that help. When a task matches the skill's description, Claude reads the file and follows it. When it does not, the skill costs nothing.

That is the whole mechanism, and it turns out to be the most practical way anyone has found to give an AI agent expertise that survives from one session to the next. This guide covers how skills work, how to install them in Claude Code, Claude.ai and the API, how to write one that actually improves results, and what to consider before a team adopts them. For how skills relate to MCP, see Claude skills vs MCP.

Why skills exist

Prompts do not scale. A good prompt for "review this pull request the way our team does it" is two pages long. Nobody pastes two pages into every session, so the knowledge lives in someone's head, or in a wiki the agent never reads.

Skills package that knowledge once, next to the code, and load it only when needed. Anthropic launched them in October 2025 for Claude.ai, Claude Code and the API. In December 2025 the format was published as an open specification, Agent Skills, and other coding agents adopted it. In practice, a SKILL.md you write for Claude Code today also works in Codex, Cursor and Copilot with minor differences.

How a skill works

Three things happen at different times, which is why skills scale.

1. At startup, the agent reads only the frontmatter of every skill it knows about: the name and a one-line description. For fifty skills that is a few hundred tokens.
2. When a task matches a description, the agent reads the full SKILL.md into context. That is when the instructions start to matter.
3. When the instructions say so, the agent opens reference files or runs scripts in the skill folder. A skill for generating Excel files might carry a Python script that does the actual writing, so the model does not have to reinvent it.

This is called progressive disclosure. It is the reason you can have many skills installed without paying for all of them every turn.

Anatomy of a skill

The minimum is one file:

release-notes/
└── SKILL.md

With this content:

---
name: release-notes
description: Write release notes from merged pull requests in our house style. Use when asked to draft, write or prepare release notes or a changelog for a version.
---

# Release notes

## When to use
The user asks for release notes, a changelog or "what shipped" for a version or date range.

## Steps
1. List merged PRs for the range using the GitHub tools. Ignore PRs labelled `chore` or `internal`.
2. Group by: New, Improved, Fixed. One line each, present tense, no PR numbers in the line.
3. Lead with the change that affects the most users.
4. End with an "Upgrade notes" section only if any PR is labelled `breaking`.

## Style
Short sentences. No exclamation marks. British spelling. Product names as in `docs/style.md`.

The description is doing real work. It is what the agent matches against, so it should say both what the skill does and when to use it, in the words a user would actually type.

A richer skill adds files:

release-notes/
├── SKILL.md
├── examples/
│   └── v2.4.md
└── scripts/
    └── list_prs.sh

SKILL.md refers to them ("see examples/v2.4.md for the expected format", "run scripts/list_prs.sh <from> <to>"). The agent reads or executes them only when it gets to that step.

Installing skills in Claude Code

Claude Code looks for skills in three places.

Project skills, in .claude/skills/<name>/ inside the repository. Commit them, and everyone who clones the repo gets them. This is where team conventions belong.

Personal skills, in ~/.claude/skills/<name>/. Yours across every project.

Plugin skills, delivered by plugins installed from a marketplace with /plugin. Plugins bundle skills together with slash commands, hooks and MCP server definitions, which is how most third-party skills are distributed.

Once a skill is in place, there is nothing to enable. Type a request that matches its description and the agent uses it. Skills can also be invoked explicitly by name, and a skill can be marked so that only the user can trigger it, which is useful for anything with side effects.

Skills in Claude.ai and the API

In the Claude web and desktop apps, skills are managed under Settings, where you can enable Anthropic's built-in skills (documents, spreadsheets, presentations, PDFs) and upload your own as a zip of the skill folder. They run inside Claude's code execution sandbox.

Through the API, skills are attached to a request that uses the code execution container. You upload a skill once, reference it by id, and the model has it available for that request. This is how you give a production agent the same expertise a developer has in Claude Code.

Writing a skill that works

Most skills we see in the wild are too long, too vague, or both. The ones that reliably change the agent's behaviour share a few properties.

The description is precise. "Helps with documents" matches everything and nothing. "Convert a DOCX contract into our redline format. Use when asked to redline, mark up or compare contract versions" matches the right requests.

The body is procedural. Numbered steps, the order they should happen in, and what "done" looks like. The agent is good at following a procedure and bad at inferring one from a description of values.

Decisions are explicit. If the task has a fork ("if the repo has a CHANGELOG.md, append to it; otherwise create one"), write the fork. The agent will otherwise pick one at random and be confidently wrong half the time.

Deterministic work goes in scripts. Anything the model would do by generating code (parse a file format, call an API with the right pagination, compute a checksum) is more reliable as a script the skill runs. The model then orchestrates rather than reinvents.

It is short enough to read. Under 500 lines for SKILL.md. Anything longer moves into reference files the agent opens on demand.

It has an example. One example of the expected output is worth a page of description.

Where to find skills

Anthropic maintains a public repository of official skills on GitHub, covering document formats, presentations and a few developer workflows. Claude Code's plugin marketplaces are the main distribution channel for third-party skills. Community "awesome" lists collect more.

The rule is the same as for any code from the internet: read it before you install it. A skill can contain scripts, and scripts run. A skill's instructions can also tell the agent to do things you would not want ("post the results to this webhook"). For a team, that means an approved set rather than an open marketplace, which we come back to below.

Skills vs the alternatives

Skills vs CLAUDE.md. A CLAUDE.md file is always loaded and should hold what the agent must always know: how to build, test, and the non-negotiable conventions. Skills hold task-specific knowledge that would bloat that file. If it applies to every session, put it in CLAUDE.md; if it applies to one kind of task, make it a skill.

Skills vs slash commands. Commands are user-triggered shortcuts for a prompt. Skills are triggered by the agent when relevant and can carry files and scripts. Many teams start with commands and graduate to skills when the prompt grows or needs supporting material.

Skills vs subagents. A subagent is a separate context with its own tools, used for isolation or parallelism. A skill is knowledge loaded into the current context. A subagent can use skills.

Skills vs MCP. MCP gives access to systems; skills give know-how. The full comparison is in Claude skills vs MCP.

Rolling skills out to a team

Three things change when skills go from one developer to a department.

Provenance. Which skills are approved, who wrote them, what scripts they contain. A curated internal marketplace, or a repository of reviewed skills, replaces "install whatever the blog said".

Consistency. The value of a skill for "how we review PRs" is that everyone's agent reviews PRs the same way. That only holds if the skill is the same everywhere and updated centrally.

Policy. A skill that says "deploy to production after the tests pass" should only run for people allowed to deploy. Skills do not enforce that; the tools they call do. This is where skills meet the gateway: the skill describes the procedure, the gateway decides whether this user's agent may call the deploy tool.

Walma AI Hub handles the last part. Approved skills and MCP servers are distributed through one signed client, policies decide who can call which tools, and every call is logged, inside the customer's own EU region. If you are standardising skills across a team, book a walkthrough.