What Are Claude Agent Skills? A Plain-English Guide to Anthropic's Open Standard

In October 2025, Anthropic introduced Agent Skills — a way to teach Claude a repeatable workflow once and have it apply that workflow automatically whenever it's relevant. In December 2025, Anthropic published the Skills spec as an open standard, which means the same idea now works across a growing list of AI tools, not just Claude. If you've seen the term "skill" thrown around and weren't sure whether it was a feature, a file format, or a marketing word, this guide clears it up. No coding background required, though there's enough technical detail here to be useful if you build.

TL;DR

An Agent Skill is a folder containing a SKILL.md file — a set of plain-English instructions, plus optional scripts and reference files — that Claude loads only when it's relevant to your task. Anthropic describes a skill as being like "an onboarding guide for a new hire." Skills make a general-purpose assistant behave like a specialist, they don't bloat the context window because of a design called progressive disclosure, and as of December 2025 they're an open standard that works across Claude.ai, Claude Code, the Claude API, and many third-party agents. The community directory skills.sh already lists hundreds of thousands of installable skills.

The problem Skills solve

Claude is broadly capable out of the box. But every team has its own way of doing things — your brand voice, your reporting format, your client onboarding steps, the specific way you want a contract reviewed. Without skills, you re-explain that context every single time. You paste the same style guide, repeat the same instructions, correct the same mistakes.

A prompt fixes this for one conversation. A skill fixes it permanently. You capture the procedure once, and from then on Claude reaches for it automatically when the situation calls for it. Anthropic frames the distinction cleanly: prompts are conversation-level instructions for one-off tasks; skills are reusable capabilities that load on demand across every conversation.

That's the whole pitch — turn the knowledge that currently lives in your head, or in a scattered set of docs, into something your AI assistant uses without being reminded.

What a Skill actually is

A skill is a directory (a folder) on a filesystem. At minimum it contains one file: SKILL.md. That file has two parts.

The first part is YAML frontmatter — a small block of metadata at the top with two required fields:

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

The name is a short identifier (lowercase letters, numbers, and hyphens, up to 64 characters). The description is the important one: it tells Claude both what the skill does and when to use it. This is the single most important sentence in the whole skill, because it's how Claude decides whether the skill is relevant to your request.

The second part is the body — ordinary Markdown containing the instructions, examples, and guidance Claude should follow:

# PDF Processing
 
## Instructions
Use pdfplumber to extract text from PDFs. For form filling,
see FORMS.md. For the full API reference, see REFERENCE.md.
 
## Examples
[concrete examples of the skill in use]

That's the entire required structure. A useful skill can be a single file. More advanced skills add bundled extras — additional Markdown files (a forms guide, a detailed reference), executable scripts, and reference materials like templates or schemas.

How Skills work: progressive disclosure

This is the clever part, and it's worth understanding even if you never write a skill yourself, because it explains why you can install a lot of skills without slowing Claude down.

The naive way to give an AI extra knowledge is to stuff everything into its prompt. That fills up the "context window" — the amount of text the model can hold at once — and it gets expensive and slow fast. Skills avoid this with progressive disclosure: Claude loads information in three stages, only as it's needed.

Here's the sequence in practice. At startup, Claude knows the name and description of every installed skill — that's it. It's like a colleague who knows the table of contents of a manual but hasn't read the chapters. When you ask for something that matches a skill's description, Claude reads the full SKILL.md into context. If those instructions point to other files — a detailed forms guide, a database schema — Claude reads only the ones the task actually requires. The rest stay on disk, costing nothing.

A walkthrough of the built-in PDF skill, straight from Anthropic's docs:

1. Startup: the system prompt includes PDF Processing — Extract text and tables from PDF files, fill forms, merge documents.
2. You ask: "Extract the text from this PDF and summarize it."
3. Claude reads SKILL.md via a bash command — now the instructions are in context.
4. Claude decides form filling isn't needed, so it skips FORMS.md.
5. Claude completes the task using only what it loaded.

Because bundled files don't consume context until they're opened, a single skill can include comprehensive documentation, large datasets, or dozens of reference files with no penalty for the parts you don't touch. Anthropic's phrasing: "the amount of context that can be bundled into a skill is effectively unbounded."

Instructions, code, and resources

The three kinds of content a skill can bundle each play to a different strength:

• Instructions (Markdown) are for flexible guidance — workflows, judgment calls, best practices. This is where most skills live.
• Code (scripts Claude runs via bash) is for things that need to be reliable and exact. A script to fill a PDF form field runs deterministically, and crucially, the script's code never enters the context window — only its output does. That makes a bundled script far more efficient and trustworthy than asking Claude to generate the equivalent code on the fly each time.
• Resources (templates, schemas, API docs, examples) are for factual lookup — the reference material Claude consults when it needs a specific fact.

A fuller skill folder might look like this:

pdf-skill/
├── SKILL.md        (main instructions)
├── FORMS.md        (form-filling guide)
├── REFERENCE.md    (detailed API reference)
└── scripts/
    └── fill_form.py (utility script)

Where Skills work

Skills run anywhere Claude has a filesystem and the ability to run code. As of this writing that's four Anthropic surfaces, and they don't all behave identically:

• Claude.ai — Pre-built skills (PowerPoint, Excel, Word, PDF) already run behind the scenes when you create documents; no setup. You can upload custom skills as zip files under Settings → Features on Pro, Max, Team, and Enterprise plans. Important caveat: custom skills on Claude.ai are per-user — each team member uploads their own, and there's no central admin management.
• Claude Code — Supports custom skills only, stored as folders either personally (~/.claude/skills/) or per project (.claude/skills/). No upload step; they're just files. Skills here have full network access, like any program on your machine.
• Claude API — Supports both pre-built and custom skills, uploaded via the /v1/skills endpoints and shared across a workspace. Skills in the API run sandboxed: no internet access and no installing new packages at runtime.
• Claude Agent SDK — The same skill behavior for developers building their own agents.

One limitation worth flagging: skills do not sync across these surfaces. A skill you upload to Claude.ai isn't automatically available in the API or in Claude Code. You manage them separately per surface.

The open standard and skills.sh

In December 2025, Anthropic released the Agent Skills spec as an open standard for cross-platform portability — the same playbook it used with the Model Context Protocol (MCP), which became the de facto way agents connect to tools. (If MCP is unfamiliar, our plain-English MCP explainer breaks it down.) Skills and MCP solve different problems: MCP connects an agent to external tools and data; Skills package procedural knowledge — the how-to. They're complementary.

Making Skills an open standard means the format isn't Claude-only. The community directory skills.sh (opens in a new tab) (an open-source ecosystem, not an Anthropic property) lists skills you can install into a wide range of agents — Claude Code, Cursor, GitHub Copilot, Gemini, Cline, Windsurf, and 20-plus others — usually with a single command like npx skills add <owner/repo>. The directory already catalogs an enormous number of skills (well into the hundreds of thousands), contributed by companies like Vercel and Microsoft alongside independent developers, with categories spanning frontend design, databases, marketing, and more.

The practical takeaway for a business: the format you learn once is increasingly portable across whatever AI tools your team adopts.

How a small business should think about Skills

You don't need to write code to benefit from this. The mental shift is the valuable part: anything you currently re-explain to Claude over and over is a candidate to become a skill.

Concrete examples of skills a non-technical operator might want:

• Brand voice — a skill that captures your tone, banned phrases, and formatting rules, so every draft comes out sounding like you without a reminder.
• Client onboarding — your standard intake steps, the documents you collect, and the email templates you send, packaged so Claude can run the sequence on request.
• Report format — the exact structure of your monthly client report, so Claude assembles it the same way every time from raw numbers.
• Proposal builder — your pricing tiers, scope language, and proposal template, captured once.

A good way to start: do the task with Claude manually a few times in plain conversation. Notice what you keep correcting and re-explaining. That repeated context is the skill — write it down in a SKILL.md, give it a clear description of when to use it, and you've built one.

A note on security

Because a skill can contain instructions and code that Claude will execute, treat installing one like installing software. Anthropic's guidance is direct: use skills only from sources you trust — ones you wrote yourself or got from Anthropic. A malicious skill could direct Claude to misuse tools, access files it shouldn't, or leak data to an external system. Skills that fetch content from external URLs are especially risky, since that fetched content could carry hidden instructions. Before using a skill from an unknown source, audit every bundled file — the SKILL.md, any scripts, and any resources — and look for anything that doesn't match the skill's stated purpose. The convenience of community directories like skills.sh is real, but so is the need to vet what you install.

Frequently asked questions

What is a Claude Agent Skill?

An Agent Skill is a folder containing a SKILL.md file — plain-English instructions plus optional scripts and reference files — that Claude loads automatically when it's relevant to your task. Anthropic compares a skill to an onboarding guide for a new hire. Skills turn a general-purpose assistant into a specialist for your specific workflows.

What is the difference between a Skill and a prompt?

A prompt is an instruction for a single conversation; you re-supply it each time. A skill is a reusable capability that loads on demand across every conversation, so you capture the procedure once and Claude applies it automatically whenever it fits. Skills eliminate repeating the same guidance.

What is progressive disclosure in Agent Skills?

Progressive disclosure is the design that lets Claude load skill information in stages instead of all at once. Only the name and description (~100 tokens) load at startup; the full instructions load when the skill is triggered; and bundled files or scripts load only when a task needs them. This keeps the context window lean even with many skills installed.

Do Agent Skills only work with Claude?

No. Anthropic published the Agent Skills spec as an open standard in December 2025, so the format works beyond Claude. The community directory skills.sh lists skills installable into Claude Code, Cursor, GitHub Copilot, Gemini, and 20-plus other agents. Within Anthropic's own products, skills run on Claude.ai, Claude Code, the Claude API, and the Agent SDK.

How do I create a custom Skill?

Create a folder with a SKILL.md file containing YAML frontmatter (a name and a description of what the skill does and when to use it) followed by Markdown instructions. Add optional scripts and reference files if needed. In Claude Code it's just files on disk; on Claude.ai you upload a zip under Settings → Features; via the API you upload through the Skills endpoints.

Are Agent Skills safe to use?

Skills can include code that Claude executes, so treat them like installing software: use only skills from trusted sources. A malicious skill could misuse tools or leak data, and skills that pull from external URLs carry extra risk. Audit every bundled file before using a skill from an unknown source.

Start by capturing one workflow

The fastest way to understand Skills is to build one. Pick a task you hand to Claude repeatedly — a report format, your brand voice, a client email sequence — and write down the instructions you keep repeating. That document is a skill in everything but name.

If you want a structured path to using Claude well at work before you get into building skills, the free Claude Cowork course walks through real prompts and real workflows, built for operators and small teams rather than developers. It's a free download.