Agent Skills Explained: What They Are, How They Work, and When to Use Them Over Prompts, Projects, or MCP

Agent Skills are folders of instructions, scripts, and resources that Claude discovers and loads automatically when they are relevant to the task at hand. Anthropic introduced them in October 2025 and describes them as custom onboarding materials: you package your expertise once, and Claude becomes a specialist on what matters to you.

The format is simple (a folder with a Markdown file, at minimum). What makes Agent Skills worth understanding properly is the architecture underneath: skills stay out of Claude's context window until the moment they are needed, they can carry executable code, and the same folder runs across the Claude apps, Claude Code, and the API.

This guide explains what Agent Skills are, how the loading architecture works, how skills compare to prompts, projects, subagents, and MCP, and what to know before rolling them out to your team. It draws on Anthropic's announcement, their Skills Explained post, and the platform documentation.

What Are Agent Skills?

An Agent Skill is a directory containing a SKILL.md file plus optional supporting material: extra instruction files, reference documents, and executable scripts. Claude scans the metadata of every installed skill, and when a request matches what a skill declares itself to be for, Claude loads it and follows it. No manual selection involved; you can watch the decision happen in Claude's visible reasoning.

Anthropic frames skills around four characteristics:

• Composable. Skills stack. Claude can coordinate multiple skills in a single task without being told which ones to combine.
• Portable. The same folder format works across the Claude apps, Claude Code, and the API.
• Efficient. Only the minimum necessary information loads at each stage. The next section covers exactly how.
• Powerful. Skills can bundle executable code, which turns fuzzy instructions into deterministic operations.

Skills are custom onboarding materials that let you package expertise, making Claude a specialist on what matters most to you.

How Agent Skills Work: Progressive Disclosure

Skills run in Claude's virtual machine environment, where Claude has filesystem access, bash, and code execution. A skill is a directory on that filesystem, and Claude interacts with it the way you would: reading files, running scripts. This is what enables progressive disclosure, the three-stage loading system that keeps skills nearly free until used.

Level 1: Metadata (always loaded)

At startup, Claude loads only each skill's YAML frontmatter into the system prompt: a name and a description. Anthropic's documentation puts the cost at roughly 100 tokens per skill, which is why you can install many skills without a context penalty. The description is what Claude matches your request against, so it must say both what the skill does and when to use it.

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

Level 2: Instructions (loaded when triggered)

When a request matches the description, Claude reads the body of SKILL.md from the filesystem with a bash command. Only then do the full instructions (workflows, best practices, guidance) enter the context window, at under 5,000 tokens.

Level 3: Resources and code (loaded as needed)

Skills can bundle additional instruction files, reference material like schemas and API docs, and executable scripts:

pdf-processing/
├── SKILL.md          # Main instructions
├── FORMS.md          # Form-filling guide
├── REFERENCE.md      # Detailed API reference
└── scripts/
    └── fill_form.py  # Utility script

These cost nothing until accessed. A skill can carry dozens of reference files; if the task only needs one schema, that is the only file Claude reads. Scripts are the most efficient part of the model: when Claude runs fill_form.py through bash, the script's code never enters the context window. Only its output does, like 'validation passed' or a specific error message. That makes bundled scripts cheaper and more reliable than having Claude write equivalent code on the fly.

Here is the full sequence for a request like 'extract the text from this PDF and summarize it':

1. At startup, the system prompt carries one line for the skill: the pdf-processing name and description.
2. The request matches the description, so Claude reads SKILL.md from the filesystem.
3. Form filling is not needed, so FORMS.md stays unread and costs nothing.
4. Claude completes the task using the loaded instructions.

Agent Skills vs Prompts, Projects, Subagents, and MCP

Skills are one of five ways to shape Claude's behavior, and picking the wrong one wastes effort. The short version: skills carry procedural knowledge that persists across conversations. Here is how that differs from each alternative.

Skills vs prompts

Prompts are moment-to-moment instructions for a single conversation. The rule of thumb from Anthropic: if you are pasting the same instructions into a third conversation, turn them into a skill. You get consistency across sessions and stop paying the repetition tax.

Skills vs projects

Projects hold background knowledge: documents and context that load statically within that project. Skills hold procedures that activate on demand anywhere. Anthropic's framing: projects are 'what you need to know', skills are 'how to do things'.

Skills vs subagents

Subagents delegate: independent task execution with their own tool permissions. Skills travel: portable expertise any agent can apply. The two combine well, since subagents can load skills, pairing independent execution with shared know-how.

Skills vs MCP

MCP connects Claude to data and tools; skills teach Claude what to do with them. An MCP server without a skill leaves users to figure out the workflow themselves. A skill without MCP cannot reach your systems. Production agents typically want both.

Anthropic's example of the pieces working together: a research agent with a project holding market research documents, MCP connections to Google Drive and GitHub, a competitive-analysis skill providing the framework, and specialized subagents for market and technical analysis. Each layer answers a different question, and none replaces another.

Pre-Built vs Custom Agent Skills

Anthropic ships pre-built skills for the document formats teams touch daily: PowerPoint (pptx), Excel (xlsx) including formulas and charts, Word (docx), and PDF generation and form filling (pdf). On claude.ai they are active whenever you create documents, with no setup. On the API you reference them by skill ID.

Custom skills are the same format applied to your world: your compliance checklist, your brand guidelines, your reporting template. Anthropic's example is a brand guidelines skill holding color palettes and typography rules that applies itself to every presentation, without anyone re-explaining the brand. Anthropic also maintains an open-source skills repository on GitHub, including the Claude API skill that comes bundled with Claude Code.

What Teams Use Agent Skills For

Three buckets cover most real usage: organizational workflows (compliance steps, templates, brand standards), domain expertise (data analysis patterns, document manipulation, spreadsheet formulas), and personal preferences (your note-taking system, your coding conventions).

Early enterprise reports are worth noting. Rakuten says skills cut an accounting workflow from a day of work to about an hour. Box uses skills to turn stored files into presentations, spreadsheets, and documents that follow organizational standards. Notion and Canva are building on skills for faster task completion and customized agents. These are vendor-reported results, so weigh them accordingly, but the pattern is consistent: the value concentrates where work repeats and standards matter.

Where Agent Skills Run (and What Does Not Transfer)

claude.ai

Pre-built document skills work with no setup. Custom skills upload as zip files through Settings under Features, on Pro, Max, Team, and Enterprise plans with code execution enabled. Two limits to plan around, per Anthropic's platform docs: custom skills are individual to each user, and claude.ai has no centralized admin management or org-wide distribution, so each team member uploads their own copy.

Claude API

Skills run inside the code execution tool's sandboxed container: pass the skill ID in the container parameter with the skills beta header. Custom skills upload through the /v1/skills endpoints and are shared workspace-wide, so the whole team gets them at once. The sandbox has no network access and no runtime package installation, so bundle everything your skill needs. Claude Platform on AWS and Microsoft Foundry follow the API's behavior.

Claude Code

Custom skills are plain directories: ~/.claude/skills/ for personal skills, .claude/skills/ inside a repo for project skills, shareable through plugins. Unlike the API sandbox, skills here have the same network access as any program on your machine. The pre-built document skills are not available in Claude Code.

Custom skills do not sync across surfaces

A skill uploaded to claude.ai is not available on the API, and vice versa; Claude Code skills are filesystem-based and separate from both. The folder format is identical, so the same skill works everywhere, but you deploy it to each surface separately. Factor that into any team rollout plan.

Security: Treat Skills Like Installing Software

Skills give Claude new capabilities through instructions and executable code. That is the point, and also the risk: a malicious skill can direct Claude to invoke tools or run code in ways that do not match its stated purpose. Anthropic's guidance is blunt: use skills you wrote yourself or obtained from Anthropic, and audit everything else the way you would audit software before installing it.

Also relevant for regulated teams: Anthropic notes that Agent Skills are not eligible for Zero Data Retention arrangements. Skill definitions and execution data follow the standard retention policy.

Package the Expertise Once

Every team runs on procedural knowledge that lives in someone's head, a stale wiki page, or a prompt someone keeps pasting. Agent Skills give that knowledge a format: a folder that loads itself when needed, runs code when precision matters, and costs almost nothing while idle.

Start by noticing repetition. The instructions you have typed three times this month are your first skill candidate. When you are ready for the step-by-step build process, including frontmatter rules, testing, and troubleshooting, our guide to building your first skill covers it end to end.