What are Claude Skills, really?

The short answer

A Claude Skill is a folder that packages one workflow: instructions, and optionally scripts or reference files, that Claude reads from the filesystem when a task calls for it. Anthropic shipped Agent Skills as a way to give Claude domain-specific expertise without re-explaining it in every conversation. Instead of pasting the same five paragraphs of house style, compliance rules, or step order into every chat, you write it once as a skill, and Claude picks it up automatically when your request matches.

The format is deliberately plain. There is no build step, no schema beyond two YAML fields, and no proprietary runtime: a skill is a directory Claude can read the same way it reads any other file on a filesystem it has access to. That simplicity is also what makes skills portable: the same folder works in Claude Code, in claude.ai, and through the API, with only the installation step differing between surfaces.

The SKILL.md format

Every skill needs exactly one required file, SKILL.md, with YAML frontmatter followed by markdown instructions:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge
  documents. Use when working with PDF files or when the user mentions
  PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start
Use pdfplumber to extract text from PDFs...

Two frontmatter fields are required, and both have real constraints:

• name: maximum 64 characters, lowercase letters, numbers and hyphens only, no XML tags, and it cannot contain the reserved words "anthropic" or "claude".
• description: non-empty, maximum 1024 characters, no XML tags. This is the field Claude matches your request against, so it has to state both what the skill does and when to use it, not just the former.

Everything below the closing --- is the skill's body: plain markdown instructions, written the way you would onboard a capable new hire who has never done this specific task before. A skill can also bundle extra files next to SKILL.md, such as a detailed reference doc or a small script, which the instructions can point to by name.

Why skills load in stages: progressive disclosure

The reason skills scale to dozens of installed folders without bloating every conversation is progressive disclosure: content only enters Claude's context window at the moment it is actually needed, in three levels.

• Level 1, metadata, always loaded. At startup, Claude loads only the name and description from every installed skill's frontmatter, roughly 100 tokens per skill. This is what makes it cheap to have many skills installed at once.
• Level 2, instructions, loaded when triggered. When your request matches a skill's description, Claude reads the full SKILL.md body, ideally under about 5,000 tokens. Only now does the actual procedure enter context.
• Level 3, bundled resources, loaded as needed. If the instructions reference another file, a reference doc or a script, Claude reads or runs that specific file only if the task requires it. A skill can ship extensive reference material with no context cost for the parts a given task never touches.

That staged model is why a skill with dozens of edge cases documented in a companion file costs nothing extra on the 90% of runs that never hit those edge cases: the file simply is not read unless it is needed.

How Claude discovers and loads a skill

Concretely, here is the sequence for a task that matches an installed skill:

1. At session start, the skill's name and description sit in the system prompt alongside every other installed skill's metadata.
2. You make a request that matches the description's trigger condition.
3. Claude runs a filesystem read, effectively cat SKILL.md, and the instructions enter context.
4. If the instructions point to another file, Claude reads that file too, only if the current task needs it.
5. If the instructions call a script, Claude executes it and only the script's output, not its source, enters context.

Nothing about this requires you to invoke a skill by name, though you usually can if the surface supports it. The default path is description matching: a good description is the entire discovery mechanism, which is why writing one well matters more than almost anything else about a skill (more on that in the authoring guide linked below).

A worked example makes the sequence concrete. Say a skill named pdf-processing is installed, with the description shown earlier. Here is what actually happens end to end:

1. At startup, the system prompt already contains one line for this skill: its name and description, nothing else.
2. You ask: "Extract the text from this PDF and summarize it."
3. The request matches the description, so Claude reads SKILL.md from the filesystem and its instructions enter context.
4. The instructions mention a separate FORMS.md for form filling. This task has nothing to do with forms, so Claude never reads that file, and it costs zero tokens.
5. Claude follows the instructions that were loaded, using the bundled extraction approach they describe, and returns the summary.

Notice what did not happen: nothing about form filling ever entered context, even though the skill folder contains a whole file about it. That is progressive disclosure working as intended, not a special case.

Personal, project and plugin skills

In Claude Code specifically, a skill lives in one of three places, and the choice changes who else can see it:

• Personal, at ~/.claude/skills/. Yours, works across every project on your machine, invisible to anyone else.
• Project, at .claude/skills/ inside a repository. Travels with the repo, so a teammate who clones it gets the skill too, without a separate install step.
• Plugin, bundled inside a plugin's skills/ directory and distributed through a marketplace. Plugin skills are namespaced, for example /my-plugin:review, so two plugins can each ship a skill with the same folder name without colliding.

On claude.ai, custom skills work differently again: each user uploads their own as a zip file, they do not sync organization-wide, and admins cannot centrally manage them. On the API, uploaded skills are shared workspace-wide instead. The filesystem-based personal, project and plugin model above is specific to Claude Code.

One consequence worth planning around: custom skills do not automatically follow you between surfaces. A skill uploaded to claude.ai is not available through the API, a skill uploaded through the API is not available on claude.ai, and Claude Code skills are filesystem-based and separate from both. If you use the same workflow in more than one surface, expect to set the skill up once per surface, not once total.

What a real skill looks like

The clearest way to see the format is to read a complete, working SKILL.md rather than a fragment. SkillCrate ships two full samples on its storefront with no email required: a list-building skill that pulls a compliance-scrubbed lead list from public sources, and an inbox-triage skill that sorts a full mailbox into a decision queue. Both are exactly the frontmatter-plus-instructions structure covered above, at production length rather than a toy example.

For the official reference, Anthropic's own documentation covers the format at platform.claude.com, and publishes open-source example skills at github.com/anthropics/skills. Claude Code's own skills docs live at code.claude.com. If you are ready to write your own, the next guide in this set walks through a full worked example.