Claude Skills Explained: How They Work

Agent Skills are Anthropic's answer to a problem every serious Claude user eventually hits: general-purpose intelligence is not the same thing as reliable, repeatable expertise. A model that can reason about anything will still produce inconsistent output on a task like "build our quarterly board deck the way we actually format it" unless it is given the same detailed guidance every single time. Skills solve this by letting you (or Anthropic, or a third party) write that guidance once, package it as a directory with a SKILL.md file, and have Claude load it automatically whenever it is relevant.

The architecture is deliberately simple and filesystem-native. Claude runs in a virtual machine with bash access; a Skill is just a folder on that filesystem. At startup, only each installed Skill's name and description - roughly 100 tokens - sit in the system prompt. When a request matches a Skill's description, Claude reads the full SKILL.md body (Anthropic recommends keeping this under 5,000 tokens) using a bash command, and only then does it consume real context. Anything the Skill references beyond that - a forms guide, an API reference, a validation script - loads only if Claude actually needs it, and scripts run through bash so their code never enters the context window at all, only their output does.

• Launched: 16 October 2025, alongside pre-built document Skills for PowerPoint, Excel, Word and PDF.
• Open standard since: 18 December 2025, published at agentskills.io - by March 2026, 32 platforms including Microsoft, OpenAI, Google's Gemini CLI, Cursor and GitHub had adopted the SKILL.md format.
• Works with: claude.ai, Claude Code, the Claude Developer Platform (API), Claude on AWS and Claude in Microsoft Foundry.
• Not a replacement for MCP: Skills package know-how; MCP connects to external tools and data. Anthropic designed them to be used together.

In Anthropic's own words, Agent Skills are "organised folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks." The engineering team behind the feature likes the analogy of an onboarding guide you'd write for a new team member: a table of contents up front, specific chapters for specific situations, and a detailed appendix you only open when you actually need it. A Skill is that same structure, written for Claude instead of a person.

Concretely, a Skill is a directory containing at minimum one file - SKILL.md - and optionally as many supporting files as the task needs: a scripts/ folder of executable code, a references/ folder of documentation Claude reads only on demand, and an assets/ folder of templates or other resources. Anthropic's own example, from the engineering write-up, packages brand guidelines this way:

anthropic_brand/
├── SKILL.md
├── docs.md
├── slide-decks.md
└── apply_template.py

Anthropic ships four pre-built Skills out of the box - for PowerPoint (pptx), Excel (xlsx), Word (docx) and PDF (pdf) generation - available on claude.ai and via the API. Beyond those, anyone can write a custom Skill: a company can package its own tone-of-voice guide, database schema conventions or NDA-review checklist, and Claude will apply it automatically the moment a matching request comes in.

Every Skill must start with YAML frontmatter containing two required fields, name and description, followed by a Markdown body containing the actual 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:

```python
import pdfplumber

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

For advanced form filling, see [FORMS.md](FORMS.md).

Anthropic's platform documentation is specific about the constraints. name can be at most 64 characters, must use only lowercase letters, numbers and hyphens, and cannot contain the reserved words "anthropic" or "claude". description can be at most 1,024 characters and, critically, is the field Claude matches your request against to decide whether the Skill is relevant at all - so it has to state both what the Skill does and when to use it, not just a vague label. A Skill with a lazy description simply won't trigger reliably, no matter how good the instructions inside it are.

The single idea that makes Skills scale is progressive disclosure - loading information in stages, only as it's needed, rather than stuffing everything into the context window up front. Anthropic's documentation breaks it into three levels, and the token costs at each level are the whole point:

• Level 1 - Metadata (always loaded, ~100 tokens): just the name and description from every installed Skill's frontmatter, appended to the system prompt at startup.
• Level 2 - Instructions (loaded when triggered, under 5k tokens): the full SKILL.md body, read into context via bash only once Claude decides the Skill is relevant to the current request.
• Level 3+ - Resources and code (loaded as needed, effectively unlimited): reference files load into context only if Claude actually opens them; scripts run through bash and only their output - not their source code - ever reaches the context window.

The practical upshot is that you can install dozens of Skills - Anthropic's own example configuration lists bigquery, docx, nda-review, pdf, pptx and xlsx side by side - and pay almost nothing in context budget for the ones that never get used in a given conversation. A Skill can bundle "comprehensive API documentation, large datasets, or extensive examples," in Anthropic's phrasing, with zero context penalty for the parts that sit unread on disk.

The comparison to MCP is unavoidable, and Anthropic addresses it head-on in its own announcement: "Skills and MCP servers work together naturally" because they solve adjacent but distinct problems. MCP (Model Context Protocol) is a connectivity standard - it defines how an agent talks to an external tool, database or service it doesn't otherwise have access to. Skills are a knowledge-packaging standard - they teach an agent the correct procedure for using the tools it already has, MCP-connected or not.

Anthropic's own architecture diagram frames it as a four-layer stack: the agent's reasoning loop, the agent's runtime (filesystem and code execution), MCP servers for external connections, and a Skills library for procedural expertise. A Skill can - and often should - reference an MCP server inside its instructions: "use the bigquery MCP server to run this query, then follow these five steps to format the result the way finance expects." Neither replaces the other. This is also why Simon Willison's "bigger than MCP" framing, which Matt Wolfe's video popularised, is really a claim about scope rather than rivalry: MCP standardised how agents connect to the world, and Skills are attempting to standardise how agents get good at using that connection.

Pre-built document Skills

The four Skills Anthropic ships by default - PowerPoint, Excel, Word and PDF - are active automatically whenever you ask Claude to create or edit a document on claude.ai, with no setup required. On the API, you invoke them by passing their skill_id (pptx, xlsx, docx or pdf) inside the container parameter alongside the code execution tool, whose sandbox they run in.

Custom Skills

Anyone can write their own. On claude.ai, you upload a Skill as a zip file through Settings → Features, and it becomes available to that individual user only - custom Skills on claude.ai are not shared organisation-wide and cannot be centrally managed by admins. On the API, custom Skills upload through the dedicated Skills API (/v1/skills endpoints) and are shared workspace-wide, so every member of a workspace can use them once uploaded.

Claude Code Skills

In Claude Code, Skills are purely filesystem-based - no upload step at all. Drop a directory with a SKILL.md file into ~/.claude/skills/ for a personal Skill available across all your projects, or into a project's .claude/skills/ folder for one scoped to that repository, and Claude discovers and uses it automatically. Claude Code doesn't get the pre-built document Skills, but it does come bundled with Anthropic's open-source Claude API Skill, which gives Claude up-to-date SDK and API reference material for eight programming languages.

Open-source Skills repository

Anthropic publishes and maintains 17 open-source Agent Skills on GitHub, spanning creative design, document creation, technical development and enterprise communication - a useful reference set for anyone learning to write their own, and the safest source of third-party Skills since they come directly from Anthropic.

Skills reach further than most Claude features, but the details differ meaningfully by surface, and - importantly - custom Skills do not sync across them. A Skill uploaded to claude.ai has to be separately uploaded to the API if you want to use it there too; API Skills aren't visible on claude.ai; and Claude Code Skills are entirely separate from both, living on the filesystem.

• claude.ai: pre-built document Skills work for everyone with no setup. Custom Skills require code execution to be enabled and are available on Pro, Max, Team and Enterprise plans - there is no custom-Skills support on the free tier.
• Claude Code: custom Skills only, free, filesystem-based, personal or project-scoped, and shareable through Claude Code Plugins.
• Claude API: both pre-built and custom Skills, gated behind the code execution tool, running in a sandboxed container with no network access and no runtime package installation - only pre-configured dependencies are available.
• Claude on AWS (Bedrock) and Microsoft Foundry: inherit the same Skills behaviour as the API; on Microsoft Foundry, Agent Skills specifically require a "Hosted on Anthropic" deployment.

One more operational detail worth knowing: Agent Skills is not covered by Anthropic's zero data retention (ZDR) arrangements. Skill definitions and execution data are retained under Anthropic's standard data retention policy, which matters if your organisation has ZDR contractual requirements elsewhere in the Claude stack.

The part of this story that has aged the most interestingly since October 2025 is what happened after launch. On 18 December 2025, Anthropic published the Agent Skills specification and SDK as an open standard at agentskills.io, effectively inviting every other AI vendor to build against the same SKILL.md format rather than inventing a competing one. It's the same playbook Anthropic ran with MCP a year earlier - open the plumbing rather than fight for a proprietary standard - and it worked at similar speed.

Within 48 hours, Microsoft had integrated Skills support into VS Code and OpenAI had added support to both ChatGPT and the Codex CLI. By March 2026, agentskills.io listed 32 adopters, including Google's Gemini CLI, JetBrains's Junie, Sourcegraph's Amp, Block's Goose, Snowflake, Databricks, ByteDance, Mistral AI and Spring AI, alongside earlier adopters Atlassian, Figma, Cursor and GitHub. Practically, that means a well-written Skill is increasingly portable: the same directory of instructions and scripts you build for Claude Code has a real chance of working, unmodified or nearly so, in a competitor's agent.

Anthropic's own documentation is unusually blunt about the risk profile here: "use Skills only from trusted sources: those you created yourself or obtained from Anthropic." Because a Skill can direct Claude to run bash commands, execute scripts and call tools, a malicious or compromised Skill can in principle do anything a malicious set of instructions could - exfiltrate data, make unauthorised network calls, or misuse tools in ways that don't match what the Skill claims to do. Skills that fetch content from external URLs are called out specifically as higher risk, since fetched content itself can carry hidden instructions.

Anthropic's stated mitigation is to treat installing a Skill exactly like installing software: audit every bundled file - SKILL.md, scripts, images, everything - before use, and be especially cautious integrating third-party Skills into systems with access to sensitive data. For organisations, Claude Enterprise customers can turn on Skill content scanning for custom Skills uploaded through claude.ai and Claude Cowork, though this scanning does not currently cover Skills uploaded via the Skills API or Claude Console.

Anthropic has since built several of its industry-specific product lines on top of the Skills primitive rather than as separate features. Claude for Healthcare and Life Sciences ships Skills for FHIR development and prior authorisation review; Claude for Financial Services ships pre-built Skills for discounted cash flow modelling and initiating coverage reports; and Claude for Small Business bundles 15 ready-to-run agentic workflows across finance, operations, sales, marketing, HR and customer service on top of 15 purpose-built Skills. In each case, the pitch is the same: instead of a generic model that needs re-briefing every session, teams get a Claude that already knows their domain's conventions.

On the consumer and developer side, the pattern that has emerged organically - visible in the wave of "here are my favourite Skills" content since launch - is teams packaging their house style: brand voice guides, code review checklists, meeting-note templates, SEO content workflows. The common thread across all of it is the same one Anthropic designed for: write the tedious, repeatable part once, and stop re-explaining it.

• No cross-surface sync: a custom Skill uploaded to claude.ai must be separately uploaded to the API, and Claude Code Skills are entirely separate from both.
• claude.ai sharing is individual, not org-wide: every team member has to upload their own copy; admins cannot centrally deploy or manage custom Skills on claude.ai.
• API sandbox has no network access: Skills running through the Claude API cannot make external calls or install packages at runtime - only pre-configured dependencies are available, which rules out some workflows entirely.
• Discovery depends entirely on the description field: a vague or poorly scoped description means Claude simply won't trigger the Skill reliably, however good the instructions inside it are - as several creators covering the topic this month have found the hard way.
• Trust is on you: there is no centralised vetting or marketplace with reviews; Anthropic explicitly puts the burden of auditing third-party Skills on the user.
• Not ZDR-covered: Skill definitions and execution data follow Anthropic's standard retention policy, not zero data retention.

Within the Claude product line, Skills sit alongside rather than compete with computer use, browser use and the Files API - all four moved to general availability together on the Claude Developer Platform, and are typically combined in real agentic deployments: a Skill supplies the know-how, computer use or browser use supplies the hands, and the Files API supplies persistent storage. Claude Code's /design command is itself a concrete example of a first-party Skill built on this exact architecture.

Against rival ecosystems, the open-standard move means the comparison is less "Claude Skills versus X's equivalent" and increasingly "who implements the same SKILL.md format best." OpenAI's Codex CLI and ChatGPT, Microsoft's VS Code, Google's Gemini CLI and Cursor all now read the same file format Anthropic defined, which is a genuinely unusual outcome in a field where every vendor typically ships incompatible plugin systems. The practical differentiator, at least for now, is less the format itself and more each platform's execution environment - sandboxing, network access, and how aggressively the agent decides to trigger a Skill in the first place.

Build a Skill if you find yourself re-explaining the same task setup to Claude more than a couple of times - a report format, a code review checklist, a company style guide, a data pipeline convention. The time investment in writing a clear SKILL.md pays back the moment you'd otherwise have re-typed the same instructions a third time, and it compounds across a team if you share it.

Start with Anthropic's pre-built Skills or the open-source repository if you just want document generation (PowerPoint, Excel, Word, PDF) or want to see well-written examples before authoring your own - both are the lowest-risk entry point, since they come directly from Anthropic. Be cautious installing third-party Skills from unfamiliar sources, and if you must, read every file before letting Claude use it, exactly as you would before running someone else's shell script.

Claude Skills are a deceptively simple idea - a folder, a Markdown file, some YAML frontmatter - built on a genuinely clever engineering insight: an agent with filesystem access doesn't need everything in its context window at once, it just needs to know where to look and when. Progressive disclosure is what makes that idea scale to dozens of installed Skills without drowning the model in unused instructions, and it's the same property that let Anthropic open the format as a standard without worrying that every implementer would need Claude-specific infrastructure to use it.

Almost a year after launch, the renewed wave of explainer and "how I actually use this" content is a healthy sign rather than a stale one: it means Skills moved past the announcement and into the part of a feature's life where people are actually building libraries of them, auditing what they installed, and arguing about best practice. Whether you're writing your first Skill or pruning your twenty-fifth, the fundamentals are the same ones Anthropic documented on day one: a sharp description, instructions Claude can act on without hand-holding, and code for the parts that need to be reliable rather than merely plausible.