What Are Agent Skills? Claude’s On-Demand Expertise, Explained

If you have wired up an AI agent, you know the friction: you paste the same 800-word "here's how we format reports" prompt into every conversation, bolt on a one-off tool, fork a bespoke agent for a single workflow — and none of it travels. Anthropic's Agent Skills, introduced on October 16, 2025, are a deliberate fix for that fragmentation. On its engineering blog, Anthropic defines a skill as "organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks." The platform docs put the payoff more bluntly: Skills are "reusable, filesystem-based resources" that "transform general-purpose agents into specialists."

The problem is one of economics. As agents take on more, Anthropic argues, "we need more composable, scalable, and portable ways to equip them with domain-specific expertise." Rather than "building fragmented, custom-designed agents for each use case, anyone can now specialize their agents with composable capabilities." Crucially, a Skill is not a rebrand of the building blocks you already know. A prompt is a one-off conversation instruction. MCP connects an agent to a tool or data source. A subagent is a separate context window. A Skill is the packaged procedural knowledge — the workflow, conventions, and reference material — that teaches the agent how to do the work well.

The anatomy of a skill

The format is almost aggressively minimal. A Skill is a directory named after the skill, and its only required file is SKILL.md. As the engineering post states, "At its simplest, a skill is a directory that contains a SKILL.md file. This file must start with YAML frontmatter that contains some required metadata: name and description." Everything else — reference docs, scripts, templates — is optional.

Those two frontmatter fields carry strict, cross-surface constraints. The name is capped at 64 characters; uses only lowercase letters, numbers, and hyphens; permits no XML tags; and cannot contain the reserved words anthropic or claude. The description must be non-empty, max 1024 characters, and should state both what the Skill does and when Claude should use it. Below the frontmatter, the Markdown body holds the actual instructions.

---
name: processing-pdfs
description: Extract text and tables from PDF files, fill forms, and merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# Processing PDFs

## Instructions
1. To inspect a form's fields, run `scripts/analyze_form.py`.
2. To fill a form, run `scripts/fill_form.py` with the field map.
3. For the field-mapping reference, see `reference.md`.

## Notes
Always validate output with `scripts/validate.py` before returning.

Bundled resources conventionally sit in three subfolders, a layout codified in Anthropic's skill-creator example: scripts/ for executable code, references/ for docs pulled into context as needed, and assets/ for output templates and fonts. Best practice keeps the SKILL.md body under 500 lines and references one level deep, with a table of contents on any reference file longer than ~100 lines.

Progressive disclosure: why it stays cheap

The architecture that lets this scale is progressive disclosure. As the docs explain, "This filesystem-based architecture enables progressive disclosure: Claude loads information in stages as needed, rather than consuming context upfront." It runs in three levels with strikingly different token costs.

• Level 1 — Metadata (always loaded): just name and description, preloaded into the system prompt at startup, roughly 100 tokens per skill. An agent can be aware of dozens or 100+ skills for almost nothing.
• Level 2 — Instructions (loaded when triggered): the SKILL.md body, read from the filesystem via bash only when the request matches the description. Target under 5k tokens.
• Level 3+ — Resources (loaded as needed): bundled files and scripts, with a cost the docs list as "effectively unlimited." When Claude runs a bundled script, "the script's code never loads into the context window. Only the script's output… consumes tokens."

The rationale: the context window is, in Anthropic's phrase, "a public good." Because files cost zero tokens until accessed, the material you can bundle is "effectively unbounded" — comprehensive API docs, datasets, examples — with no penalty for what goes unused. And executing deterministic code beats generating it, since "sorting a list via token generation is far more expensive than simply running a sorting algorithm."

How to build one

You need no special tooling. "Claude models understand the Skill format and structure natively," the docs note; "Simply ask Claude to create a Skill and it generates properly structured SKILL.md content." The practical recipe is short.

• Name it well. Use kebab-case, ideally gerund form — processing-pdfs, analyzing-spreadsheets. Avoid vague names like helper, utils, or tools.
• Write the description in third person, covering both what it does and when to use it. This is the single most important authoring decision: "Claude uses it to choose the right Skill from potentially 100+ available Skills."
• Keep the body lean and push detail into reference files and scripts.
• Build evaluations first. The best-practices guide is emphatic — "Create evaluations BEFORE writing extensive documentation" — with a checklist minimum of three evals, tested across Haiku, Sonnet, and Opus.

Anthropic even ships a skill-creator skill that builds, edits, optimizes, and benchmarks other skills.

Where they run

The same SKILL.md folder is portable across four surfaces. The engineering post states it plainly: "Agent Skills are supported today across Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform." The launch announcement frames the payoff as "Build once, use across Claude apps, Claude Code, and API."

• Claude apps (claude.ai): enabled under Settings > Capabilities (code execution required), then Customize > Skills, where custom skills upload as a ZIP. Team and Enterprise Owners must switch Skills on organization-wide first.
• Claude Code: skills live at four scopes — personal (~/.claude/skills/), project (.claude/skills/), plugin, and enterprise — with enterprise overriding personal overriding project. Per the Claude Code docs, custom commands were folded into skills, so .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy.
• The API: skills are managed at the /v1/skills endpoint behind three beta headers — code-execution-2025-08-25, skills-2025-10-02, and files-api-2025-04-14 — and attached via the Messages API container parameter, up to 8 skills per request.
• The Agent SDK is a supported surface for building custom agents; its loading mechanics live in the dedicated SDK docs.

Capabilities differ by surface. The API sandbox has no network access and no runtime package installation; Claude Code gets full local network and filesystem access; claude.ai's network access varies by user and admin settings. Custom skills also do not sync between surfaces.

Examples and use cases

Anthropic ships four pre-built "document" skills — pptx, xlsx, docx, and pdf — which on claude.ai are "already working behind the scenes when you create documents." The public anthropics/skills repo holds 17 example folders, including brand-guidelines, canvas-design, mcp-builder, and skill-creator. Their descriptions model the what-plus-when pattern: canvas-design, for instance, fires "when the user asks to create a poster, piece of art, design, or other static piece."

On the enterprise side, the announcement cites Box turning stored files into branded PowerPoint and Excel output, Notion integrations, and Rakuten using Skills to "streamline our management accounting and finance workflows" — with the kicker, "What once took a day, we can now accomplish in an hour."

Best practices and the security caveat

The recurring advice is discipline: keep skills focused and concise, prefer pre-written utility scripts for deterministic work over regenerating code (they are "more reliable than generated code" and "save tokens"), and signal whether Claude should run a script or read it as reference. The one caveat you cannot wave away is that skills are executable code. The engineering post warns that "malicious skills may introduce vulnerabilities… or direct Claude to exfiltrate data and take unintended actions," and recommends "installing skills only from trusted sources. When installing a skill from a less-trusted source, thoroughly audit it before use." The docs add: treat it like installing software, and watch skills that fetch from external URLs.

That portability is now bigger than Anthropic. On December 18, 2025, the company published Agent Skills as "an open standard for cross-platform portability," documented at agentskills.io, alongside organization-wide management and a partner-built directory. Rivals have since adopted it — OpenAI Codex, Google's Gemini CLI, GitHub Copilot, Cursor, and more — making the humble SKILL.md one of the few formats that travels across competing agents.