How Claude Skills work

Progressive disclosure, where Skills run, pre-built document Skills, and the security habits that matter.

Updated November 2026 from Anthropic’s public documentation. Always check the live docs if you are implementing Skills in production — product names and plan limits change.

In this guide

What a Skill is
Progressive disclosure
Where Skills work
Pre-built and custom Skills
Security
Limits worth knowing

What a Skill is

A Claude Skill — Anthropic also calls the format Agent Skills — is a folder of instructions, and optionally scripts and reference files, that Claude loads when a task matches the skill’s description. At minimum the folder contains a SKILL.md file. That file starts with YAML frontmatter (a name and a description) and then ordinary Markdown instructions.

Anthropic’s own research note, Equipping agents for the real world with Agent Skills, describes the idea as packaging procedural knowledge the way you would onboard a new teammate: not one giant prompt you paste every time, but a reusable directory the agent can open when it needs it.

The same folder shape is documented as an open format at agentskills.io/specification. Tools besides Claude may implement that format; this guide sticks to how Claude uses it.

Unlike a one-off prompt, a Skill is meant to be installed once and reused. Claude does not need the full text in every conversation. It only needs enough metadata to decide whether the Skill is relevant.

How loading works: progressive disclosure

Claude does not read every installed Skill in full at the start of a chat. Anthropic describes three layers:

Layer	When it loads	What it costs	What it contains
1. Metadata	At startup, for every installed Skill	Anthropic estimates on the order of ~100 tokens per Skill	The `name` and `description` from YAML frontmatter, injected so Claude can choose among Skills
2. Instructions	When Claude decides the Skill matches the request	The body of `SKILL.md` (keep this lean; under ~5,000 tokens is the documented guidance)	The procedure, rules, and examples
3. Resources and code	Only if the instructions point to them	Nothing until accessed. Scripts contribute their output, not their source, when Claude runs them	Extra Markdown, templates, data files, and executable scripts

That design is why the description field is the most important writing you will do. It is the only part Claude reliably sees before it decides to open the file. A vague description such as “Helps with documents” will either never trigger or trigger at the wrong time. A good one says both what the Skill does and when to use it, with the keywords a user is likely to type.

On surfaces where Claude has a filesystem and bash, Anthropic documents that Claude reads SKILL.md the way a person would open a file, then follows any relative links to references/, assets/, or scripts/. This is also why Skills can bundle material that would never fit in a single system prompt: unread files do not consume the context window.

Where Skills work

As of Anthropic’s current platform docs, Skills show up across several Claude products. They do not automatically sync from one surface to another.

claude.ai. Anthropic’s pre-built document Skills can run when you create files. You can also upload custom Skills as zip files. Platform docs list custom uploads for Pro, Max, Ultra, Team, and Enterprise plans when code execution is enabled. Check your account’s Skills settings and the Claude Help Center for the latest plan list.
Claude Code. Custom Skills are ordinary folders. Personal Skills live in ~/.claude/skills/; project Skills live in .claude/skills/. They can also ship inside Claude Code plugins. The pre-built PowerPoint, Excel, Word, and PDF Skills that exist on claude.ai and the API are not the ones bundled into Claude Code.
Claude API, Claude Platform on AWS, and Microsoft Foundry (hosted-on-Anthropic deployments). API Skills run inside the code execution container. You list skill_ids in the container parameter and include the code execution tool. Custom Skills are uploaded through the Skills API (/v1/skills) and are workspace-wide. Managed Agents can attach Skills in an agent’s skills array or load them from a GitHub repository mounted on the session.

Because uploads do not sync, a Skill you add in Claude Code is not automatically available in claude.ai or the API. You install it again on each surface where you need it.

Pre-built Skills and custom Skills

Anthropic ships pre-built Agent Skills for common document work: pptx (PowerPoint), xlsx (Excel), docx (Word), and pdf. The platform docs list those on the Claude API, Claude Platform on AWS, Microsoft Foundry, and claude.ai.

There is also an open-source Claude API skill in Anthropic’s public skills repository, which supplies up-to-date API reference material. It is bundled with Claude Code and can be installed from that repository.

Custom Skills are how you capture your own way of working: a review checklist, a brand voice, a data-analysis path, a support policy. If you can write the procedure down for a new hire, you can usually turn it into a Skill. See our companion guide, How to write a SKILL.md.

Security

Skills are more powerful than a snippet of text. They can instruct Claude to read files, run scripts, and call tools. Anthropic’s overview is blunt: use Skills from trusted sources — ones you wrote or obtained from Anthropic — and audit anything else before you turn it on. A malicious Skill can look useful in its description and still direct the agent toward data exfiltration, unexpected network calls, or tool misuse.

Practical habits:

Read every file in the folder, not only SKILL.md.
Be extra careful with Skills that fetch URLs. The fetched page can contain new instructions.
Treat installing a Skill like installing software, especially in production systems.
Claude Enterprise organizations can enable Skill content scanning for custom Skills uploaded in claude.ai and Claude Cowork. Anthropic notes that scanning does not cover Skills uploaded through the Skills API or the Claude Console.

Limits worth knowing

Runtime differs by product. The Claude API sandbox has no network access and no runtime package installation — only pre-installed packages. Claude Code Skills have the same network access as other programs on that computer. claude.ai network access depends on user and admin settings.
Sharing differs by product. API Skills are workspace-wide. Claude Code Skills are personal or project-based, or shared as plugins.
Data retention. Anthropic states that Agent Skills are not covered by zero-data-retention arrangements. Skill definitions and execution data follow Anthropic’s standard retention policy.
Model availability. Platform docs currently say Agent Skills are available on every model, with product-specific setup (for example, the Messages API still needs the code execution tool).