What Are Claude Skills? How SKILL.md Folders Work

Claude skills are folders. Each one contains a SKILL.md file with a short description and a set of instructions, and an agent such as Claude Code reads the description first and opens the rest only when your task calls for it. That is the whole idea, and it explains why a skill can carry a long, careful procedure without slowing down every conversation.

This guide covers what is inside a skill, how an agent discovers and loads one, who decides when it runs, which agents accept the format and when a skill is a better choice than a prompt or an instruction file. If you want to build one, the step-by-step guide to creating a Claude skill picks up where this page stops.

What are Claude skills?

A Claude skill is a directory whose only required file is SKILL.md. The file starts with YAML frontmatter, which holds the skill's name and description, and continues with Markdown instructions written for the agent. The directory can also hold scripts, reference documents and templates that the instructions point to.

The format is written up in the open Agent Skills specification, and Anthropic's skills repository holds examples that range from creative work to testing web apps and generating MCP servers. Because the format is an open standard, people use "Claude skills", "agent skills" and "SKILL.md folders" to mean the same thing. This directory lists skills published on GitHub in that format, and each skill page links back to the repository so you can read the source.

Here is the smallest useful skill, taken from the shape of the specification:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---

Step-by-step instructions go here.

Real skills are longer, but the structure does not change. A skill needs a name, a description and a body.

What is inside a skill folder?

The specification names one required file and three conventional folders. Everything else is up to the author.

The split between SKILL.md and the other folders is deliberate. The main file stays short and acts as an overview and a table of contents, while detail lives in files the agent opens on demand. Both the specification and the Claude Code documentation recommend keeping SKILL.md under 500 lines.

Scripts matter because they let a skill do real work with real tools. The official PDF skill, for instance, handles extraction, merging, splitting, watermarking, form filling and OCR in Python and on the command line, and the web app testing skill drives Playwright scripts against a local app. In both cases the Markdown tells the agent when and how to use the tooling.

How does an agent load a skill?

Agents load skills in stages, so that having many skills installed does not flood the context window. The specification calls this progressive disclosure and describes three levels.

1. Metadata. The name and description of every installed skill are loaded at startup, roughly 100 tokens per skill according to the specification.
2. Instructions. The full SKILL.md body is loaded when the skill is activated. The specification recommends staying under 5,000 tokens for this part.
3. Resources. Files in scripts/, references/ and assets/ are read or run only when the instructions call for them.

Claude Code follows the same pattern. Its documentation says the description is always in context so Claude knows the skill exists, while the body loads only on invocation. The combined text of description and when_to_use is cut off at 1,536 characters in the skill listing, so the most important trigger words belong at the start.

One consequence is easy to miss. Once a skill is invoked, its content stays in the conversation for later turns, so a long body is a recurring cost for the rest of that session. Claude Code also re-attaches recently invoked skills after the conversation is compacted, within a fixed token budget.

Who decides when a skill runs?

There are two paths, and you can choose which ones a skill allows.

• You call it. In Claude Code you type /skill-name, optionally followed by arguments. Codex uses $skill-name, and Cursor uses / in Agent chat.
• The agent calls it. When your request matches the description, the agent loads the skill without being asked. This is why the description is the most important line in the file.

Claude Code adds two frontmatter switches. Setting disable-model-invocation: true stops Claude from loading the skill on its own, which suits risky actions such as deployments, while you can still type the slash command. Setting user-invocable: false hides the skill from the slash menu and leaves it available to Claude as background knowledge. Neither field is part of the open specification, so other agents may ignore them.

Which agents can use Claude skills?

The same folder works in more places than the name suggests. The directory's agent pages record where each tool looks for skills and how to install them.

Cursor and GitHub Copilot also read .claude/skills/ for compatibility, so one folder can serve several tools. The Claude apps on the web and desktop work differently: there is no skills folder on your computer, and you upload a ZIP file instead. The Claude apps page covers that route.

Agents agree on the core fields, name and description, and differ on extras. Claude Code accepts a long list of optional fields, OpenCode recognizes only a handful and ignores the rest, and Codex reads optional UI and policy settings from an agents/openai.yaml file. The SKILL.md format reference lays these differences out field by field.

When is a skill better than a prompt?

A prompt is right for a one-off request. A skill earns its place when the same procedure comes up again and you want the agent to follow it the same way each time.

Skills fit well when the task has:

• a repeatable sequence of steps, such as a release checklist or a review routine
• tooling the agent should run rather than reinvent, such as a script that validates a file
• reference material that is too long to paste each time, such as a style guide or an API summary
• a clear trigger, so the description can say when it applies

They fit poorly when the instruction applies to every task in a repository. A rule such as "use pnpm, not npm" belongs in an always-loaded file like CLAUDE.md or AGENTS.md, because you want it present in every session without waiting for a match. The comparison of CLAUDE.md, AGENTS.md and skills goes through that decision in detail. For the wider question of how skills sit next to MCP servers, plugins and subagents, read Claude skills vs MCP, plugins and subagents.

What do skills look like in practice?

The directory's data gives a sense of the range. Skills tagged for skill authoring include Anthropic's Skill Creator, which walks the agent through drafting a skill, testing it on sample prompts and tuning its description. Debugging has Systematic Debugging, which requires the agent to find a root cause before it proposes any fix. Planning has Writing Implementation Plans, which turns a spec into small tasks.

Notice that none of these is a tool in the sense of an API. Each one is a way of working that the agent adopts when the task fits. That is the difference between a skill and a connector, and it is why a skill can be read, forked and edited like any other text file in a repository. The top skills page shows which ones people use most.

What should you check before installing one?

A skill is instructions plus any scripts it ships, and it runs with the permissions of your agent session. Treat it the way you would treat a shell script from the internet.

• Read SKILL.md and every file under scripts/.
• Look at allowed-tools, an optional field that pre-approves tools while the skill runs.
• Check the licence. Anthropic's repository states that most of its skills are Apache 2.0, while its document skills (docx, pdf, pptx, xlsx) are source-available rather than open source.
• Prefer repositories you trust, and pin a version when your install tool supports it.

Each skill page in this directory shows its licence and the result of an automated safety check, which is a starting point and not a substitute for reading the files. When you are ready to try one, how to add skills to Claude Code lists four install methods.