What Are Claude Skills? How Anthropic's Agent Skills Work

Claude Skills — Anthropic calls them "Agent Skills" in its technical documentation — are folders of instructions, scripts, and reference files that Claude can load partway through a task, instead of carrying every bit of specialized knowledge in its context window at all times. A skill might teach Claude how to fill out a PDF form, format a presentation to a company's brand guidelines, or file a ticket in Jira the way a particular team does it. Claude only reads a skill's contents when the task in front of it actually calls for that skill, which is the entire point: it lets Claude carry far more specialized expertise than it could if everything had to sit in the prompt from the first token.

What exactly is a Claude Skill?

In Anthropic's own framing, building a skill is like writing an onboarding guide for a new hire: you don't hand a new employee the entire employee handbook before their first task, you give them the specific procedure for the job at hand, plus pointers to where the rest of the detail lives if they need it. A Claude Skill is that same idea formalized as a directory on disk.

At minimum, a skill is one file: SKILL.md, which opens with YAML frontmatter naming the skill and describing what it does and when to use it. Around that file, a skill can bundle almost anything else Claude might need — a Python script that extracts fields from a PDF, a markdown reference document listing a company's brand colors, a template spreadsheet, or a JSON schema for an internal database. Claude reads SKILL.md with a plain filesystem command (cat, essentially) when it decides the skill is relevant, and only opens the other bundled files if the instructions in SKILL.md point it to them.

This is a close cousin of MCP, the protocol that lets Claude connect to outside tools and data sources — but the two solve different problems. MCP gives Claude a new tool to call, such as a connector to a CRM or project tracker. A skill gives Claude the procedural know-how for using a tool well, such as which fields to fill in a certain order, or what counts as a complete filing in a specific company's workflow. Anthropic's documentation explicitly describes the two as complementary, and skills are often written specifically to tell Claude how to drive an MCP-connected service.

How "progressive disclosure" actually works

The mechanism that makes skills cheap to keep around is what Anthropic calls progressive disclosure, and it happens in three stages:

1. Discovery (always loaded). At the start of a session, Claude loads only the name and description of every installed skill into its system prompt — Anthropic estimates roughly 100 tokens per skill. This is enough for Claude to recognize when a skill might be relevant, without the cost of loading its full content.
2. Activation (loaded when triggered). If a user's request matches a skill's description, Claude reads the full body of SKILL.md into context. Anthropic's guidance keeps this under roughly 5,000 tokens for a well-written skill.
3. Execution (loaded as needed). From there, Claude follows the instructions, which may tell it to open a specific reference file, run a bundled script, or both. Scripts run through Claude's bash access; only their output — not the script's own source code — enters the context window.

The practical upshot, per Anthropic's engineering documentation, is that there's no real ceiling on how much a skill can bundle. A skill can ship a dozen reference files and a full API manual, and none of it costs any context unless a given task actually needs that specific file. Claude is, in effect, choosing what to read off a filesystem the way a person would, rather than trying to hold the whole manual in its head.

Anatomy of a SKILL.md file

Anthropic's developer documentation lays out concrete constraints for the two required frontmatter fields:

• name: up to 64 characters, lowercase letters, numbers, and hyphens only, no XML tags, and it cannot contain the reserved words "anthropic" or "claude."
• description: up to 1,024 characters, no XML tags, and it has to state both what the skill does and when Claude should use it — because this description is the only thing Claude sees before deciding whether a skill is relevant.

A typical bundle looks like this on disk:

Below the frontmatter, SKILL.md is ordinary markdown: short, direct instructions, a quick-start code sample if relevant, and links to the other files by name. Anthropic's own advice to skill authors: write it the way you'd brief a new team member on one task, not the way you'd write a comprehensive manual. The full field-by-field requirements live in Anthropic's Agent Skills developer documentation.

Prebuilt skills vs. custom skills

Anthropic's documentation splits skills into a few categories:

• Prebuilt (Anthropic) skills ship for document work: PowerPoint, Excel, Word, and PDF. These are active automatically wherever Claude creates or edits those file types — in claude.ai, through the API, on Claude Platform on AWS, and on Microsoft Foundry (where they require a "Hosted on Anthropic" deployment) — with no setup required from the user.
• Custom skills are written by individuals or organizations for their own workflows: applying a specific brand style, formatting meeting notes a certain way, filing tasks into Jira, Asana, or Linear, or running a company-specific data pipeline.
• Organization-provisioned skills, on Team and Enterprise plans, let an admin push a custom skill out to everyone in the organization and set whether it's on or off by default.
• Partner skills, built by companies such as Notion, Figma, and Atlassian to pair with their own MCP connectors, are listed in a Skills Directory inside Claude's settings.
• Open-source skills that Anthropic publishes itself in a public GitHub repository, including a "Claude API skill" that bundles up-to-date SDK reference material for eight programming languages and ships with Claude Code by default.

Where you can actually use Claude Skills

Skill support differs meaningfully by surface, and — importantly — skills don't sync between them. A skill uploaded to claude.ai has to be separately uploaded to the API; a skill built for Claude Code lives on the filesystem and isn't automatically available anywhere else.

On the API, skills run inside a sandboxed container with no network access and no ability to install new packages at runtime — only pre-configured dependencies are available. In Claude Code, by contrast, a skill has the same network access as any other program running on that machine, and Anthropic's docs caution against having skills install packages globally. In claude.ai, network access for a skill depends on account and admin settings and can range from full to none. Enterprise organizations can additionally turn on content scanning that checks custom skills uploaded in claude.ai and Claude Cowork for malicious content (this scanning does not cover skills uploaded through the API or Console).

One more detail worth knowing if you're relying on Claude for sensitive material: Anthropic's platform documentation states that Agent Skills is not covered by zero-data-retention arrangements, so skill definitions and execution data are retained under Anthropic's standard retention policy rather than being excluded from it.

The open Agent Skills standard

Skills started as an Anthropic-only feature, introduced in an October 16, 2025 engineering blog post by Barry Zhang, Keith Lazuka, and Mahesh Murag. On December 18, 2025, Anthropic published the format itself as an open standard — the specification and a reference SDK are hosted at agentskills.io, with development happening in the open on GitHub. The pitch is portability: a skill folder written once, following the spec, should work the same way across any agent that implements it, not just inside Claude.

agentskills.io's own client showcase — which, since it's the standard's own site, is a reasonable read on actual adoption — lists a long roster of agent tools built around the format, including Claude Code and claude.ai themselves, Cursor, GitHub Copilot, VS Code, Google's Gemini CLI, and OpenAI's ChatGPT & Codex, among dozens of smaller coding agents and frameworks. The standard is explicitly open to outside contributions rather than Anthropic-governed alone.

It's worth being precise here, because the naming gets confusing fast: this open "Agent Skills" format is not the same thing as the "Skills" feature Google is rolling into the Gemini app to replace Gems. Google's Gemini Skills are a product feature inside Google's own app; the Agent Skills standard at agentskills.io is a shared file format that multiple companies' agents — including, per its own client list, Gemini CLI — can choose to read. They happen to share a name and a similar basic idea (packaged, on-demand instructions), but one is a single company's app feature and the other is an interoperable, cross-vendor specification.

How to actually create and use a skill

The mechanics differ slightly by surface, but the underlying task — writing a good SKILL.md — is the same everywhere:

• In Claude apps: open Settings, go to the "Skills" section under Customize, and either browse the Skills Directory for a prebuilt or partner skill, or create a custom one. Anthropic also offers a "skill-creator" skill that interviews you about the workflow you want to capture and generates the folder, the SKILL.md frontmatter, and any bundled files for you, without hand-editing markdown.
• In Claude Code: create a directory under ~/.claude/skills/ for a personal skill or .claude/skills/ inside a project for a team-shared one, drop in a SKILL.md with the required frontmatter, and Claude Code will discover and use it automatically. Skills can also be distributed as Claude Code Plugins or pulled from Anthropic's public skills repository.
• Through the API: upload a skill with the /v1/skills endpoint (or manage it in the Claude Console), then reference it by its skill_id in the container parameter alongside the code execution tool when you send a Messages API request. Anthropic's four prebuilt document skills are also addressable this way using the ids pptx, xlsx, docx, and pdf.

In every case, the authoring advice is the same: start from a handful of real example tasks rather than guessing at requirements, keep SKILL.md itself short and split anything long into a separate referenced file, and write the description field carefully, since that's the only text Claude sees before deciding whether the skill is even relevant to what you've asked. Anthropic's Claude Help Center article, "What are Skills?", walks through the claude.ai version of this flow in more detail.

Security: skills can run code, so vet them like software

Because a skill can bundle executable code and instructions that direct Claude to call other tools, Anthropic's own guidance treats installing a skill as roughly equivalent to installing software: use skills you wrote yourself or that came from Anthropic, and if you must use one from an unfamiliar source, audit every file in it first — not just SKILL.md, but any scripts, images, and other bundled resources — for unusual network calls or file access that doesn't match what the skill claims to do. A skill that fetches data from an external URL is a particular risk, since the fetched content itself could carry malicious instructions. Anthropic recommends extra caution before connecting an untrusted skill to systems that hold sensitive data.

What's next for Claude Skills

Anthropic's own posts describe this as an early stage of the feature: the company says it's working toward simpler skill creation, better discovery and sharing tools, and eventually letting agents write, edit, and evaluate their own skills rather than relying entirely on a person to author them. With the format now published separately as an open standard at agentskills.io, the more immediate practical test is adoption — whether a skill written for Claude keeps working, unmodified, inside the growing list of other agents that say they support the spec. For a deeper look at how Claude's broader context tools fit together, see how Claude's memory feature persists information across chats, which solves a related but distinct problem from skills: memory is about what Claude remembers, skills are about what Claude knows how to do.

Written byTheo Park

Theo Park runs the AI desk at Pandromeda. He follows model launches from the frontier labs and the open-weight community, tracks the assistants and developer tools built on them, and explains what each release changes on pricing, capability and safety. His reporting leans on primary sources: model cards, technical reports, API documentation and the companies' own announcements.

More from Theo ParkAll AI coverage