Claude Skills
Last reviewed
Sources
32 citations
Review status
Source-backed
Revision
v6 · 8,888 words
Improve this article
Add missing citations, update stale details, or suggest a clearer explanation.
Suggest edit
CtrlK
Last reviewed
Sources
32 citations
Review status
Source-backed
Revision
v6 · 8,888 words
Add missing citations, update stale details, or suggest a clearer explanation.
Claude Skills (also marketed as Agent Skills) are a feature developed by Anthropic that lets users package repeatable workflows, instructions, reference materials, and optional executable scripts into discoverable folders that Claude can load on demand. Each Skill is a directory on a filesystem that contains a SKILL.md file with YAML frontmatter, plus any supporting files the workflow needs. Anthropic announced Skills publicly on October 16, 2025 and released them at the same time across Claude.ai, Claude Code, the Claude API, and the Claude Agent SDK.[1][2]
The central design idea is progressive disclosure, which Anthropic calls "the core design principle that makes Agent Skills flexible and scalable."[3] Claude is told only the name and one-line description of every installed Skill at the start of a session, then reads the full SKILL.md only when the user's request matches, and only opens additional bundled files (templates, references, scripts) when a step actually needs them. This keeps the context window small while letting a single account install many specialized capabilities.[3][4] Independent developer and AI commentator Simon Willison wrote on the day of launch that Skills "might be a bigger deal than MCP," pointing to the simplicity of the format compared with the Model Context Protocol.[5] Two months later, on December 18, 2025, Anthropic released the format as an independent open standard at agentskills.io, opened organization-wide admin provisioning to Team and Enterprise plans, and launched a curated partner-skills directory anchored by Atlassian, Canva, Cloudflare, Figma, Notion, Sentry, Vercel, and Zapier.[20][21][23] On March 31, 2026 that directory became a unified surface at claude.ai/customize covering Skills, connectors, and plugins.[24] Within weeks of the open-standard release more than thirty agentic coding tools adopted the format, including GitHub Copilot, Cursor, Gemini CLI, and OpenAI Codex.[20][21]
| Attribute | Value |
|---|---|
| Developed by | Anthropic |
| Initial release | October 16, 2025 |
| Open standard release | December 18, 2025 |
| Standard home | agentskills.io |
| Unified directory | claude.ai/customize (skills, connectors, and plugins) |
| File format | Folder containing SKILL.md with YAML frontmatter plus optional resources |
| Required fields | name, description |
| Available on | Claude.ai Pro/Max/Team/Enterprise, Claude Code, Claude API, Claude Agent SDK, Claude Cowork |
| Reference repository | github.com/anthropics/skills |
| License (most skills) | Apache 2.0 |
| License (document skills) | Source-available, not open source |
| Notable adopters | GitHub Copilot, VS Code, Cursor, Gemini CLI, OpenAI Codex, Goose, OpenCode, Amp, Letta, Junie, Kiro, Roo Code |
A Skill is a folder. The minimum contents are a single SKILL.md file whose first lines are YAML frontmatter:
---
name: pdf-processing
description: Extract text and tables from PDFs, fill forms, merge documents. Use when the user mentions PDFs, forms, or document extraction.
---
# PDF processing
## Quick start
Use pdfplumber to extract text from PDFs.
## Form filling
See FORMS.md for the form-filling reference.
The name field is the unique identifier (lowercase, hyphenated, maximum 64 characters, and not allowed to contain the words "anthropic" or "claude"). The description is a short string of at most 1,024 characters that tells Claude both what the Skill does and when to use it. Anything below the closing --- is Markdown that Claude reads as instructions when the Skill is triggered.[2][6]
A more complex Skill folder may look like this:
pdf-skill/
├── SKILL.md # main instructions
├── FORMS.md # extra reference loaded only when needed
├── REFERENCE.md # detailed API reference
├── scripts/
│ └── fill_form.py # executable Python script
└── assets/
└── template.pdf # binary template
Claude reaches into these files using ordinary bash commands inside the code-execution sandbox: it runs cat SKILL.md to load the main file, then cat FORMS.md if a step references it, then executes python scripts/fill_form.py for deterministic operations. Script source code never enters the context window; only the printed output of the script does, which makes Skills far more token-efficient than asking Claude to write the same logic from scratch on every call.[3][4]
Anthropic likens the architecture to an onboarding binder for a new employee, writing that "building a skill for an agent is like putting together an onboarding guide for a new hire."[3] The table of contents (Skill metadata) is always visible, individual chapters (the SKILL.md body) get pulled off the shelf only when a question lands in their territory, and the appendices (scripts, templates, reference files) only get opened when a specific step demands them. Skills are not always-on personality settings; they are situation-triggered reference material that costs almost nothing to keep around.
Progressive disclosure is the core engineering pattern. The official documentation describes three loading levels:[3][6]
| Level | Content | When loaded | Approximate token cost |
|---|---|---|---|
| 1. Metadata | name and description from YAML frontmatter of every installed Skill | At session startup, included in the system prompt | About 100 tokens per Skill |
| 2. Instructions | Full body of SKILL.md for one Skill | Only when Claude judges the Skill is relevant to the current request | Under about 5,000 tokens per Skill |
| 3. Resources | Additional Markdown files, scripts, templates, datasets | Only when a step references them | Effectively unlimited; bundled files cost zero tokens until accessed |
The consequence is that a user can install dozens of Skills without bloating the context window. Claude knows each Skill exists and what it is for, but it does not pay the token cost of any Skill it does not actually use. When the model finally does call a Skill, it pulls only the specific files that step needs. Independent benchmarking by integration vendors in early 2026 reported that combining Skills with a tightly-scoped MCP server can reduce total token usage on equivalent workflows by up to roughly 65 percent versus attaching the same material to a system prompt.[26]
A representative load sequence: at startup the system prompt includes the line pdf-processing - Extract text and tables from PDF files. The user types "Extract the text from this PDF and summarize it." Claude matches the request to the description, issues bash: cat ~/.claude/skills/pdf-processing/SKILL.md, and the body enters context. Claude reads the body, notices that form-filling is not needed, skips FORMS.md, then follows the instructions and calls any bundled scripts via bash.[6]
Claude does not re-read the SKILL.md file on each turn after activation. The rendered content sticks in the conversation as a single message, and Claude Code carries the most recent invocation forward across auto-compaction within a 25,000-token shared budget for re-attached Skills.[15]
Skills live as ordinary directories on a virtual machine, accessible to Claude over the same bash interface it uses for any other code-execution task. Because Skills are just folders, version control is straightforward: a Skill can be a Git repository, distributed as a ZIP file, or committed to a project's .claude/skills/ directory. Any tool that can read Markdown and run shell commands can in principle execute a Skill.[2][7] This decouples Skills from the model: the same folder works whether Claude is a Pro user on claude.ai, an API caller running batch jobs, or a developer in Claude Code iterating in a terminal.
The frontmatter is the only part of a Skill that Claude is forced to read. Anthropic enforces several constraints on its fields, and Claude Code adds a number of optional fields specific to its runtime:[6][15]
| Field | Required | Surface | Rules |
|---|---|---|---|
name | Yes (API), Optional (Claude Code) | All | Lowercase letters, digits, and hyphens only. Maximum 64 characters. May not contain XML tags or the reserved words "anthropic" and "claude". Defaults to the directory name in Claude Code if omitted. |
description | Yes (recommended) | All | Non-empty, maximum 1,024 characters, no XML tags. Describes what the Skill does and when Claude should use it. |
version | No | API | Semantic version string (for example 1.0.0). Used by the API for pinning. |
when_to_use | No | Claude Code | Additional trigger phrases or example requests appended to the description in the Skill listing. |
argument-hint | No | Claude Code | Hint shown during autocomplete (for example [issue-number]). |
arguments | No | Claude Code | Named positional arguments for $name substitution in the body. |
allowed-tools | No | Claude Code, open standard (experimental) | Tools Claude can use without prompting permission while the Skill is active. The open standard exposes the same field as an experimental capability gate.[27] |
disable-model-invocation | No | Claude Code | If true, only the user can invoke with /<name>; Claude does not auto-trigger. |
user-invocable | No | Claude Code | If false, hidden from the slash command menu. |
model | No | Claude Code | Model override for the rest of the current turn. |
effort | No | Claude Code | Effort level override (low, medium, high, xhigh, max). |
context | No | Claude Code | Set to fork to run in a forked subagent. |
agent | No | Claude Code | Subagent type to use when context: fork is set. |
paths | No | Claude Code | Glob patterns that gate auto-activation by file path. |
hooks | No | Claude Code | Hooks scoped to this Skill's lifecycle. |
shell | No | Claude Code | bash (default) or powershell for inline command injection. |
license | No | Open standard | Maximum 500 characters. Records the Skill's redistribution terms in a portable way across implementations.[27] |
compatibility | No | Open standard | Declares the host environments the Skill is known to run on (for example claude-code, codex-cli, cursor).[27] |
metadata | No | Open standard | Arbitrary string-to-string map for vendor-specific extensions. Authors are asked to namespace keys to avoid collisions.[27] |
Writing a precise description is the single most important authoring task. Because Claude only sees the description when deciding whether to load a Skill, a vague line like "helps with documents" will produce inconsistent activation, while a specific line like "Extract text and tables from PDF files; use when the user mentions PDFs, forms, or document extraction" will trigger reliably.[3][6] If a description is unhelpful, Anthropic recommends putting the most distinctive use case first because the combined description and when_to_use text is truncated at 1,536 characters in the Claude Code listing to limit context usage.[15]
Claude Code recognizes four discovery scopes for Skills, with a defined precedence when the same name appears in more than one location:[15]
| Scope | Path | Applies to | Precedence |
|---|---|---|---|
| Enterprise | Managed settings file | All users in the organization | Highest |
| Personal | ~/.claude/skills/<name>/SKILL.md | All projects on a user's machine | Second |
| Project | .claude/skills/<name>/SKILL.md (in repo root) | One repository, all collaborators | Third |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled | Namespaced as plugin-name:skill-name, no conflicts |
The API uses a different model: custom Skills uploaded via the /v1/skills endpoint are workspace-wide and visible to every member of the workspace, while Claude.ai uploads are private to the uploading user until an admin explicitly provisions a partner Skill to the organization.[6][23] Claude Code also auto-discovers Skills from nested .claude/skills/ directories within a project, which supports monorepos where individual packages carry their own Skills, and from any directory passed via the --add-dir flag at startup.[15]
When a name collision happens (for example a project Skill called commit and a personal Skill called commit), enterprise overrides personal and personal overrides project. Plugin Skills sit in a namespace of their own and are addressed as plugin-name:skill-name, so they cannot collide with anything else.
Claude Code watches Skill directories for filesystem changes during a session. Adding, editing, or removing a Skill under any watched path takes effect within the current session without a restart. The exception is creating a top-level Skills directory that did not exist when the session started: that directory is not watched until the next session begins.[15] The hot-reload behavior shipped in Claude Code 2.1, alongside session teleportation and language-specific output.
The lifecycle of a Skill within a single Claude conversation looks like this:[3][4][6]
name and description of every installed Skill. The full SKILL.md files are not loaded.bash call such as cat ~/.claude/skills/pdf-processing/SKILL.md. The body enters the context window.bash call only when that branch of the workflow is needed.bash. Only the script's stdout/stderr enters context, not the source code.brand-guidelines Skill on top of a pptx Skill to produce a branded presentation, with no manual orchestration required.[1][2]Because every step is just bash against ordinary files, there is no proprietary protocol layer between the model and the Skill. Claude treats Skills the way a developer would treat a folder of helper scripts. That is what makes Skills feel different from a Custom GPT or a Gemini Gem: no hosting layer to depend on, no upload step to gate, just files that the model can read on demand.
Claude Code Skills support a unique preprocessing feature called dynamic context injection. The syntax !`<command>` inside SKILL.md is replaced by the command's output before Claude sees the file. A Skill that summarizes uncommitted changes might use:
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes in two or three bullet points.
When Claude loads this Skill, the live diff has already been substituted in. The model receives the actual changed lines, not the literal command string. Multi-line variants use a fenced code block opened with three backticks plus an exclamation mark. The pattern is preprocessing, not tool use, so it consumes the cost of the substitution but never enters the agent loop.[15]
Anthropic and early adopters have published a range of representative use cases:[1][2][3]
| Use case | Example | What the Skill encodes |
|---|---|---|
| Brand voice | A brand-guidelines Skill applied to every generated document | Approved colors, typography, tone-of-voice rules, banned phrasing |
| Internal documentation | A company-onboarding Skill that answers new-hire questions | Org chart, process diagrams, policy summaries, internal links |
| Output formats | An xlsx Skill that produces consistent Excel reports | Cell formatting templates, chart conventions, formula libraries |
| Reporting workflows | A quarterly-report Skill for finance teams | Step-by-step procedure for combining spreadsheets, anomaly checks, narrative templates |
| Design assets | A slack-gif-creator Skill that produces optimized animated GIFs | Size limits, palette constraints, FFmpeg command snippets |
| Engineering | A webapp-testing Skill that runs Playwright against a target site | Test scaffolding, common selectors, screenshot capture commands |
| Developer tooling | An mcp-builder Skill that scaffolds new MCP servers | Project layout, registration boilerplate, TypeScript or Python templates |
| Personal automation | A recipe-formatter Skill for a home cook | Preferred unit conversions, allergen tags, output template |
| Code review | A commit Skill that stages and writes a conventional message | Linting checks, message format, scope rules |
| Compliance | A legal-review Skill applied to contract drafting | Clause libraries, banned language, jurisdiction notes |
The broader pattern is that any workflow a knowledge worker repeats becomes a candidate for a Skill: the natural-language steps become the SKILL.md body, the reference data becomes a bundled file, and any deterministic operation becomes a script. The model never had to learn the workflow during training. It just reads the manual you wrote, the same way a contractor on day one would.
Anthropic ships a set of pre-built Skills directly from the Claude API and Claude.ai. These are sometimes called document Skills because they target the four common Office document formats:[6][8]
skill_id | Format | Capabilities |
|---|---|---|
pptx | PowerPoint | Create presentations, edit slides, apply layouts and templates, analyze existing decks |
xlsx | Excel | Create spreadsheets, write formulas, generate charts, perform data analysis |
docx | Word | Create documents, edit content, preserve formatting, work with tracked changes and comments |
pdf | Generate formatted PDFs, extract text and tables, fill forms, merge and split files |
These Skills are available to all paid Claude.ai users and to API callers with the relevant beta headers enabled. They activate automatically when a user asks Claude to make or modify the corresponding file type.[6] Crucially, document Skills are licensed source-available rather than open source: they ship in the public anthropics/skills repository so that users can read them, but Anthropic reserves the right to limit redistribution and derivative works, unlike the rest of the repository which is Apache 2.0.[7]
Anthropic also bundles a claude-api Skill that gives Claude up-to-date reference material for the Claude API and SDKs across eight programming languages, and ships a skill-creator Skill that walks users through authoring new Skills interactively.[6][7] Claude Code ships with several additional bundled Skills that are available in every session, including /simplify, /batch, /debug, /loop, /init, /review, and /security-review. Unlike most built-in commands, which execute fixed logic, these are prompt-based: they hand Claude detailed instructions and let it orchestrate the work using its tools.[15]
Anthropic publishes the open-source anthropics/skills GitHub repository as a public reference catalog and as an installable Claude Code marketplace.[7] The repository is registered as a Claude Code plugin marketplace using the command:
/plugin marketplace add anthropics/skills
From there, users can install bundled Skill packs:
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills
As of mid-2026 the repository ships seventeen Skills, organized loosely into four categories:[7]
| Skill | Category | Description |
|---|---|---|
algorithmic-art | Creative | Generate p5.js art with seeded randomness and reproducible parameters |
canvas-design | Creative | Produce PNG and PDF designs from natural-language descriptions |
slack-gif-creator | Creative | Build optimized animated GIFs sized for Slack reactions |
theme-factory | Creative | Generate cohesive themes for Claude Artifacts and other UI |
frontend-design | Creative | Produce React/Tailwind component sketches and mockups |
web-artifacts-builder | Development | Scaffold complex Claude.ai HTML Artifacts using React, Tailwind, and shadcn/ui |
mcp-builder | Development | Scaffold new Model Context Protocol servers |
webapp-testing | Development | Run Playwright test scaffolds against a target site |
claude-api | Development | Provide up-to-date Claude API and SDK reference material across eight programming languages |
brand-guidelines | Enterprise | Apply organizational color, typography, and tone-of-voice rules |
internal-comms | Enterprise | Draft consistent internal newsletters and announcements |
doc-coauthoring | Enterprise | Collaborative document drafting with revision tracking |
pdf | Document | PDF extraction, generation, and form filling |
docx | Document | Word document creation and editing with formatting fidelity |
pptx | Document | PowerPoint presentation creation and editing |
xlsx | Document | Excel spreadsheet creation, formulas, charting |
skill-creator | Meta | Interactive Skill authoring assistant |
The repository also publishes the template/ directory (a minimal scaffolding starter for new Skills) and the spec/ directory containing the Agent Skills standard specification.
A community ecosystem grew quickly. Catalogs such as awesome-claude-skills, claude-skills-marketplace, tonsofskills.com, and SkillsMP collect community Skills, and several open marketplaces aggregated thousands within months.[9][10][11] Vercel's skills.sh directory, launched in early 2026, lists tens of thousands. Doppio.ai's Claude Code Skills Directory and the VoltAgent awesome-agent-skills repository (a cross-vendor list covering Claude Code, Codex, Gemini CLI, and Cursor) round out the most-cited curated indexes, with roughly 4,200 named Skills aggregated by spring 2026.[28][29] Because Skills are plain folders, they can be installed by cloning a repository, copying a ZIP into a settings menu, or committing a .claude/skills/ directory to a project. There is no central approval process and no revenue-sharing storefront comparable to the GPT Store, which means the community ecosystem is messier but also lower-friction.
The largest single community effort is Superpowers, a meta-framework by Jesse Vincent ("obra") that bundles more than twenty composable Skills with a bootstrap loader and slash commands like /brainstorm, /write-plan, and /execute-plan.[30] Released in October 2025 and added to Anthropic's official plugin marketplace by January 2026, Superpowers chains Skills across the software lifecycle (brainstorming, git-worktree setup, plan writing, subagent execution, TDD, and code review). It had grown to roughly 194,000 stars and 17,300 forks by May 2026, the highest-starred Claude Skill project on GitHub, and runs unchanged in Codex CLI, Cursor, Gemini CLI, and the GitHub Copilot CLI.[30]
Alongside the December 18, 2025 open-standard release, Anthropic launched a curated partner-skills directory and opened admin-controlled organization-wide provisioning on Team and Enterprise plans.[23] The directory let administrators push vetted Skills to every user with a single toggle. The launch lineup included Atlassian (Jira and Confluence), Canva, Cloudflare (workers and DNS), Figma, Notion, Sentry, Vercel, and Zapier (paired with Zapier's MCP catalog of 8,000-plus apps).[23]
On March 31, 2026 Anthropic merged the partner-skills directory, the connector list, and the plugin marketplace into a single browse surface at claude.ai/customize. The directory offers a typed filter (Skills, connectors, plugins), a search bar, and an "install" button. Personal accounts install community Skills; Team and Enterprise admins can additionally pin Skills to all workspace members from claude.ai/admin-settings/skills.[24]
| Surface | What it groups | Who can install | Launched |
|---|---|---|---|
| Unified directory (claude.ai/customize) | Skills, connectors, plugins | Any logged-in user | March 31, 2026 |
| Partner-skills section | Vetted partner-built Skills | Workspace admins (Team, Enterprise) | December 18, 2025 |
| Plugin marketplace | Multi-component plugins | Workspace admins; project-level installs in Claude Code | February 2026 |
| Personal upload | Custom ZIP-packaged Skills | Any paid user | October 16, 2025 |
On December 18, 2025, Anthropic released the Agent Skills format as an independent open standard hosted at agentskills.io.[20][21] The specification is deliberately small. According to Simon Willison's analysis on December 19, 2025, the entire spec is short enough to read in minutes and includes a lightly defined metadata extension field plus an experimental allowed-skills field for constraining agent capabilities.[21] The published specification documents name, description, license, compatibility, allowed-tools, and metadata as the recognised frontmatter keys, leaves every other key as a vendor extension, and pins the maximum description length at 1,024 characters.[27]
Within 48 hours Microsoft integrated Skills into VS Code and OpenAI added support to ChatGPT and Codex CLI. By mid-2026 more than thirty independent agent products read the same SKILL.md files, including:[20][22]
| Vendor | Product |
|---|---|
| Anthropic | Claude.ai, Claude Code, Claude Cowork |
| OpenAI | Codex CLI, ChatGPT |
| Microsoft | VS Code, GitHub Copilot |
| Gemini CLI | |
| Cursor | Cursor IDE |
| Block | Goose |
| JetBrains | Junie |
| AWS | Kiro |
| Letta | Letta |
| Sourcegraph | Amp |
| SST | OpenCode |
| All Hands AI | OpenHands |
| Snowflake | Cortex Code |
| Databricks | Genie Code |
| Mistral | Mistral Vibe |
| Roo Code | Roo Code |
| Laravel | Boost |
| ByteDance | TRAE |
| Factory | Factory |
The pace of adoption surprised even Anthropic. Within weeks Microsoft published an Azure Skills Plugin built on the standard so that the same Skill folder could light up experiences in Claude Code, GitHub Copilot, Copilot CLI, and any other supporting tool.[22] Coverage in The New Stack, VentureBeat, and SiliconANGLE described the move as Anthropic's most successful infrastructure standardization since MCP.[14][20]
The Skills specification is governed separately from the Linux Foundation's Agentic AI Foundation (AAIF), formed December 9, 2025 with Anthropic, OpenAI, and Block as co-founders.[32] AAIF received MCP, Block's Goose, and OpenAI's AGENTS.md as anchor projects, but Anthropic kept Skills at agentskills.io rather than donating it. Analysts framed the split as deliberate: MCP and AGENTS.md cover wire protocols where vendor neutrality is essential, while the Skills format is small enough that Anthropic can keep iterating on it directly.[32]
Every major model provider now ships some form of customization layer. Skills, Custom GPTs, and Google's Gemini Gems all share the goal of packaging reusable AI behavior, but the implementations differ sharply:[12][13]
| Feature | Claude Skills | OpenAI Custom GPTs | Gemini Gems | Cursor Rules | GitHub Copilot Custom Instructions |
|---|---|---|---|---|---|
| Provider | Anthropic | OpenAI | Cursor | GitHub | |
| Storage | Folder of Markdown plus optional scripts | Hosted record on OpenAI servers | Hosted record on Google servers | .cursor/rules/*.mdc files in the repo | .github/copilot-instructions.md in the repo |
| Instruction limit | None (multi-page Markdown) | About 8,000 characters | About 4,000 characters | None | None |
| Executable code | Yes (any language available in the sandbox) | Limited to Code Interpreter and Actions (HTTP) | Limited to built-in Google tools | None | None |
| External APIs | Via the user's environment or scripts | Via Actions (OpenAPI specs) | Limited to Google integrations | None | None |
| Discovery model | Description-based progressive disclosure | All instructions loaded into every conversation | All instructions loaded into every conversation | Path-glob match | Always loaded for repo |
| Sharing | Git repo, ZIP, plugin marketplace, public catalogs | GPT Store with revenue sharing | No public sharing ecosystem | Repo only | Repo only |
| Cross-vendor portability | Yes, supported by Codex, Cursor, Gemini CLI, GitHub Copilot, and more after the December 2025 open-standard release | No (OpenAI-only) | No | No (Cursor-specific) | No (GitHub-specific) |
| Activation | Automatic, based on description match | Manual selection, then auto within the chat | Manual selection per chat | Auto, based on file path | Always-on for repo |
| Free tier | Yes (Claude Code is free; document Skills available on paid claude.ai plans) | Yes (since 2024) | Yes | Yes (Cursor free tier) | Yes (Copilot free tier) |
Another useful contrast is between Skills and the Model Context Protocol, which is also an Anthropic-led effort. MCP is a protocol for exposing live tools and data sources to a model through a server. Skills are a static format for procedural knowledge. The two are complementary: a Skill might explain how a workflow should be carried out, while an MCP server provides the live data the workflow operates on.[5][14]
| Aspect | Claude Skills | Model Context Protocol |
|---|---|---|
| Primary purpose | Teach Claude how to perform a task | Connect Claude to external systems |
| Format | Folder of Markdown and scripts | Protocol specification with stdio or HTTP servers |
| Token cost when idle | Roughly 100 tokens per Skill (description only) | Often thousands of tokens for tool listings |
| Implementation effort | Write a Markdown file | Build and host a server in a supported language |
| State | Stateless across sessions | Can hold connection state and credentials |
| Vendor neutrality | Open standard since December 2025 | Vendor-neutral by design (transferred to Linux Foundation in 2026) |
| Distribution | Folder copy or plugin marketplace | Server URL plus auth credentials |
| Discoverability | Description-based progressive disclosure | All tools loaded at session start |
Anthropic frames the relationship between the various customization features as a stack: a complete Claude agent configuration combines a system prompt, a set of Skills, persistent memory (where supported), and tools (whether built-in, MCP-connected, or invoked through Skill scripts). Skills sit between the always-on system prompt and the per-call tools, providing on-demand domain knowledge.[3][14] Willison put the practical case bluntly: GitHub's official MCP consumes "tens of thousands of tokens," while a Skill that wraps the same workflow as a CLI invocation costs only the description until it triggers.[5]
By early 2026 the dominant production pattern was to combine Skills with MCP servers rather than choose between them. The split is sometimes called "Skills are the playbook, MCP is the nervous system": Skills tell Claude what to do, MCP tells it where the data lives.[26] One Skill can orchestrate multiple MCP servers. A competitive-analysis Skill might call the Google Drive MCP server for internal notes, a GitHub MCP server for competitor repositories, and a web-search MCP server for market data, then assemble the result using prompts in SKILL.md. Anthropic's January 2026 guidance recommended pairing the two so organizations could keep credentials on the MCP side while versioning procedural knowledge as ordinary code.[26]
| Question | Use a Skill | Use an MCP server |
|---|---|---|
| Are you teaching the model how to think about a problem? | Yes | No |
| Are you connecting the model to live data or systems? | No | Yes |
| Does the workflow change rarely and live in Git? | Yes | Either |
| Does the resource require credentials, OAuth, or session state? | No | Yes |
| Is the cost of always-on tool listings unacceptable? | Yes (Skills idle at about 100 tokens) | No (full tool list always loaded) |
| Should the result be portable to Codex, Cursor, and Copilot? | Yes (open standard) | Yes (open protocol) |
Skills behave slightly differently depending on the surface they run on. The overall behavior is the same (a folder, progressive disclosure, on-demand load), but each surface has its own constraints:[6][15]
| Surface | Pre-built Skills | Custom Skills | Network access | Sharing | Distribution |
|---|---|---|---|---|---|
| Claude.ai | Yes (auto, no setup) | Yes (Settings > Features, ZIP upload) | Variable per user/admin settings | Per user, plus admin-provisioned partner Skills since Dec 2025 | Manual upload or unified directory |
| Claude API | Yes (skill_id reference) | Yes (/v1/skills endpoint) | None (sandbox is offline) | Workspace-wide | API endpoint |
| Claude Code | Selected bundled Skills | Yes (filesystem) | Same as user's machine | Personal, project, or plugin | Filesystem or plugin marketplace |
| Claude Agent SDK | Inherited from API or Claude Code session | Inherited | Inherited | Inherited | Wraps Claude Code CLI |
| Claude Cowork | Inherited from Claude.ai workspace plus the eleven official Cowork plugins | Yes (workspace and admin-provisioned) | Same as host machine | Plugin- or admin-managed | Unified directory or plugin install |
Claude Code discovers Skills in three locations beyond the enterprise scope:[15]
~/.claude/skills/ are available to all of a user's Claude Code projects..claude/skills/ inside a Git repository are available to anyone who clones the project. This makes Skills checkable into version control alongside source code.In Claude Code, Skills run with the same network and filesystem access as any other program on the user's machine, so they can call external APIs, modify files in the working directory, and execute long-running scripts. This is more permissive than Claude.ai or the API, where Skills run inside a sandboxed virtual machine.[6]
Claude Code merged the older .claude/commands/ directory into the Skills format in late 2025: a file at .claude/commands/deploy.md and a Skill at .claude/skills/deploy/SKILL.md both create the slash command /deploy and behave the same way.[15] Skills add features that plain commands lack: a directory for supporting files, frontmatter to control whether the user or the model invokes the command, and the ability to bundle scripts that Claude can execute. The disable-model-invocation: true flag lets a team build a /deploy Skill that the user must trigger explicitly, so Claude does not decide on its own that the code looks ready to ship.
Several Skill conventions have emerged among Claude Code users. A humanizer Skill for editing AI-generated text, a security-review Skill that audits a pending pull request, and a commit-message Skill that formats Git commit messages are commonly cited examples. The awesome-claude-skills GitHub list curates community Skills focused on developer workflows, and the cross-vendor awesome-agent-skills repository tracks more than a thousand Skills confirmed to work in both Claude Code and the major non-Anthropic CLIs.[9][10][29]
Claude Code introduced a plugin system in October 2025, around the same time as Skills. Plugins are larger packages that can include Skills, slash commands, hooks, MCP server registrations, and configuration. Skills are one of several content types that a plugin can ship.[7][15]
The relationship can be summarized as follows:
| Concept | Scope | Contains |
|---|---|---|
| Skill | A single capability (one folder with SKILL.md) | Instructions, optional scripts, optional reference files |
| Plugin | A bundle of related capabilities | One or more Skills, slash commands, hooks, settings, MCP server registrations |
| Marketplace | A registry of plugins | Multiple plugins, each potentially containing many Skills |
A team that publishes a Claude Code marketplace can ship a single plugin called engineering-tooling that bundles a code-review Skill, a release-notes Skill, a slash command for triggering deploys, and an MCP server registration for the team's internal API. Installing the plugin gives every team member the same configuration in one step.[15]
Using Skills via the Claude API requires three beta headers and the code execution tool:[6]
| Requirement | Value |
|---|---|
| Beta header | code-execution-2025-08-25 |
| Beta header | skills-2025-10-02 |
| Beta header | files-api-2025-04-14 |
| Skill management endpoint | /v1/skills |
| Execution endpoint | Standard Messages API with container.skills populated |
| Maximum Skills per request | 8 |
| Maximum custom Skill upload size | Under 8 MB |
| File outputs | Returned with file_id for download via the Files API |
A minimal API request that uses both a built-in Skill and a custom Skill looks like this:
{
"container": {
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "1.0.0"},
{"type": "custom", "skill_id": "brand-guidelines", "version": "latest"}
]
}
}
Custom Skills uploaded via the API are workspace-wide: every member of the API workspace can use any uploaded Skill. This is different from Claude.ai, where uploads are per-user.[6]
The Claude Agent SDK wraps the Claude Code CLI binary, so any Skills resolvable to the SDK process inherit Claude Code's discovery rules. A developer building an autonomous agent that drafts pull requests, for example, can ship the agent with a .claude/skills/pr-summary directory and trust that the SDK will surface that Skill to Claude on every relevant prompt. This makes Skills the recommended way to package domain knowledge for SDK-based agents, as an alternative to inflating the system prompt or attaching every reference file as context on each turn.
Claude.ai exposes Skills under Settings > Features for users on Pro, Max, Team, and Enterprise plans with code execution enabled. Custom Skills are uploaded as ZIP files and remain private to the uploader. Pre-built document Skills (PowerPoint, Excel, Word, PDF) work transparently: if the user asks Claude to make a deck, Claude pulls in the pptx Skill without any explicit setup. Team and Enterprise admins gained centralized organization-wide provisioning on December 18, 2025: from claude.ai/admin-settings/skills they can enable any partner-built Skill for every member of the workspace, and admin-provisioned Skills are enabled by default.[6][23] User-uploaded custom Skills still have to be shared out of band or republished as an admin-managed package.
Claude Cowork, Anthropic's desktop AI agent for macOS and Windows, entered research preview in January 2026 and reached general availability on April 9, 2026.[25] Cowork treats Skills as one of three customization primitives (alongside connectors and plugins) and exposes them through the same unified directory used on Claude.ai. It shipped at GA with eleven official plugins built on Skills, covering legal, sales, finance, marketing, HR, customer support, recruiting, data analysis, software engineering, design, and operations; each plugin bundles Skills, connectors, slash commands, and subagents.[25] Users can describe a workflow in a sentence and have Claude assemble a one-shot plugin from existing Skills and connectors. The GA release also added six enterprise features: role-based access controls, group spend limits, usage analytics, OpenTelemetry support, a Zoom MCP connector, and per-tool connector controls.[25]
Anthropic launched Skills with several named enterprise partners and added more in the months after:[1][2]
When the open standard launched in December 2025, partner-built Skills from Atlassian, Cloudflare, Figma, Sentry, Stripe, Vercel, and Zapier joined the existing four, expanding the pool of vetted enterprise integrations.[23] In May 2026, Anthropic launched a vertical-industry push for legal, releasing more than twenty connectors and twelve practice-area plugins (litigation, transactional, IP, regulatory, immigration, and others) packaging Skills for law-firm workflows.[31]
For Team and Enterprise plans, administrators have a single console at claude.ai/admin-settings/skills to enable, restrict, or pin Skills for the workspace. User uploads remain private unless an admin packages them as a managed plugin, but partner Skills propagate organization-wide once toggled on.[6][23]
Skills run inside the same code-execution sandbox that Claude uses for any other script. On the Claude API the sandbox has no network access; on Claude.ai the level of network access depends on user and admin settings; in Claude Code, Skills run with the same access as any other process on the user's machine.[6]
Anthropic's official guidance on security includes:[6]
Because a malicious Skill can in principle direct Claude to invoke any tool the agent has access to, an audit step before installing community Skills is non-optional. The official documentation puts it plainly: "a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose."[6] In Claude Code, the project trust dialog protects against this for repository-checked Skills: the allowed-tools field only takes effect after the user accepts the workspace trust prompt for that folder.
Claude Skills data is not eligible for Zero Data Retention: Skill definitions and execution data are retained per Anthropic's standard retention policy.[6]
Anthropic publishes a best-practices document for Skill authors. The most repeated points are:[3][6][15]
SKILL.md itself under 500 lines. Move detailed reference material to separate files.[15]The skill-creator Skill, which ships in the Anthropic skills repository, will walk a user through these steps interactively: it asks about the workflow, generates the folder structure, fills in the YAML frontmatter, and bundles requested resources without manual file editing.[7]
The published documentation lists several limitations and constraints:[6]
description and when_to_use text at 1,536 characters in the listing, and the overall character budget for all Skill descriptions defaults to 8,000 characters or 1% of the context window, whichever is larger.[15]Reception in the developer community was strongly positive. Simon Willison's October 16, 2025 post argued that Skills "might be a bigger deal than MCP" because the format is dramatically simpler than the Model Context Protocol and because progressive disclosure solves the context-window cost problem that has dogged MCP servers in production. He predicted what he called a "Cambrian explosion" of community Skills.[5]
Within weeks, third-party marketplaces and curated lists appeared. The awesome-claude-skills GitHub list, the claude-skills-marketplace repository, the tonsofskills.com directory, and the SkillsMP catalog were all live by late 2025, collectively listing thousands of community Skills aimed at engineering, marketing, product, compliance, and executive workflows.[9][10][11] Coverage in InfoQ, The New Stack, AI Business, and Neowin emphasized the open-standard nature of the format and its potential to become a cross-vendor configuration layer for AI agents.[16][17][18][19]
Simon Willison's December 19, 2025 follow-up on the open-standard release pointed out the deliberate minimalism of the specification: brief enough to read in one sitting, lightly defined enough to leave room for vendor-specific extensions like Claude Code's disable-model-invocation field.[21] VentureBeat described the open standard as "the fastest cross-vendor standardization event in AI tooling," because the entire spec fits in a document a developer can read during a coffee break.[20] By April 2026, more than thirty independent agent products read the same SKILL.md format from the same directory structure, and Vercel's skills.sh directory listed nearly 90,000 community Skills across the catalog.
The scale caught most observers off guard. Aggregated search interest for "claude skills marketplace" grew roughly nine-fold over the first three months of 2026, and Vercel's skills.sh indexed tens of thousands of community uploads.[28][29] Several marketplaces, notably Agensi, opened revenue-sharing programs that pay authors a share of paid plan installs, the first time the Skills ecosystem has taken on storefront economics like the GPT Store.[28]
Skills succeeded where prior customization attempts (Custom GPTs, Gemini Gems) faltered because Skills are files. There is no upload, no hosting layer, no platform tax, no review process. A Skill is a directory in a Git repository. That choice is what made cross-vendor adoption possible: every agentic tool already knew how to read a folder.
| Date | Event | Source |
|---|---|---|
| October 16, 2025 | Public announcement of Agent Skills; available on Claude.ai (Pro, Max, Team, Enterprise), Claude Code, the Claude API, and the Claude Agent SDK | [1][2] |
| October 2025 | Public release of the anthropics/skills GitHub repository with example Skills and document Skills | [7] |
| October 2025 | Launch partners Box, Notion, Canva, and Rakuten announce production integrations | [1][2] |
| October 2025 | Claude Code plugin system enters public beta, with Skills as one supported content type | [15] |
| October 9, 2025 | Jesse Vincent (obra) publishes the Superpowers Skills framework, which becomes the most-starred community Skill project | [30] |
| Claude Code 2.1 (late 2025) | Hot reload for Skills, session teleportation, language-specific output | [15] |
| December 18, 2025 | Anthropic releases the Agent Skills format as an open standard at agentskills.io; the specification is published as the independent agentskills/agentskills GitHub repository; partner directory and org-wide admin provisioning ship for Team and Enterprise | [20][21][23] |
| December 18, 2025 | Microsoft integrates Skills into VS Code; OpenAI announces Codex CLI and ChatGPT support within 48 hours | [20] |
| January 2026 | Superpowers added to Anthropic's official Claude Code plugin marketplace | [30] |
| January 2026 | Claude Cowork enters research preview with Skills as a first-class building block | [25] |
| February 2026 | Anthropic launches the Claude Code plugin marketplace with eleven official plugins built on Skills | [25] |
| Early 2026 | Vercel's skills.sh directory and other third-party marketplaces collectively list tens of thousands of community Skills | [9][10][11] |
| March 2026 | Microsoft publishes the Azure Skills Plugin built on the open standard | [22] |
| March 31, 2026 | Anthropic launches the unified directory at claude.ai/customize for skills, connectors, and plugins | [24] |
| April 9, 2026 | Claude Cowork reaches general availability on macOS and Windows with eleven Skills-built plugins and six enterprise features | [25] |
| May 2026 | Anthropic ships more than twenty connectors and twelve practice-area plugins for legal workflows | [31] |
| Mid-2026 | More than thirty independent agent products read the same SKILL.md format | [22] |
What are Claude Skills in one sentence? Claude Skills are folders containing a SKILL.md instruction file plus optional scripts and reference files that Claude loads on demand to specialize at a repeatable task, using progressive disclosure to keep the context window small.[1][3]
When did Anthropic launch Skills? Anthropic announced Agent Skills on October 16, 2025 and made them available the same day across Claude.ai, Claude Code, the Claude API, and the Claude Agent SDK.[1][2]
Are Claude Skills free? Claude Code is free to download and supports custom Skills with no extra charge; the pre-built document Skills (PowerPoint, Excel, Word, PDF) are available on paid Claude.ai plans (Pro, Max, Team, Enterprise) and through the Claude API with the relevant beta headers.[6]
Is the Skills format open source? The Agent Skills format itself is an open standard published at agentskills.io on December 18, 2025, and most Skills in the anthropics/skills repository are licensed under Apache 2.0. The exception is the four document Skills, which are source-available rather than open source.[7][20]
Do Skills work outside Claude? Yes. After the December 2025 open-standard release, more than thirty agent products read the same SKILL.md files, including GitHub Copilot, VS Code, Cursor, Google's Gemini CLI, and OpenAI's Codex CLI.[20][22]
How are Skills different from MCP? Skills teach Claude how to perform a task as static Markdown; the Model Context Protocol connects Claude to live external systems through a server. They are complementary, and the dominant 2026 production pattern pairs a Skill (the playbook) with one or more MCP servers (the data sources).[5][26]