---
title: "Claude Skills Explained: How Agent Skills Actually Work"
description: "Claude Skills are folders with a SKILL.md file that Claude loads only when relevant. What they are, where they run, and which ones are worth installing."
type: "guide"
locale: "en"
category: "Claude Code"
canonical: "https://agenticschool.dev/guides/claude-skills-explained"
datePublished: "2026-08-28"
dateModified: "2026-08-28"
---

# Claude Skills Explained: How Agent Skills Actually Work

- Category: Claude Code
- Keywords: claude skills, claude code skills, what are claude skills, claude agent skills, claude skills marketplace, how to use claude skills, claude skills vs subagents, best claude skills, how to add skills to claude code, claude skills example, claude skills github, claude design skills
- Canonical URL: https://agenticschool.dev/guides/claude-skills-explained
- Locale: en

> Claude Skills are folders with a SKILL.md file that Claude loads only when relevant. What they are, where they run, and which ones are worth installing.

Claude Skills are folders. Each one holds a SKILL.md file whose YAML frontmatter carries two required fields, name and description, followed by Markdown instructions, and the agent loads that content only when your request matches the description. Anthropic calls the feature Agent Skills, published it as an open standard in December 2025, and supports it across claude.ai, Claude Code, the Claude Agent SDK and the Claude Developer Platform. This Claude Skills guide covers what a Claude skill is, where skills work, how they differ from slash commands, subagents, MCP servers and CLAUDE.md, which ones are worth installing, and how to write one in about ten minutes.

## What a Claude skill is, in three layers

A Claude skill is a directory containing a SKILL.md file, and optionally scripts, reference documents and templates alongside it. The file opens with YAML frontmatter and continues as ordinary Markdown instructions. What makes the format work is not the file, it is the loading model: Anthropic documents a three-stage process called progressive disclosure, where the agent reads only the metadata at startup, pulls the instructions into context when your request matches, and touches the bundled files only if the task actually needs them. That is why you can install many skills without paying for the ones you never trigger.

- Level 1, metadata: the name and description fields, loaded into the system prompt at startup, roughly 100 tokens per skill.
- Level 2, instructions: the SKILL.md body, loaded only when the skill is triggered, recommended to stay under 5,000 tokens.
- Level 3, resources: bundled reference files and scripts, costing nothing until they are read. A script that runs contributes only its output, never its source.

The description is not documentation, it is the matching surface. It is the only text about your skill that sits in the system prompt before anything triggers, so it is the only thing separating yours from all the other skills Claude can see. Anthropic requires it to say both what the skill does and when to use it, and a vague description produces a skill that never fires.

Everything on this page was read off primary sources on August 28, 2026: the Agent Skills overview on the Claude developer platform, the Claude Code skills reference, the published Agent Skills specification, and the anthropics/skills repository on GitHub. Skills shipped in October 2025 and the surface is still moving quickly, so check the same sources before you build something expensive on any single detail here.

## Where Claude Skills work, surface by surface

Skills run in Claude Code, in claude.ai and through the Claude API, and Anthropic states that the Claude Agent SDK and the Claude Developer Platform support them as well. What changes between surfaces is where the file lives, who else can see it, and which frontmatter fields are legal. The warning that catches people is that custom skills do not sync across surfaces: a skill uploaded to claude.ai is not available through the API, and Claude Code skills are filesystem-based and separate from both. You install the same folder once per surface you want it on.

- Claude Code, where it lives: ~/.claude/skills/name/SKILL.md for personal skills, .claude/skills/name/SKILL.md for a project, or a skills folder inside a plugin.
- Claude Code, who can use it: you, everyone who clones the repo, or everyone the plugin is enabled for. The directory name becomes the slash command.
- Claude Code, frontmatter allowed: every field, including the Claude Code extensions such as disable-model-invocation, allowed-tools, model, effort and paths.
- Claude Code, watch out for: skills have the same network access as any other program on your computer, so an untrusted skill is untrusted software.

- claude.ai, where it lives: uploaded as a zip file through Settings and then Features.
- claude.ai, who can use it: only you. Anthropic states custom skills there are individual to each user and cannot be centrally managed by admins. Pro, Max, Team and Enterprise plans, code execution on.
- claude.ai, frontmatter allowed: the six specification fields only, which are name, description, license, compatibility, metadata and allowed-tools.
- claude.ai, watch out for: network access varies with your user and admin settings, so a skill that fetches data may behave differently than it does on your machine.

- Claude API, where it lives: created through the /v1/skills endpoints and referenced by skill_id in the container parameter of a request.
- Claude API, who can use it: the whole workspace. Anthropic states uploaded custom skills are shared workspace-wide.
- Claude API, frontmatter allowed: the same six specification fields as claude.ai. An unexpected key fails the upload with a hard error rather than being ignored.
- Claude API, watch out for: skills require the code execution tool and run in a sandboxed container with no network access and no runtime package installation, so only pre-installed packages are available.

Anthropic also ships four pre-built Agent Skills for documents: PowerPoint, Excel, Word and PDF, referenced by the skill ids pptx, xlsx, docx and pdf. Those are active on claude.ai and available through the API, and Anthropic states they are not available in Claude Code, although the open-source Claude API skill ships bundled with Claude Code instead.

## Claude Skills vs agents, subagents, commands and MCP

These are not competing options, they solve different problems, and confusing them is the most common mistake in this whole area. Claude Skills vs agents is the wrong framing to begin with: an agent is the whole system doing the work, and a skill is one of the things you hand it, not a smaller version of it. A skill is a procedure loaded on demand. A slash command is now the same thing in a single file, because Anthropic merged custom commands into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave identically, and if both exist the skill wins. A subagent is a separate context that does work and reports a conclusion back. An MCP server is a live connection to an external system. CLAUDE.md is a set of facts loaded on every single turn.

- Skill: use it when you keep pasting the same multi-step procedure, and you want it available without being loaded every turn.
- Slash command: use it when one Markdown file is enough and there is nothing to bundle. It creates the same command a skill does, so there is no reason to migrate a working one.
- Subagent: use it when the work would flood your main context and you only need the conclusion back.
- MCP server: use it when the agent needs live data or an external API at runtime. Instructions cannot fetch anything.
- CLAUDE.md: use it for facts that apply on every turn. Anthropic advises moving a CLAUDE.md section into a skill once it has grown into a procedure rather than a fact.

Getting that split right is most of what separates an agent setup that feels fast from one that feels bloated, and it is the spine of the Claude Code course we teach at Agentic School.

## The anatomy of a minimal SKILL.md

A working skill needs exactly two frontmatter fields. The Agent Skills specification requires name, at most 64 characters of lowercase letters, numbers and hyphens, with no leading, trailing or consecutive hyphens, and matching the parent directory name. It requires description, at most 1,024 characters, covering both what the skill does and when to use it. Everything else is optional. The example below is the shortest honest answer to how to create Claude Skills that run anywhere: it uses only specification fields, so the same folder loads in Claude Code, uploads to claude.ai and packages for the Skills API without a single edit.

```markdown
---
name: pr-description
description: Writes a pull request description from the current branch diff. Use when the user asks for a PR description, a pull request summary, or release notes for a branch.
---

# PR description

## Steps

1. Read the diff between the current branch and the default branch.
2. Group the changes by area: features, fixes, refactors, tests.
3. Write a title under 70 characters, then a body with a Summary section and a Testing section.
4. List any migration or config change a reviewer has to apply by hand.

## Rules

- Describe behavior a reviewer can check, not the files you touched.
- Never claim a test passed unless you ran it.
- If the diff is empty, say so and stop.
```
A complete SKILL.md saved at .claude/skills/pr-description/SKILL.md. The directory name becomes /pr-description, and the description is what the model matches your request against.

- license: the license covering the skill, either a license name or the name of a bundled license file.
- compatibility: up to 500 characters describing environment requirements, such as required system packages or network access.
- metadata: a free-form map of string keys to string values, for your own tooling to read.
- allowed-tools: pre-approved tools the skill may use, marked experimental in the specification because support varies between agents.

Claude Code accepts far more fields than those six, including argument-hint, arguments, disable-model-invocation, user-invocable, model, effort, context, hooks and paths. Those are Claude Code extensions, not part of the standard. Include one in a skill you package for claude.ai or the Skills API and the upload fails with an unexpected-key error naming the offending field, rather than quietly ignoring it. Write the portable six if the skill needs to travel, and reach for the extensions only for skills that will live on your machine.

## Claude Skills marketplace, library and awesome lists

There is no dedicated Claude Skills marketplace and no official Claude Skills library as a separate Anthropic product. Anyone searching for one lands on the Claude Code plugin system instead, which is the real distribution mechanism. Anthropic publishes its own Claude Skills repository on GitHub as anthropics/skills, which you register inside Claude Code as a plugin marketplace and then install as one of two plugins. Anthropic also runs an official plugin marketplace, and its documentation states that is the only marketplace Claude Code registers on its own. Everything else, including the awesome Claude Skills lists people share, is community-curated and unvetted.

- Anthropic skills repository: add anthropics/skills as a plugin marketplace in Claude Code, then install its document-skills or example-skills plugin. Limitation: Anthropic labels these demonstration material, not production code.
- Official Anthropic plugin marketplace: anthropics/claude-plugins-official, the only marketplace Claude Code registers by itself. Limitation: names like agent-skills are reserved precisely because impersonation is a live risk here.
- claude.ai settings: upload a skill folder as a zip through Settings and then Features. Limitation: the skill stays private to your own account and admins cannot manage it centrally.
- Skills API: create and upload through the /v1/skills endpoints for workspace-wide access. Limitation: requires the code execution tool, and the container has no network access.
- Community lists: ComposioHQ maintains awesome-claude-skills on GitHub, a curated list of community skills and tools. Limitation: an awesome list is an index, not a review. Nothing on it was audited for you.

Anthropic also publishes a long-form PDF called The Complete Guide to Building Skills for Claude on its resources site, which is the closest thing to an official authoring manual for the format.

Anthropic is blunt about the risk: use skills only from sources you created yourself or obtained from Anthropic, because a skill can direct Claude to run code and call tools in ways that do not match its stated purpose. Read every file in a skill before installing it, not just the SKILL.md, and treat a skill that fetches data from an external address as the highest-risk category, since fetched content can carry instructions of its own. Installing a skill from a GitHub repository is installing software from a stranger.

## Claude Skills worth installing first

Every skill named below was verified by reading its own SKILL.md in the anthropics/skills repository on August 28, 2026, not by copying somebody else's summary. We picked for breadth rather than a ranking: two that make you better at building agent tooling, two that raise the quality of what you ship, and three design skills, the category people search for hardest after the general term. Most of that repository is Apache 2.0; the document skills for Word, Excel, PowerPoint and PDF are source-available rather than open source.

- skill-creator: creates and edits skills, and runs evals measuring how reliably a description triggers. Best for anyone writing more than two skills. Limitation: it fixes structure and triggering, not your domain knowledge.
- mcp-builder: builds MCP servers in Python with FastMCP or Node and TypeScript with the MCP SDK. Best for when a skill is the wrong tool and you need a live connection. Limitation: server design only, not hosting or auth.
- webapp-testing: drives a local web app with Playwright to verify frontend behavior, capture screenshots and read browser logs. Best for checking a change in the running app, not just in tests. Limitation: local apps only.
- frontend-design: aesthetic direction for new or reworked UI, aimed at output that does not read as a templated default. Best for solo builders with no designer. Limitation: it shapes typography, it does not know your brand.
- canvas-design: turns a written design philosophy into posters and other static pieces as PNG and PDF. Best for one-off visual assets. Limitation: static output, and it is told to create original work rather than copy an artist.
- theme-factory: applies one of ten preset color and font themes to a deck, a doc or an HTML page, or generates a new one. Best for making scattered outputs look like one system. Limitation: it styles, it does not lay out.
- claude-api: a current reference for the Claude API and SDKs covering model ids, pricing, streaming, tool use and caching in eight languages. Best for writing code against Claude. Limitation: it already ships with Claude Code.

Two honest caveats on the whole set. First, Anthropic attaches an explicit disclaimer to that repository: the skills are provided for demonstration and educational purposes, and what Claude actually does may differ from what the skill describes. Second, the best Claude Code skills for you are almost never the famous ones. A three-line skill encoding how your team writes commit messages fires ten times a day; a beautifully built design skill you installed because it looked impressive sits there costing you 100 tokens a session forever.

## What a skill actually costs you in context

A skill you never trigger costs about 100 tokens, per Anthropic's own progressive-disclosure table: the name and description of every installed skill sit in the system prompt from startup, and nothing else does. The cost that bites arrives after the trigger, because in Claude Code an invoked skill's rendered content enters the conversation as a single message and stays there for the rest of the session. Claude Code does not re-read the file on later turns, so a long skill is a long-lived tax.

- 30 installed skills at roughly 100 tokens of metadata each: about 3,000 tokens spent at startup, whether or not you use a single one.
- One skill body at the recommended 5,000-token ceiling, invoked once: 5,000 tokens that stay in the conversation for the rest of the session.
- Five such skills invoked in one session: about 25,000 tokens, which is exactly the combined budget Claude Code re-attaches after auto-compaction.
- After compaction Claude Code keeps only the first 5,000 tokens of each re-attached skill and fills that 25,000-token budget from the most recently invoked backwards, so skills you invoked early can disappear entirely.
- Claude Code caps the skill listing at 1 percent of the model context window by default, and caps each entry at 1,536 characters of description text, dropping descriptions from your least-used skills first when it overflows.

The rule that falls out of the arithmetic: keep the description sharp and the body short, and push everything long into reference files that load only when the task reaches for them. Anthropic's specification recommends keeping SKILL.md under 500 lines for exactly this reason. It is the same context-budget discipline our Claude Code material applies to the rest of an agent session, and it is why skill length is a design constraint rather than a detail.

## When not to write a skill at all

Most of what people package as a skill should not be a skill. A one-off instruction belongs in the prompt you are already typing. A fact that applies on every turn belongs in CLAUDE.md, where it is always loaded. A live external data source belongs in an MCP server, because written instructions cannot fetch anything. Work that would flood your main context belongs in a subagent. And anything that must happen every time, without the model getting a vote, belongs in a hook. A skill is the right answer only for a repeatable procedure you want available but not permanently loaded.

- One-off instruction: put it in the prompt. A skill you invoke once cost you the time to write it and then roughly 100 tokens of metadata in every session afterwards.
- Project rule or fact: put it in CLAUDE.md. Anthropic draws the line at exactly this point, noting that a skill body loads only when used while CLAUDE.md content does not.
- Live data or an external API: build an MCP server. A skill can describe an API, it cannot call one the agent has no connection to.
- A long investigation that would fill your context: hand it to a subagent and keep only the conclusion.
- A guarantee rather than a suggestion, such as blocking a bad commit: use a hook. A skill is instructions the model may decline to follow, and Anthropic advises hooks when behavior must be enforced deterministically.

The simplest test is whether you can say out loud when the skill should fire. If you cannot, its description will not say it either, and you have written a document rather than a skill.

## Which of these you should set up this week

Three things decide this every time: which surface you actually work in, whether the skill needs to travel between surfaces, and whether the thing you are packaging is a procedure or a fact. Once those three are settled, the build itself is a folder and a file.

- One person shipping in Claude Code: create ~/.claude/skills/name/SKILL.md for the two procedures you retype most and use the full Claude Code frontmatter. You do not need six-field portability until a skill leaves your machine.
- A small team on one repo: put skills in .claude/skills/ and commit them, so the procedure ships with the code and the next hire inherits it. Add disable-model-invocation: true to anything with a side effect, such as a deploy.
- Document and comms work on claude.ai: the pre-built PowerPoint, Excel, Word and PDF skills are already active and need no setup. Upload one custom skill for your house style, and remember it stays private to your account.
- Building on the Claude API: upload through the /v1/skills endpoints for workspace-wide access, keep frontmatter to the six specification fields, and design for a container with no network access and no package installation.

If you only do one thing: take the procedure you pasted into a chat twice this week, put it in a folder with a SKILL.md, and write a description that names the words you would actually say when you want it. The free Claude Code course at Agentic School walks through building one end to end.

## Steps

### 1. Pick the procedure you keep repeating

Choose something you have pasted into a chat more than twice: a release checklist, a review routine, a report format. If it is a fact rather than a procedure, it belongs in CLAUDE.md instead.

### 2. Create the skill folder

Make a directory whose name is lowercase letters, numbers and hyphens, at most 64 characters, with no leading, trailing or consecutive hyphens. In Claude Code that directory name becomes the slash command you type.

### 3. Write the two required frontmatter fields

Create SKILL.md inside the folder, opening with YAML frontmatter that sets name, matching the directory name, and description, up to 1,024 characters saying both what the skill does and when to use it. The description is the only text loaded at startup, so put the trigger words in it.

### 4. Write the body as instructions, not prose

Below the frontmatter, write numbered steps and explicit rules. Keep SKILL.md under 500 lines, which is Anthropic's recommendation, and move long reference material into separate files in the folder so it loads only when the task needs it.

### 5. Put the folder where the surface reads it

For Claude Code, use ~/.claude/skills/name/ for personal or .claude/skills/name/ inside the repo for a project. For claude.ai, zip the folder and upload it through Settings and then Features. For the API, create it through the /v1/skills endpoints. Skills do not sync between these, so install it on each surface you want it on.

### 6. Keep it portable if it has to travel

If the same skill will run on more than one surface, restrict the frontmatter to the six specification fields: name, description, license, compatibility, metadata and allowed-tools. A Claude Code-only field such as argument-hint makes a claude.ai or Skills API upload fail with an unexpected-key error.

### 7. Verify it loaded

In Claude Code, ask what skills are available and confirm yours is listed with its description, then invoke it directly by its slash command. If the command works but the description is missing, the YAML failed to parse: run claude plugin validate against your skills directory, or start with the debug flag to see the parse error.

## FAQ

### What are Claude Skills?

Claude Skills are folders that give Claude a specific capability. Each folder contains a SKILL.md file with YAML frontmatter carrying two required fields, name and description, followed by Markdown instructions, plus any scripts or reference files you want to bundle. Anthropic calls the feature Agent Skills and published it as an open standard in December 2025. Claude loads only the roughly 100 tokens of metadata at startup and reads the full instructions only when your request matches the description.

### How do I add skills to Claude Code?

Create a directory at ~/.claude/skills/your-skill-name/ for a personal skill, or .claude/skills/your-skill-name/ inside a repository for a project skill, and put a SKILL.md file in it with name and description in the frontmatter. The directory name becomes the slash command. Claude Code also loads skills from plugins, so you can install a published set by adding a plugin marketplace, for example Anthropic's own anthropics/skills repository, and installing its document-skills or example-skills plugin.

### How do I create a Claude skill?

Make a folder, add a SKILL.md file, and give it two frontmatter fields. The name must be at most 64 characters of lowercase letters, numbers and hyphens, must not start or end with a hyphen, must not contain consecutive hyphens, and must match the folder name. The description must be at most 1,024 characters and must state both what the skill does and when to use it, because that is the text the model matches your request against. Everything below the frontmatter is ordinary Markdown instructions, and Anthropic recommends keeping the file under 500 lines.

### What is the difference between Claude Skills and subagents?

Claude Skills vs subagents is a difference of kind, not size. A skill is content: instructions and files loaded into the current conversation when your request matches its description, costing roughly 100 tokens of metadata until it fires. A subagent is a separate context that goes off, does work with its own tools, and returns only a conclusion, which is what keeps a long investigation from filling your main context window. Use a skill when you want the agent to follow a known procedure. Use a subagent when the work itself would flood your context and you only need the answer.

### Is there an official Claude Skills marketplace?

There is no separate Anthropic Skills marketplace product. Distribution runs through the Claude Code plugin system: Anthropic publishes an official plugin marketplace at anthropics/claude-plugins-official, which its documentation describes as the only marketplace Claude Code registers on its own, and its open-source skills live in the anthropics/skills repository, which you can register as a plugin marketplace yourself. On claude.ai you upload a zip through Settings and then Features, and on the Claude API you upload through the /v1/skills endpoints. Community indexes such as ComposioHQ's awesome-claude-skills list third-party skills but audit none of them.

### Do Claude Skills work outside Claude Code?

Yes. Anthropic states that Agent Skills are supported across claude.ai, Claude Code, the Claude Agent SDK and the Claude Developer Platform, and the format was released as an open standard so other agent products can adopt it. The catch is that custom skills do not sync between surfaces: a skill uploaded to claude.ai is not available through the API, and Claude Code skills are filesystem-based and separate from both. Frontmatter differs too, since claude.ai and the Skills API accept only the six specification fields while Claude Code accepts many more.

### What are the best Claude Skills?

For most builders the best Claude Skills are the small ones you write yourself, because a skill that encodes how your team actually works fires every day while a famous one usually sits unused at roughly 100 tokens a session. If you want a starting set from Anthropic's own repository, skill-creator helps you write and evaluate further skills, mcp-builder covers building MCP servers in Python or TypeScript, webapp-testing drives a local app with Playwright, and frontend-design, canvas-design and theme-factory are the design skills. Anthropic labels that repository as demonstration and educational material, so audit anything before you install it.