A Claude skill is a folder with a Markdown file in it. The file is named SKILL.md. It starts with a few lines of metadata, and the rest is plain instructions written for an AI agent to read. Anthropic announced the format on October 16, 2025, and "claude skills" went from an internal pattern to a thing people search for almost overnight. If you just heard the term and want to know what a skill actually is before anyone sells you on building one, this is the page.
No code runs to make a skill exist. You write a folder, and Claude reads it when the moment calls for it. The part worth understanding is when and how it reads it, which I'll get to.
What a Claude skill actually is
Here is a complete, valid skill:
pdf-processing/
└── SKILL.md
And here is what's inside that file:
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills PDF forms, and
merges multiple PDFs. Use when working with PDF documents or when the user
mentions PDFs, forms, or document extraction.
---
# PDF processing
Step-by-step instructions the agent follows when this skill is active...
Two parts. The top, between the --- fences, is YAML frontmatter: structured metadata. The required fields are name and description, and per the Agent Skills specification the name maxes out at 64 characters (lowercase letters, numbers, hyphens) and the description at 1024. Everything below the second --- is the body: Markdown prose telling the agent how to do the task. Recommended sections are step-by-step instructions, example inputs and outputs, and common edge cases. There are no format rules for the body, so you write whatever helps the agent do the work.
A skill can hold more than one file. The convention is a scripts/ folder for code the agent can run, a references/ folder for longer documentation it pulls in only when needed, and an assets/ folder for templates or data. None of that is required. The minimum viable skill is one SKILL.md and nothing else.
The frontmatter has a few optional fields too, and they're worth knowing by name even at the definition stage. license records how the skill may be reused. compatibility flags environment needs, like "Requires Python 3.14+ and uv" or "Designed for Claude Code." metadata is a free-form key-value bag for things like author and version. And there's an experimental allowed-tools field that pre-approves specific tools the skill is permitted to run. You will not touch most of these on day one. They exist so the format scales from a five-line note to a production skill an organization audits.
So when someone says "I wrote a Claude skill," they wrote a folder. When they say "I installed a skill," they copied a folder into a directory the agent watches. The format is deliberately boring, and that plainness is the whole point.
The open standard underneath
The thing that makes skills worth a definition article is that they are not a Claude-only feature. Anthropic released the format as an open standard called Agent Skills, and the spec lives in the open. The format was developed by Anthropic, then handed to the broader community, and other agent tools adopted it.
More tools than you'd guess have picked it up. Cursor reads skills. OpenAI's Codex supports them. Gemini CLI documents them. So do OpenCode, Goose, GitHub Copilot, VS Code, Amp, and a long tail of others listed on the standard's site. One SKILL.md folder, written once, gets read by agents from three or four different companies. To me that portability is the strongest argument for the format existing at all, because you are not betting your reusable instructions on one vendor's roadmap.
A small but telling detail from the Claude Code docs: custom slash commands and skills have merged. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create a /deploy command and behave the same way. Older command files keep working. Skills are the superset, adding a folder for supporting files, frontmatter to control invocation, and automatic loading when relevant.
Progressive disclosure, or why skills don't bloat your context
This is the mechanism that makes skills more than a renamed text snippet. Agents load them in stages, a design the spec calls progressive disclosure.
Stage one, discovery. When the agent starts, it reads only the name and description of every skill you have, roughly 100 tokens each. That's all. It now knows that a "pdf-processing" skill exists and what it's for, but it has not read the instructions.
Stage two, activation. When your task matches a description, the agent pulls the full SKILL.md body into context. The spec recommends keeping that body under 5000 tokens and under 500 lines.
Stage three, execution. If the skill references a script or a long reference file, the agent loads that only at the moment it's needed.
The payoff is concrete. You can keep dozens of skills installed and the agent carries almost none of their weight until one becomes relevant. A 4000-word reference document sitting in a skill costs you about a sentence of context, the description line, right up until the second you need the whole thing. This is why the description field is the most load-bearing text you'll write. It is the only part the agent always sees, so it has to say both what the skill does and when to reach for it. "Helps with PDFs" is a bad description. The long, keyword-rich version above is a good one, because the agent decides whether to activate based almost entirely on that string.
How a skill differs from a prompt, a command, a plugin, and an MCP server
People conflate these constantly, so here is the beginner-level map.
A prompt is something you type once and it's gone. You paste a checklist into chat, the agent follows it for that conversation, and tomorrow you paste it again. A skill is that same checklist saved to disk, named, and loaded automatically when the work matches, so you stop re-pasting. If you keep typing the same instructions into Claude, you have found a skill you haven't written yet.
A slash command was the older Claude Code way to save a reusable instruction as a file you'd trigger by hand. As noted above, commands and skills have converged. A command is roughly a skill you always invoke yourself, where a full skill can also load on its own when the description matches.
A plugin is a heavier, tool-specific package, often bundling executable extensions and UI hooks for one particular app. Skills are lighter and more portable. A skill is text and maybe some scripts in a folder, readable by many agents. A plugin tends to be code wired into one host.
An MCP server is the one worth getting right, because it's the most common mix-up. MCP (Model Context Protocol) connects an agent to live tools and data: a running process the agent calls to query your database, hit an API, or read a ticketing system. It gives the agent new capabilities and connections. A skill gives the agent knowledge and procedure: how to do a task, in what order, with which conventions. One is a wire to a system; the other is an instruction sheet. They compose well together, and a skill can even tell the agent to call an MCP tool. If you want the full comparison, read SKILL.md vs MCP, which goes deeper than I will here.
The short version: a skill teaches, an MCP server connects, a prompt is a one-off, a command is a manual trigger, and a plugin is app-specific machinery.
Why the format matters now
Two reasons, and they reinforce each other.
The first is reuse without lock-in. Before an open skill standard, the knowledge you fed an agent lived in chat history, scattered CLAUDE.md files, or some vendor's proprietary config. Move tools and you started over. A SKILL.md folder is a portable artifact instead. You check it into git, version it like code, and carry it to whatever agent you use next quarter. The same folder works in Claude Code, Cursor, Codex, and Gemini CLI today, with no rewrite.
The second is that progressive disclosure changes the economics of giving an agent expertise. You no longer pay a context tax for knowledge the agent isn't currently using. That makes it sane to maintain a library of twenty narrow skills instead of one bloated mega-prompt that eats your context window on every turn. Each one stays narrow and named, and the agent loads it only on demand. Anthropic ships its own document-handling skills (PDF, DOCX, PPTX, XLSX) this exact way in production Claude, with the source available in the anthropics/skills repo as reference implementations.
There's a quiet implication here for who gets to build agent capabilities. Because a skill is just structured writing, the bottleneck is no longer "can you code an integration." It's "can you describe a procedure clearly." That opens skill authoring to the people who actually own the procedure, the ops lead, the brand manager, the compliance reviewer, even when they've never touched a terminal. Tools like Knack lean directly into that, turning a short interview into a finished SKILL.md folder so a non-coder can ship one. But the format itself is the reason that's even possible.
So, what is a Claude skill?
A folder with a SKILL.md file: a name, a description, and instructions an agent reads when your task matches. Open standard, portable across tools, loaded progressively so it costs nothing until used. That's the definition. The next questions are usually "how do I use one" and "how do I build one," and those have their own pages: start with how to use Claude skills, then build a skill with no code when you're ready to write your own.