Every team that leans on an AI assistant eventually builds the same artifact by accident: a 4,000-word block of instructions — brand voice, the exact way finance wants a spreadsheet formatted, the six steps for filling out that one government PDF — pasted into the top of every session. It works, sort of. It also spends context on every turn whether the task needs it or not, and once the block grows past what fits comfortably, the model starts skating over the middle of it.

Skills, which Anthropic released across its products in mid-October, are the structural fix for that habit. The pitch sounds modest — "a folder Claude can load when it needs to" — but the mechanism underneath is the interesting part, and it changes how you should think about giving a model expertise.

A Skill is a folder, not a plugin

At its simplest, a Skill is a directory containing a SKILL.md file, plus whatever reference documents and scripts that file wants to bring along. There is nothing to compile and no API to register against. A realistic one looks like this:

pdf-forms/
├── SKILL.md          # metadata + core instructions
├── reference.md      # general PDF notes, loaded if needed
├── forms.md          # form-filling steps, loaded only when relevant
└── fill_form.py      # extracts form fields; run, never read into context

The SKILL.md file must open with YAML frontmatter carrying two required fields, name and description:

---
name: pdf-forms
description: Fill, inspect, and flatten fillable PDFs. Use when the user
  needs to complete a PDF form or pull out its field names.
---

# Filling PDF forms

To discover a form's fields, run `fill_form.py --inspect <file>`.
For layout conventions and edge cases, see reference.md; for the
step-by-step fill procedure, see forms.md.

That is the entire authoring surface. The power is in what the runtime does with it.

Progressive disclosure is demand-paging for instructions

Here is the design principle worth internalizing. Claude does not read your whole Skill up front. It reveals itself in stages:

At startup, only the name and description of every installed Skill get preloaded into the system prompt. One line each — cheap enough to have hundreds sitting there.
When a task matches a description, Claude loads the body of that SKILL.md.
The referenced files — reference.md, forms.md, and any bundled scripts — load only when the work actually reaches them.

If you have written an operating system, this is virtual memory. The description is the page-table entry; the body and its files are pages the model faults in the moment it touches them. Because nothing beyond that one-line description costs you until it is used, the amount of expertise you can attach is, in Anthropic's words, "effectively unbounded." You are no longer rationing a context budget across every possible instruction — you are indexing them and paying only for the ones a given task pulls in.

The sharpest idea is running code you never read

The PDF example ships a pre-written Python script that reads a file and extracts every form field. The detail that matters: Claude runs that script without loading either the script or the PDF into its context. It sees the output, not the source.

Sit with that for a second, because it draws a line most prompt-stuffing never does. Anything deterministic — parsing, formatting, validating, arithmetic on a spreadsheet — is more reliable as code than as tokens a model generates and hopes are right, and executing it costs no context at all. Skills let you place that boundary deliberately: prose where judgment lives, a script where correctness is mechanical. The Skills Anthropic built for Office files lean on exactly this, generating real .xlsx, .docx, and .pptx with formulas and layouts intact rather than narrating what a document should contain.

Same folder, everywhere Claude runs

The format is portable by design. The same directory works in the Claude apps (Pro, Max, Team, and Enterprise), in Claude Code, on the API, and through the Agent SDK.

In Claude Code, drop the folder in ~/.claude/skills, or install from the anthropics/skills marketplace. Because it is just files, you check it into version control and the whole team inherits it.
On the API, Skills ride along in Messages requests behind the code-execution beta, with a /v1/skills endpoint to manage them programmatically.

Skills also compose. Claude decides which ones a task needs and coordinates them, so a "house brand voice" Skill and a "build a deck" Skill combine on a single request without you wiring anything between them.

The obvious caveat, stated plainly

This feature gives Claude access to execute code. While powerful, it means being mindful about which skills you use—stick to trusted sources to keep your data safe.

A Skill is executable code plus instructions that run with your permissions. A folder from a stranger is the same trust decision as piping a script from the internet straight into your shell. Treat it that way: read the scripts before you install, and prefer Skills you or your organization wrote.

The takeaway

The practical shift is that "prompt engineering" starts to look more like packaging. Stop maintaining a mega-prompt you paste everywhere; start maintaining a directory. Take one workflow you re-explain constantly — the report format, the deploy checklist, the form — and write its SKILL.md. Then spend your effort where it pays: sharpen the description until Claude reaches for the Skill at exactly the right moment, because that single line is the whole activation contract. Move the deterministic parts into a script the model runs instead of narrates.

Three files, three jobs: the description does retrieval, the body does instruction, the script does computation. Keeping each job in the right place is the actual skill of writing a Skill.

Sources: Equip agents with skills (Anthropic) · Equipping agents for the real world with Agent Skills (Anthropic Engineering)