Claude skills: how to install and write skills for Claude Code and Claude.ai

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.

Is a skill just a prompt?

It is the most common question about skills, and the honest answer is: the core of it is. SKILL.md is instructions written in Markdown, and a model reads it the way it reads any prompt. Three things make it more than a prompt in practice:

• It loads itself. You do not paste it. The agent reads it only when a request matches its description, so fifty skills cost almost nothing until one is needed.
• It carries tools. Scripts, templates and reference files sit next to the instructions, and the agent runs or opens them when a step calls for it. A prompt cannot ship a Python script that parses your invoice format correctly every time.
• It is a file in a repository. You can review it in a pull request, version it, roll it back and share it with a team. That is what turns one person's good prompt into a team convention.

If a skill would be one paragraph with no files, a line in CLAUDE.md or a slash command may be the better tool. The comparison is further down.

How to install skills in Claude Code

Claude Code looks for skills in several places. These are the ones you will use:

When two skills share a name, enterprise wins over personal, and personal wins over project. That is useful for an organisation that wants one approved version of a skill to override local copies.

Once a skill is in place there is nothing to enable. Three ways to use it:

• Automatically. Type a request that matches its description and Claude loads it.
• Explicitly. Type /skill-name at the start of a message, with arguments if the skill takes them: /release-notes v2.4.
• List what is loaded with /skills, which shows every available skill and its description.

The frontmatter fields worth knowing

Only name and description are needed to start, but a few optional fields in Claude Code change how a skill behaves:

A deploy skill, for example, is safer like this:

---
name: deploy
description: Deploy the application to production after the release checklist passes.
disable-model-invocation: true
allowed-tools: Bash(git status *) Bash(git tag *)
---

Skills in Claude.ai, the API and Managed Agents

The built-in skills in Claude.ai cover document formats: Word, Excel, PowerPoint and PDF. They are the reason Claude can produce a real .xlsx with formulas instead of a table pasted into a chat.

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.

A worked example: ux-lint

The properties above are easier to see in a skill that exists. We publish ux-lint, an open-source UX linter for coding agents, under the same Agent Skills format. It installs like any other skill:

npx skills add Walma-Labs/ux-lint

Then you ask for it in the words you would use anyway: "review the signup page for UX problems", "ux check before I merge".

It is worth reading as an example because of four choices, each one an instance of a rule from the previous section.

The deterministic work is a script, not a prompt. The skill ships a Playwright script that opens the page in a real browser and measures it: tap-target sizes and spacing, elements that cannot actually be clicked, horizontal overflow, FCP and LCP, click-to-paint latency, layout shift. The model never estimates a pixel value. It receives numbers and reasons about them. That is the difference between a skill that works and a design skill that guesses from source code.

The reference material sits beside SKILL.md, not inside it. Every UX principle is traced to its primary research in a references/ folder, which the agent opens when it needs to justify a finding. The instruction file stays short enough for the agent to actually follow.

The instructions constrain the model, not just guide it. Each principle is labelled with the strength of its evidence, and the skill documents where popular UX advice overstates the research. It will not flag a navigation bar for "violating Miller's Law", because that law is about memory, not visible menu items. Writing the boundary into the skill is what stops a confident-sounding wrong answer.

One skill, three modes. review produces a ranked report, check a pass/fail verdict for pre-merge, fix applies the changes and re-measures. The modes map to when people actually ask, which is the practical version of "the description is precise".

If you are writing your first skill, cloning the shape of a working one is faster than starting from the specification.

When a skill does not trigger

The most common complaint about skills is that Claude ignores them. Work through these in order:

1. Is it loaded? Run /skills in Claude Code. If it is not listed, the folder is in the wrong place or the file is not called SKILL.md.
2. Does it work when called directly? Type /skill-name. If that works, the skill is fine and the problem is matching.
3. Does the description use the user's words? Claude matches the request against the description. If people say "changelog" and the description says "release documentation", it will not fire. Name the task and the phrases people actually type.
4. Is the frontmatter valid YAML? A skill with malformed frontmatter loads with empty metadata, so it has no description to match. Running Claude Code with --debug shows parse errors.
5. Is automatic use switched off? disable-model-invocation: true means only /skill-name runs it.
6. It worked once and then stopped? Claude Code reads a skill into the conversation once and does not re-read the file on later turns. Phrase instructions so they apply for the whole task, or invoke the skill again.

Before you install someone else's skill

A third-party skill runs with your permissions. It can contain scripts, and its instructions can steer the agent. Install skills only from sources you trust, and review them first. A five-minute review catches most problems:

• Read SKILL.md in full. Look for instructions that send data anywhere ("post the summary to…", "upload to…"), touch credentials, or tell the agent to skip confirmations.
• Read every script. Network calls, curl | sh, writes outside the project, and anything obfuscated are reasons to stop.
• Check allowed-tools. A skill that pre-approves broad shell access deserves more scrutiny than one that only reads files.
• Pin a version. Install from a specific commit or release, not a moving branch, so the skill you reviewed is the skill that runs.
• Prefer a team copy. Fork reviewed skills into your own repository or internal marketplace, and update them deliberately.

Where to find skills

Anthropic maintains a public repository of official skills on GitHub, covering document formats, presentations and a few developer workflows. Our shortlist of the best Claude skills covers the official ones and the community skills worth installing, Claude marketing skills covers the marketing collections, and skill-creator is the way to build and test your own. 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.