Claude Skills Explained: How SKILL.md Files Teach an Agent a Job

If you have asked Claude to make a spreadsheet or a slide deck, you have already used a skill. Anthropic shipped Skills on 16 October 2025, published the format as the Agent Skills open standard on 18 December 2025, and by September 2026 the same folder layout runs in Claude.ai, Claude Code, the Claude API and in agents from Cursor, OpenAI, GitHub and Google. This guide covers what Claude Skills are, how Claude decides to load one, what goes in the file, where they run, and what changed recently.

Claude Skills are folders of instructions, scripts and reference files that Claude loads only when a task matches the skill's description. Each skill is a directory with a SKILL.md file whose YAML frontmatter carries a name and a description; the Markdown body holds the procedure, and optional scripts run through bash without their code ever entering the context window.

How Claude Skills work

Skills exist because prompts do not scale. A prompt is a one-off instruction for one conversation; a skill is a filesystem resource Claude can find again. Anthropic's docs describe skills as onboarding material for a new team member: workflows, context and conventions that turn a general agent into a specialist.

The mechanism is progressive disclosure, in three levels.

Level	When loaded	Token cost	Content
1: Metadata	Always, at startup	About 100 tokens per skill	`name` and `description` from the frontmatter
2: Instructions	When the skill is triggered	Under 5,000 tokens	The `SKILL.md` body
3: Resources	As needed	Nothing until accessed	Bundled files; scripts run through bash and only their output enters context

At startup Claude reads only the frontmatter of every installed skill and puts the names and descriptions in its system prompt. The description is what your request is matched against, so it has to say both what the skill does and when to use it. When a request matches, Claude reads SKILL.md from disk with bash and only then does the body cost tokens. If the body points at FORMS.md or a database schema, Claude reads those too, only when needed; if it points at validate_form.py, Claude runs it and sees only the output.

Anthropic's worked example is a custom pdf-processing skill. The system prompt carries one line: the name and a description that mentions PDFs, forms and document extraction. A user asks to extract the text from a PDF and summarise it. Claude runs cat pdf-processing/SKILL.md, decides form filling is not needed so never opens FORMS.md, and does the job from the instructions it just loaded. Dozens of reference files can sit in a skill at zero cost until one is read.

Anatomy of a SKILL.md file

The Agent Skills specification at agentskills.io defines the format. A skill is a directory containing, at minimum, SKILL.md, with optional scripts/, references/ and assets/ folders:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

The frontmatter fields:

Field	Required	Rule
`name`	Yes	1 to 64 characters, lowercase letters, digits and hyphens; no leading, trailing or double hyphens; must match the directory name
`description`	Yes	1 to 1,024 characters; says what the skill does and when to use it
`license`	No	A licence name or a reference to a bundled licence file
`compatibility`	No	Up to 500 characters of environment requirements, such as required packages or network access
`metadata`	No	A map of string keys to string values for anything the spec does not define
`allowed-tools`	No	A space-separated list of pre-approved tools; experimental

A minimal skill is two lines of frontmatter and some Markdown:

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

# PDF Processing

Use pdfplumber to extract text from PDFs. For advanced form filling, see [FORMS.md](FORMS.md).

The spec's advice on the body is short: step-by-step instructions, examples of inputs and outputs, common edge cases. Keep SKILL.md under 500 lines and move long reference material into references/, because the whole file loads once the skill activates. Keep file references one level deep and use relative paths from the skill root. The skills-ref validate ./my-skill command from the reference library checks the frontmatter and naming rules. One rule from Anthropic's best-practice guidance that trips people up: a skill name cannot contain the reserved words "claude" or "anthropic", which is why Anthropic renamed its own claude-academy-guide skill to academy-guide before it could be uploaded as a custom skill.

Where Claude Skills run

Claude API. Skills require the code execution tool, whose container they run in. You reference a pre-built skill by its skill_id (pptx, xlsx, docx or pdf) in the container parameter, or upload your own through the /v1/skills endpoints. Custom skills are shared across the workspace. The sandbox has no network access and no runtime package installation. Claude Platform on AWS and Microsoft Foundry inherit the same behaviour.

Claude Code. Custom skills are plain directories: ~/.claude/skills/<name>/SKILL.md for every project you work on, .claude/skills/<name>/SKILL.md for one project, or <plugin>/skills/<name>/SKILL.md inside a plugin. Claude loads them automatically when relevant, and you can invoke one directly as /name. Custom commands have been merged into skills, so a .claude/commands/deploy.md and a .claude/skills/deploy/SKILL.md both create /deploy. Claude Code adds features on top of the standard: control over whether you or Claude may invoke a skill, running a skill in a subagent, and dynamic context injection. That last one is worth knowing: a line such as !`git diff HEAD` inside the body is executed and replaced with its output before Claude reads the skill, so a /summarize-changes skill arrives with the live diff already inlined. Skill files are watched for changes within a session, nested .claude/skills/ folders in a monorepo apply when Claude works on that package, and bundled skills such as /code-review, /debug, /batch, /loop, /run and /verify ship with the tool. The pre-built document skills are not available in Claude Code, but the open-source Claude API skill is.

Claude.ai. The pre-built document skills are active whenever you create files. Custom skills upload as zip files under Settings, Features, on Pro, Max, Team and Enterprise plans with code execution enabled. They are per-user; admins cannot manage them centrally on those plans, though the pricing page lists organisation-wide skills deployment for Team and Enterprise.

Cowork and cloud sessions do not read ~/.claude/skills/ on your machine. They load the skills enabled for your Claude.ai account at session start, and cloud sessions also load skills committed to the repository's .claude/skills/.

Examples

Anthropic's public repository at github.com/anthropics/skills has 174,100 stars and holds the document skills that power file creation in Claude apps (docx, pdf, pptx and xlsx, source-available rather than open source), plus Apache-licensed examples spanning creative work, testing web apps, MCP server generation and enterprise communications. In Claude Code it installs as a plugin marketplace:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

The skills listed on AI Agents Listing show the range. Anthropic Document Skills is that document set. Frontend Design Skill is the one Anthropic updated on 3 September 2026 to avoid generic design defaults. Superpowers is a community skill library that packages an entire engineering workflow, from brainstorming to test-driven development, as skills that call each other.

Vendors now ship skills as their onboarding path. Firecrawl publishes an agent-onboarding SKILL.md an agent can fetch to obtain its own API key, and its CLI's init command installs its skills into Cursor, Claude Code and Windsurf. Browser Use's quickstart tells a coding agent to run browser-use skill install. Anthropic's commerce agent blueprint, released on 2 September 2026, ships its catalog search, personalisation, sales analytics and inventory capabilities as skills alongside a Claude Code plugin.

Claude Skills vs CLAUDE.md vs MCP

These three get confused because all of them "give Claude context". They answer different questions.

CLAUDE.md holds facts. Coding standards, architecture decisions, which library to use. It is read at the start of every session, so everything in it costs tokens every time. Claude Code's own guidance is to move a section into a skill when it has grown into a procedure rather than a fact, or when you keep pasting the same checklist into chat.
A skill holds a procedure. It loads only when used, so long reference material is nearly free until needed, and it can carry scripts for the steps where code is more reliable than generation.
MCP connects tools and data. The Model Context Protocol is how Claude reads Google Drive, updates Jira or calls your own service. A skill can tell Claude how to use an MCP server well; it cannot replace one.

Skills beyond Claude

Agent Skills is an open standard, and the client showcase at agentskills.io lists Cursor, Claude Code, GitHub Copilot, VS Code, Gemini CLI, Codex, Goose, OpenHands, Roo Code, Amp, Kiro, Junie, OpenCode and dozens more. The format is identical; the extensions differ.

OpenAI's Codex reads skills from .agents/skills in the working directory and every parent up to the repository root, from ~/.agents/skills, from /etc/codex/skills and from a bundled system set. You mention one with $skill-name in Codex or @skill-name in ChatGPT, or let it trigger implicitly from the description. The initial skills list is capped at 2% of the model's context window (8,000 characters when the window is unknown), so Codex shortens descriptions first and may omit skills when many are installed. An optional agents/openai.yaml sets display metadata, declares MCP dependencies, and can set allow_implicit_invocation: false. A $skill-creator drafts one from a description and Record & Replay drafts one from a demonstration.

Cursor includes skills on every paid plan next to MCPs and hooks, and its 19 August 2026 release added custom modes: pick a skill from / and press Option-Enter to pin it as an always-on mode. Teams plans get a marketplace for internal rules, skills and plugins.

When to use Claude Skills (and when not)

Use a skill when a task repeats and has steps: a release checklist, a data-analysis pipeline, a document format, a brand guideline. Use one when part of the job is better done by a script than by a model, since a script's code never enters context and its output is deterministic. Use one when several people or agents need the same workflow, because a folder is versionable and portable across clients.

Do not use a skill for a fact that applies to every session; that is CLAUDE.md. Do not use one to reach live data or external systems; that is MCP. Do not write a description that only says "helps with PDFs", because the description is the trigger and a vague one either never fires or fires constantly. And treat skills from strangers as code, because that is what they are: Anthropic's own announcement warns that skills can execute code and that you should stick to trusted sources.

What's new (as of 3 September 2026)

Anthropic updated the frontend-design skill in the public repository on 3 September 2026 to avoid generic design defaults. The repository is at 174,100 stars and 54 commits.
The commerce agent blueprint Anthropic released on 2 September 2026 packages its shopping and merchant agent capabilities as skills, with a Claude Code plugin to customise them.
Claude Code now loads nested .claude/skills/ directories in monorepos under directory-qualified names, watches skill files for live changes, and ships /run, /verify and a /run-skill-generator that records how to launch your app as a per-project skill.
Cursor added custom modes on 19 August 2026, pinning any skill as an always-on mode.
Codex documents .agents/skills discovery, the 2% context budget for the skills list, $skill-creator, $skill-installer and agents/openai.yaml, and positions plugins as the way to distribute skills across ChatGPT and Codex.
Agent Skills opened an official Discord server, announced on the agentskills.io site.
Vendor skills are becoming the default onboarding path: Firecrawl's agent-onboarding SKILL.md and Browser Use's browser-use skill install both arrived this summer.

Key takeaways

A Claude Skill is a directory with a SKILL.md whose frontmatter needs only name (64 characters, lowercase and hyphens) and description (1,024 characters).
Only the name and description are loaded at startup, about 100 tokens per skill; the body loads when triggered and bundled files only when read.
Skills run in the Claude API through the code execution tool, in Claude Code from ~/.claude/skills/ or .claude/skills/, and in Claude.ai as uploaded zips on paid plans.
Claude Code extends the standard with invocation control, subagent execution and dynamic context injection such as !`git diff HEAD`.
The same folder works in Cursor, Codex, Copilot, Gemini CLI and other clients that implement the Agent Skills standard.

FAQ

What is a Claude skill?

A Claude skill is a folder containing a SKILL.md file with instructions, plus optional scripts and reference files, that Claude loads when a task matches the skill's description. Anthropic introduced Skills on 16 October 2025 and published the format as the Agent Skills open standard on 18 December 2025.

How do I create a skill in Claude Code?

Create ~/.claude/skills/<name>/SKILL.md for a personal skill or .claude/skills/<name>/SKILL.md inside a project, with frontmatter that describes what the skill does and when to use it, followed by the instructions. Claude Code detects the file within the session, loads it when a request matches, and lets you run it directly as /name.

Are Claude skills the same as MCP?

No. MCP is a protocol for connecting Claude to external tools and data such as Google Drive, Jira or your own API. A skill is a set of instructions and scripts for a procedure. Skills often describe how to use an MCP server well, and the two are used together.

Can I use Claude skills in Cursor or Codex?

Yes. The SKILL.md format is the Agent Skills open standard, and Cursor, Codex, GitHub Copilot, Gemini CLI and others implement it. Codex reads skills from .agents/skills and Cursor includes skills on paid plans. Claude Code-specific frontmatter extensions such as invocation control may be ignored elsewhere.

Do skills cost tokens when they are not used?

Only the frontmatter does: about 100 tokens per installed skill for the name and description in the system prompt. The body and any bundled files cost nothing until the skill is triggered and the files are read.

AI Agents Listing keeps a growing Skills directory alongside its agents and MCP servers.