Agent Skills is the open standard for packaging agent capabilities as filesystem folders. A skill is a directory with a SKILL.md file (YAML frontmatter plus markdown instructions) and optional scripts/, references/, and assets/. Anthropic-originated, governed via agentskills.io, native in Claude Code (plugin marketplace), Claude.ai, and the Claude API. The canonical implementation lives at anthropics/skills — the most-starred AI repository on GitHub at ~131k stars in May 2026.
An Agent Skill is a folder containing, at minimum, a SKILL.md file. The file has YAML frontmatter (a name and a description) followed by markdown instructions that tell an agent how to perform a specific task. Optional sub-directories carry the rest of the skill: scripts/ for executable code, references/ for deeper documentation, assets/ for templates and static resources. That's the entire format.
The thesis is straightforward: most agent capabilities are repeatable procedures. Filling a PDF form. Generating a slide deck with the company brand. Reviewing code against a house style guide. Running a specific test suite. These don't need a live tool server — they need instructions, maybe a few helper scripts, and a way for the agent to find them when relevant. Skills package that bundle as a directory, version it in git, and let any compatible agent load it on demand.
Skills sit alongside MCP and A2A in the agent stack but solve a different problem. MCP is a runtime protocol for letting an agent call tools and read data over JSON-RPC. A2A is a runtime protocol for letting one agent delegate to another. Skills is a static format for shipping reusable instructions and supporting files that the agent reads itself. All three coexist; most production agent systems in 2026 use at least two of them.
The name field (max 64 characters, lowercase alphanumeric and hyphens, must match the parent directory name) and the description field (max 1024 characters, "what it does and when to use it") are the only frontmatter that's required. Optional fields are license, compatibility, metadata, and the experimental allowed-tools. The whole point of keeping the required surface tiny: every skill in a workspace gets its name + description loaded at agent startup, so the agent can match incoming tasks to relevant skills without loading the full body.
A skill is loaded in three tiers. The metadata is cheap and always loaded. The body is loaded only when the agent activates the skill. The supporting files in scripts/, references/, and assets/ are loaded only when the body's instructions point to them. Each tier has a recommended budget — if you stay inside the budgets, hundreds of skills can coexist without burning context.
The name + description from every available skill. Loaded once, kept in context. This is what the agent uses to decide which skill matches a task.
The full markdown instructions. Loaded only when the agent activates the skill. Spec recommends keeping the file under 500 lines and moving deep references out.
Files loaded only when the body's instructions explicitly point to them. references/REFERENCE.md, scripts/extract.py, brand templates, lookup tables.
The directory shape — everything else in a skill hangs off SKILL.md as an orchestrator:
pdf-processing/ ├── SKILL.md # required: frontmatter + markdown ├── scripts/ │ ├── extract.py # text/table extraction │ └── fill_form.py # PDF form filling ├── references/ │ └── REFERENCE.md # field schema, edge cases └── assets/ └── template.pdf # reusable form template
A minimal SKILL.md — just the two required fields and a few lines of instructions:
--- name: pdf-processing description: Extract text and tables from PDFs, fill PDF forms, merge files. Use when handling PDF documents or when the user mentions PDFs, forms, or document extraction. --- # PDF Processing ## When to use - The user uploads or links a PDF file - The user asks to extract data from a form - The user asks to merge or split PDFs ## How to extract text 1. Run `scripts/extract.py <path>` to get the structured output 2. If the PDF is scanned, fall back to OCR (see references/REFERENCE.md) 3. Return tables as Markdown tables, prose as plain text
A SKILL.md with the optional fields — license, environment requirements, custom metadata, and the experimental tool allowlist:
--- name: code-review description: Review a pull request against the house style guide. Use when the user shares a PR link, runs `/review`, or asks for code feedback. license: Apache-2.0 compatibility: Requires git, gh, and access to the internet metadata: author: 2nth.ai version: "1.0" allowed-tools: Bash(git:*) Bash(gh:*) Read --- # Code Review [ instructions ... ]
An agent surface like Claude Code can ship with dozens of skills installed via the plugin marketplace. If every skill loaded its full body at startup, context would be exhausted before the user typed a prompt. By loading only the ~100-token metadata tier upfront and deferring the rest, hundreds of skills can sit in a workspace doing nothing — until one matches a task and the agent pulls in just that body. The format is the budget.
Skills are consumed natively in three Anthropic surfaces today: Claude Code (via the plugin marketplace), Claude.ai (paid plans, with custom upload), and the Claude API (programmatic via the Skills API). The canonical reference set lives at anthropics/skills, organised in four categories. Partner-shipped skill sets are starting to appear — Notion's are the first highlighted by Anthropic.
| Surface | How skills are loaded | Notes |
|---|---|---|
| Claude Code | Plugin marketplace | /plugin marketplace add anthropics/skills then install document-skills or example-skills. |
| Claude.ai | Built-in + custom upload | The repo's example skills are pre-installed on paid plans. Users can upload their own. |
| Claude API | Skills API | Pre-built or upload custom skills programmatically. See the Skills API quickstart. |
| Other agents | Spec-compliant loaders | Any agent runtime that implements the agentskills.io spec can load these folders. |
The anthropics/skills repo is organised in four practical categories — useful both as a catalogue of what's already shipped and as a template library when authoring your own:
| Category | Examples | Use case shape |
|---|---|---|
| Creative & Design | algorithmic-art, canvas-design, theme-factory, slack-gif-creator | Generative output bound by aesthetic / brand constraints. |
| Development & Technical | claude-api, frontend-design, mcp-builder, web-artifacts-builder, webapp-testing, skill-creator | Code authoring, scaffolding, testing, meta-skill creation. |
| Enterprise & Communication | brand-guidelines, internal-comms, doc-coauthoring | Voice / format / policy adherence inside an organisation. |
| Document Skills | docx, pdf, pptx, xlsx | Office-format authoring and extraction. Source-available, not Apache 2.0 — the same skills power Claude.ai's document features in production. |
Most skills in anthropics/skills are Apache 2.0. The four document skills (docx, pdf, pptx, xlsx) are source-available, not open source — Anthropic shares them as a reference for sophisticated production skills but reserves rights. If you fork them into a commercial product, read the headers carefully. The spec at agentskills.io is itself open and vendor-neutral; only specific skills in the example repo carry restricted terms.
"Skill" overlaps with "tool" and "MCP server" in casual conversation, but they solve different problems and the differences are load-bearing once you're building anything real:
| Concern | Skills | MCP | Function-calling tools |
|---|---|---|---|
| Format | Folder + SKILL.md | JSON-RPC server | JSON Schema in a request |
| Lifetime | Static; in git, in a folder | Long-running process, per-session state | Per-call |
| What it carries | Instructions, scripts, templates, references | Live tools, resources, prompts | One callable function |
| Load model | Progressive disclosure | Capability list at handshake | Sent in the prompt |
| Best fit | Repeatable procedures and brand / policy adherence | Live access to data and external systems | Per-call function dispatch |
A common 2026 pattern: a skill named internal-comms contains the company's voice rules and a script scripts/draft.py. The script's logic uses an MCP server (say, mcp-server-slack) to fetch the message thread and an MCP server (say, mcp-server-postgres) to look up the project's internal status. The model that ties it together calls function-calling tools for the leaf operations. Skills frame the procedure, MCP provides the live data, function-calling tools execute the steps.
The consultancy unlock. SA delivery teams routinely build the same artefacts — SARS submissions, BBBEE scorecards, CIPC filings, POPIA assessments, NHBRC documentation — with subtle per-client variations. Each of those is a skill: a folder with the format spec in SKILL.md, the actual templates in assets/, and any client-specific overrides as separate skills that reference the base. Once authored, every agent surface (Claude Code on a delivery laptop, Claude.ai for a partner, the API for an automation) can use them.
POPIA and the data boundary. Skills are static files; they never reach out to a database or an API on their own. That makes them safe to publish in shared repositories — the brand voice, the form templates, the procedure documentation. The bits that touch personal data live behind MCP servers or function-calling tools that the skill references, and those servers stay local. The skill says "use the customer-data MCP server"; the server stays on the SA-hosted machine; only the agent's response crosses the boundary.
Cost & sovereignty. Skills themselves are free — it's a folder format. No per-call cost, no FX exposure, no dependency on a specific cloud. A consultancy can author skills once, version them in a private GitHub repo, and distribute them to client engagements. That separates "where the IP lives" (in the skill folders) from "where the inference runs" (Claude API, local Ollama, hosted Vertex). The skill is the durable asset; the model is the substitutable runtime.