Claude Skills Explained — Anthropic's New Feature

On October 16, 2025, Anthropic launched Agent Skills — folders of instructions, scripts, and reference files that Claude reads from a filesystem and loads only when a task actually needs them (Anthropic engineering blog). Two months later, on December 18, 2025, Anthropic made the format an open standard, adding a partner directory with contributions from Atlassian, Canva, Notion, Figma, Cloudflare, Stripe, and Zapier (SiliconANGLE). This article explains exactly how the loading mechanism works, what it costs in tokens, where Skills run, how they differ from the Model Context Protocol (MCP) — a separate standard Anthropic also created — and how to build, test, and secure your own.

What Is a Claude Skill?

A Claude Skill is a directory that contains at minimum one file: SKILL.md, with YAML frontmatter specifying a name and a description. Anthropic's own definition calls Skills "organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks" (Anthropic engineering blog).

Beyond the required SKILL.md, a Skill folder can hold:

• Additional markdown files — a FORMS.md or REFERENCE.md that Claude only opens if the task calls for that level of detail
• Executable scripts — Python, Bash, or Node.js code that Claude runs through its bash tool rather than generating on the fly
• Reference resources — database schemas, API documentation, brand templates, JSON configuration

Anthropic's own framing is useful here: a Skill folder is organized "like an onboarding guide you'd create for a new team member" — one top-level document that orients a new hire, with deeper reference material they only pull up when a specific situation demands it (Claude Platform Docs). That's a genuinely different mental model than the "one giant system prompt" approach most Claude users grew up with. Instead of pasting the same 3,000-word style guide into every conversation, you write it once as a Skill, and Claude expands it only in conversations where it's relevant.

Metadata for an installed Skill costs roughly 100 tokens. The full SKILL.md body, loaded only when triggered, typically stays under 5,000 tokens. Anything a Skill references beyond that — reference files, datasets, scripts — costs zero tokens until Claude actually opens it ([Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)).

How Skills Work — The Progressive Disclosure Mechanism

The engineering decision that makes Skills scale is called progressive disclosure: Claude is shown almost nothing about a Skill until it needs it, then reveals more information in stages as the task requires it. Anthropic's documentation breaks this into three formal levels.

Level 1 — Metadata, always loaded. At the start of a session, Claude's system prompt includes just the name and description field from every installed Skill's frontmatter. This is deliberately cheap: roughly 100 tokens per Skill, which means a user or team can have dozens of Skills installed and pay almost nothing until one actually fires.

Level 2 — Instructions, loaded on trigger. When a user's request matches a Skill's description closely enough, Claude reads the body of SKILL.md from the filesystem using its bash tool. That content — typically under 5,000 tokens — enters the context window for the first time at this point, not before.

Level 3 — Resources and code, loaded as needed. If the SKILL.md instructions point to a FORMS.md or a scripts/validate.py, Claude only opens those files if the specific sub-task calls for them. Scripts are executed rather than read: their source code never enters the context window, only their output does (Claude Platform Docs).

Think of it like a library with a card catalog. You don't carry every book in the building around with you all day — you check the catalog card (Level 1), pull the one book you need off the shelf (Level 2), and only photocopy the specific appendix page if the chapter tells you to (Level 3). The library can hold a million volumes and your backpack still only ever gets heavier by the page count you actually read.

A second useful analogy: Skills behave like lazily-loaded software modules in a large codebase. A Python project can import a 50,000-line library, but the interpreter doesn't parse every function in that library into memory upfront — it resolves what's actually called. Progressive disclosure does the same thing to Claude's context window, which is a hard, finite resource that every extraneous token competes for.

How does Claude decide which skill to use?

Claude matches the user's request against each installed Skill's description field, which Anthropic requires to state both what the Skill does and when Claude should use it. A well-written description like "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" gives Claude the triggering signal without loading the rest of the Skill.

What happens if two skills could both apply?

Claude can load and combine multiple Skills in one session — Anthropic's documentation lists "compose capabilities" as one of the three core benefits, alongside specialization and reduced repetition (Claude Platform Docs). There's no formal priority system published; in practice, the model reasons about which Skill (or combination) best matches the request the same way it reasons about which tool to call.

A Minimal Skill Example

Here's the shape of the smallest real Skill, following Anthropic's own field requirements: name must be 64 characters or fewer, lowercase letters/numbers/hyphens only, and cannot contain the words "anthropic" or "claude." description must be non-empty and under 1,024 characters (Claude Platform Docs).

pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    └── fill_form.py

SKILL.md:

---
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:

'''python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
'''

For advanced form filling, see FORMS.md.

Walk through what happens when a user says "extract the text from this PDF and summarize it," per Anthropic's own worked example: Claude's system prompt already contains the one-line description from Level 1. The request matches it, so Claude runs cat pdf-processing/SKILL.md via bash, pulling the Level 2 instructions into context. Because the task doesn't involve filling a form, FORMS.md never gets opened — that reference material stays on disk costing nothing (Claude Platform Docs).

Where Skills Run

Skills work across four Anthropic surfaces, but — and this is a detail people frequently get wrong — they do not automatically sync between them.

Surface	How Skills load	Sharing scope	Network access
Claude Code	Auto-discovered from .claude/skills/ (project) or ~/.claude/skills/ (personal)	Personal or project-based; can be distributed via Claude Code Plugins	Full — same as any program on the user's machine
Claude.ai	Uploaded as a zip through Settings → Features	Individual user only; not shared org-wide, not centrally managed by admins	Full, partial, or none, depending on user/admin settings
Claude API	Uploaded via the /v1/skills endpoint, invoked by skill_id in the container parameter	Workspace-wide — all workspace members can access an uploaded Skill	None; sandboxed container, no runtime package installs
Claude Agent SDK	Same mechanism as the API	Workspace-wide	Depends on the sandbox configuration

Table: How Skills load and share across Anthropic's four product surfaces, per Claude Platform Docs.

Using Skills through the Claude API requires the code execution tool (the sandboxed container Skills run inside) plus the beta header skills-2025-10-02. If a Skill needs to read or write files via the Files API, you add a second header, files-api-2025-04-14 (Claude Platform Docs).

The cross-surface gap matters in practice: a Skill you build and test in Claude Code lives in a git-trackable folder, but it will not appear in claude.ai or the API until you separately package and upload it there. Anthropic is explicit about this in its own docs — "Skills uploaded to claude.ai must be separately uploaded to the API," and Claude Code Skills are "filesystem-based and separate from both." Teams standardizing on Skills across a whole organization need a deliberate distribution plan, not an assumption that one upload covers everything.

Built-in Skills From Anthropic

Anthropic ships four pre-built document Skills, available on the Claude API, Claude Platform on AWS, Microsoft Foundry, and claude.ai:

• pptx — create and edit PowerPoint presentations, including chart generation
• xlsx — create and manipulate Excel spreadsheets, including formulas and reports
• docx — create and edit Word documents with formatting
• pdf — generate formatted PDF documents and reports

Notably, these four pre-built Skills are not available inside Claude Code itself, though an open-source "Claude API skill" — which bundles up-to-date API reference material and SDK documentation for eight programming languages — ships with Claude Code by default and is published in Anthropic's public skills repository (Claude Platform Docs).

The rationale behind the document Skills is architectural, not cosmetic. Anthropic's engineering post frames it directly: Skills let Claude use "executable code for precise tasks like creating Excel spreadsheets with formulas... areas where traditional code excels over pure language generation." Before Skills, an LLM asked to build a formula-driven spreadsheet had to generate the entire XML structure of an .xlsx file as text — slow, and prone to subtly malformed output. A Skill instead hands Claude a deterministic Python script that does the file manipulation correctly every time, and Claude's job shifts from "generate the file" to "decide what the script's inputs should be."

Skills vs MCP — They're Complementary, Not Competing

The most common point of confusion for anyone reading about Claude Skills for the first time: aren't Skills the same thing as MCP servers? They are not, and the difference is architectural, not just semantic.

MCP (Model Context Protocol) is a network protocol. An MCP server is a running process — local or remote — that exposes tools and resources to any MCP-compatible client over a defined wire format (JSON-RPC). MCP was itself an Anthropic-originated open standard, and it has since been transferred to the Linux Foundation, becoming the de facto way agentic AI systems connect to live external services (SiliconANGLE).

Skills are local folders of static files. Nothing is "running" — there's no server, no persistent process, no network handshake. The host application (Claude Code, claude.ai, or the API's sandboxed container) reads files off a filesystem when Claude asks for them.

A useful shorthand: MCP is to Skills roughly what an API call is to a reference manual. When you need a database's live, current row, you call the database — that's what MCP servers are for. When you need to remind an already-capable model how your team formats a quarterly report, or which script reliably builds a compliant PDF, you hand it a folder — that's what a Skill is for.

	MCP	Skills
What it is	Network protocol / running server process	Static folder of files
Connects to	Live external systems (databases, GitHub, Slack, Linear)	Nothing — it's local content
Governance body	Linux Foundation (as of late 2025)	Open standard, Anthropic-led, partner directory
Typical use	Real-time data, external API actions	Repeatable procedures, document generation, brand rules
Context cost when idle	Tool schemas loaded per connected server	~100 tokens per installed Skill (metadata only)

Table: MCP and Skills solve different problems and are usually deployed together, not as alternatives.

You'll frequently use both in a single Claude Code session: an MCP server connects Claude to your company's live Jira instance, while a Skill tells Claude the specific formatting your team expects when it files a new ticket. The AI agents explained guide covers where both of these fit inside a broader agent architecture that also includes planning and memory.

Skills vs Other Extension Mechanisms

Mechanism	Format	Where It Runs	Best For
Claude Skills	Folder + SKILL.md + scripts	Local filesystem (Claude Code, Claude.ai, sandboxed API container)	Reusable workflows, document creation, brand rules
MCP servers	Network protocol	Process (local or remote)	Live data, external APIs, databases
System prompts	Single text block	Inline in every request	Persistent persona and instructions
Custom Instructions	UI text fields	Inline in Claude.ai	Personal preferences
OpenAI GPTs	Hosted config + actions	OpenAI servers	ChatGPT-only assistants
Cursor .cursorrules	Single file	Cursor IDE	Editor-specific coding rules
Claude CLAUDE.md	Single markdown file	Claude Code session	Project-wide context for one repository

Table: Where Claude Skills sit among the extension mechanisms available across major AI coding and chat tools.

The simplest mental model: Skills are to Claude what a well-organized reference shelf is to a new employee — folder-driven, and read only a page at a time, rather than memorized cover to cover on day one.

Creating Your Own Skill

The fastest path uses Anthropic's own skill-creator meta-skill, which is included with Claude Code and ships as part of the open-source skills repository. In a Claude Code session you can ask, in plain language, to "create a skill that does X," and skill-creator scaffolds the folder, drafts a compliant SKILL.md, and validates the frontmatter fields against Anthropic's format rules.

The manual path is just as viable for a simple Skill:

1. Create a folder under ~/.claude/skills/your-skill-name/ (personal) or .claude/skills/your-skill-name/ (project-scoped, so it's committed to the repo and shared with teammates).
2. Add SKILL.md with a name and description in YAML frontmatter, following the character limits above.
3. Write the instruction body — clear, step-by-step guidance, the same way you'd document a process for a new hire who's competent but unfamiliar with your specific conventions.
4. Add any scripts under a scripts/ subfolder if the task benefits from deterministic code rather than generated text.
5. Test by starting a new Claude session and issuing a prompt that should match your description field. Watch whether Claude actually triggers it — if it doesn't, the description is usually too vague or doesn't state clearly enough when to use the Skill.

How do I share a Skill with my team?

In Claude Code, commit the Skill folder under .claude/skills/ inside your project repository — anyone who clones the repo gets it automatically, and Claude Code Plugins can also distribute Skills more broadly. On the API, upload once through the /v1/skills endpoint and it becomes available workspace-wide. On claude.ai, sharing is currently per-user only — there is no admin-level organization-wide distribution yet, a limitation Anthropic states explicitly in its own documentation (Claude Platform Docs).

Do Skills sync automatically between Claude Code, claude.ai, and the API?

No. Anthropic's documentation is explicit that custom Skills do not sync across surfaces: a Skill uploaded to claude.ai must be separately uploaded to the API, and Claude Code Skills, being filesystem-based, are entirely separate from both. Plan distribution per surface rather than assuming one upload covers everything.

Security Considerations — Why "Just a Folder" Still Needs Auditing

Because a Skill can bundle executable code and can direct Claude to invoke bash commands, file operations, or network calls, Anthropic's own security guidance treats Skills the same way a security team would treat installing third-party software: use only Skills you wrote yourself or obtained directly from Anthropic, and if you must use one from an unfamiliar source, audit every bundled file — SKILL.md, scripts, images, everything — before letting Claude run it (Claude Platform Docs).

The specific risks Anthropic calls out:

• External fetches inside a Skill are the highest-risk pattern. A Skill that pulls content from a URL can have that content silently contain instructions that Claude then follows, even if the Skill itself was originally trustworthy — its external dependency can change after the fact.
• Tool misuse. A malicious Skill's instructions can direct Claude to run file operations or bash commands well outside what its stated description implied.
• Data exposure. A Skill with legitimate access to sensitive files could, in principle, be written to quietly send that data somewhere external.

For enterprise deployments, Anthropic separately documents governance and vetting workflows for Skills at scale, and notes that Agent Skills is not currently covered by Zero Data Retention (ZDR) arrangements — Skill definitions and execution data follow Anthropic's standard retention policy rather than a stricter no-retention agreement (Claude Platform Docs). If your organization has ZDR contractual requirements, that's a real constraint worth flagging to your security team before rolling Skills out broadly.

Skills as an Open Standard — What Changed in December 2025

Two months after launch, Anthropic reframed Skills from an Anthropic-only feature into an open standard other vendors could adopt. The December 18, 2025 announcement added three things: organization-wide Skill management for Claude Team and Enterprise subscribers, a "quick-create flow" where a user describes a desired Skill in plain language and Claude builds it, and a public directory of partner-built Skills from Atlassian, Canva, Notion, Figma, Cloudflare, Stripe, and Zapier (SiliconANGLE).

Those partner Skills give a concrete sense of what a mature Skill ecosystem looks like in practice: a Figma-built Skill teaches Claude a company's specific brand guidelines when generating design assets; Atlassian and equivalent project-tooling Skills let Claude create correctly-formatted tickets in Jira or Trello without a human re-explaining ticket conventions every session.

Industry reaction to the "open standard" framing was measured rather than uniformly enthusiastic. Constellation Research analyst Holger Mueller was quoted directly on the skepticism: "Single vendors are rarely able to set standards by themselves, and while MCP was endorsed by practically all AI vendors, it doesn't mean history will repeat itself" (SiliconANGLE). That's a fair caveat — MCP's rise to a near-universal standard, culminating in its transfer to the Linux Foundation, took roughly a year of multi-vendor adoption pressure, and Skills is still in its first year.

Why Skills Matter

Before Skills existed, the closest equivalent most Claude power users had was a personal library of saved prompts — a Notion doc, a Raycast snippet collection, a folder of .txt files with the exact phrasing that got good results last time. That pattern was fragile in three specific ways: you had to remember which prompt to paste and when, the prompt text alone couldn't execute code, and there was no structured way to hand a colleague your best prompt without a copy-paste conversation in Slack.

Skills formalize that pattern into something closer to real software distribution. A Skill folder is version-controllable — commit it to git like any other code, and you get history, diffs, and rollback for free. It's testable — because triggering is deterministic given a matching request, you can write eval prompts that check whether a Skill fires correctly. And it's discoverable at the model level, not just the documentation level: Claude itself reads the description and decides when a Skill applies, rather than a human needing to remember it exists.

The Claude subagents pattern extends this idea one step further — instead of one Claude instance loading a Skill inline, a main agent spawns a separate, isolated subagent instance to carry out a Skill-driven task in parallel, then reports back only the result. Skills give an agent what to know; subagents give a system how to divide the work. The two composed together are how Anthropic's own products, including Claude Code's specialized subagent roles, get built. Developers building agents in code can compare this approach with the OpenAI Agents SDK.

What This Means

Claude Skills solve a narrow but real problem: how do you give an already-capable model durable, reusable, executable expertise without permanently bloating its context window? Progressive disclosure — metadata always, instructions on trigger, resources on demand — is the specific engineering answer, and the token-cost numbers Anthropic publishes (about 100 tokens idle per Skill, under 5,000 when triggered) show why it scales to dozens of installed Skills without noticeable overhead. Skills are not a replacement for MCP, which handles the separate job of connecting to live external systems; the two are designed to run side by side. What's still unsettled, six months after the open-standard announcement, is whether Skills becomes a genuinely cross-vendor format the way MCP did, or stays a mostly Anthropic-ecosystem convention that other vendors watch from a distance.

Frequently Asked Questions

Q: Do I need to be a developer to use Claude Skills? A: No. Non-developers can install Anthropic's pre-built document Skills (pptx, xlsx, docx, pdf) with no setup and use custom ones shared by colleagues. Writing your own only requires basic markdown for SKILL.md; bundled scripts are optional.

Q: Can a Skill access the internet? A: It depends entirely on the surface. In Claude Code, a Skill's scripts have full network access — the same as any program on your machine. On the Claude API, Skills run in a sandboxed container with no network access and no runtime package installation. On claude.ai, network access for Skills is full, partial, or none depending on user and admin settings (Claude Platform Docs).

Q: Are Claude Skills open source? A: The SKILL.md format and progressive disclosure protocol became an Anthropic-led open standard on December 18, 2025. Anthropic also publishes several of its own Skills, including the Claude API reference skill, in a public GitHub skills repository. The four pre-built document Skills (pptx, xlsx, docx, pdf) are not separately open-sourced, but any developer can author and share their own Skills freely under the published format.

Q: How is a Skill different from a custom GPT? A: GPTs are hosted OpenAI assistants bundling instructions and actions, running only inside ChatGPT. Skills are local, filesystem-based folders that load progressively and work across four different Anthropic surfaces — Claude Code, claude.ai, the API, and the Agent SDK — though not automatically synced between them.

Q: Can I use Skills and MCP in the same Claude Code session? A: Yes, and Anthropic's own products routinely do. Skills give Claude reusable local procedures and document-generation ability; MCP connects that same session to live external systems like a database, a project tracker, or a chat platform. See What Is MCP? for how the connection side works.

Q: Where should I save shared team Skills in Claude Code? A: Commit them to your repository under .claude/skills/ for project-scoped sharing — every teammate who clones the repo gets the Skill automatically. For skills you want available in every project you personally work on, install them under ~/.claude/skills/ instead.

Q: What's the maximum size of a SKILL.md file? A: Anthropic caps the name field at 64 characters and the description field at 1,024 characters. There's no published hard limit on the body of SKILL.md itself, but Anthropic's own guidance keeps it under roughly 5,000 tokens in practice, pushing anything longer into a separate referenced file that loads only when needed.

Q: Is it safe to install a Skill I found online? A: Treat it the way you'd treat installing unfamiliar software with system access. Anthropic explicitly recommends using only Skills you authored yourself or obtained from Anthropic, and if you use a third-party Skill, auditing every bundled file for unexpected network calls, unusual file access, or behavior that doesn't match its stated description before running it.

Q: Are Skills covered by Anthropic's Zero Data Retention (ZDR) policy? A: No. Agent Skills is explicitly excluded from ZDR arrangements as of this writing — Skill definitions and execution data are retained under Anthropic's standard data retention policy. Enterprises with ZDR contractual requirements should confirm this with Anthropic before deploying Skills against sensitive data.

Q: Do pre-built Skills like pdf or xlsx work inside Claude Code? A: No. The four pre-built document Skills (pptx, xlsx, docx, pdf) are available on the Claude API, Claude Platform on AWS, Microsoft Foundry, and claude.ai, but not inside Claude Code. Claude Code instead ships with an open-source "Claude API skill" providing SDK reference material, and supports any custom Skill you build or install.

Sources

• Anthropic Engineering Blog: Equipping agents for the real world with Agent Skills (October 16, 2025)
• Claude Platform Docs: Agent Skills overview
• SiliconANGLE: Anthropic makes agent Skills an open standard (December 18, 2025)
• Aragon Research: Anthropic Supercharges Claude with 'Agent Skills'
• Anthropic open-source skills repository: github.com/anthropics/skills

Related: What Is MCP?, AI Subagents Explained, AI Agents Explained.