How Agent Skills Work: SKILL.md, Progressive Loading and How They Differ from MCP
Agent Skills package instructions, scripts and reference files into a folder that an agent loads in stages, so it can keep many skills on hand at a small cost in context. On October 22, 2026 Anthropic donated the open standard to the Agentic AI Foundation. This explainer covers the format, the loading steps, the contrast with MCP and the security caveats.
Checked against the Agent Skills specification at agentskills.io (no version number stated) and the Model Context Protocol specification, revision 2026-07-28
- Loaded at each stage: the name and description, then the instructions
- Loaded only on demand: bundled files and scripts
As of All entries as stated by the specifications and Anthropic
| Attribute | Agent Skills | Model Context Protocol (MCP) | Figure |
|---|---|---|---|
| What it is | A lightweight, open format: a folder with a required SKILL.md file (metadata plus instructions) and optional scripts, references and assets12 |
An open protocol for integrating LLM applications with external data sources and tools3 | Vendor-stated |
| What it carries | Procedural knowledge and context: instructions, workflows, reference material and code the agent can run12 | Contextual information and server features such as prompts, resources and tools3 | Vendor-stated |
| How it reaches the model | Loaded in stages: name and description at startup, the SKILL.md body when a task matches, other files only when needed12 |
A client connects to a server using the protocol's message patterns and transports3 | Vendor-stated |
| Where it runs | As files the agent reads; in Claude, skills sit on a virtual machine with filesystem and bash access, and scripts run there4 | Servers can run locally or as remote servers elsewhere on the internet4 | Vendor-stated |
| Version | The specification page states no version number; Anthropic's proposed roadmap includes versioned releases15 | Revision 2026-07-28 (latest)3 | Vendor-stated |
| Governance | Donated by Anthropic to the Agentic AI Foundation (AAIF) under the Linux Foundation on Oct 22, 2026; maintained by engineers from Anthropic, Google, OpenAI and others as individuals, with David Soria Parra and Mahesh Murag as Lead Maintainers5 | Donated by Anthropic to the AAIF earlier, per Anthropic5 | Vendor-stated |
| Adoption, as stated by Anthropic | More than 70 agent platforms integrated; 1 million skills published and nearly 280 million installed5 | No adoption figure on the specification page we read3 | Vendor-stated |
| Security guidance | Anthropic's docs say to use skills only from trusted sources and to audit every bundled file, since a malicious skill can direct Claude to call tools or run code in ways that don't match its stated purpose4 | The specification has a security and trust-and-safety section with key principles3 | Vendor-stated |
A side-by-side of the open Agent Skills format and MCP, from their own specifications, Anthropic's documentation and Anthropic's announcement. The two are not alternatives: they do different jobs, as the sections below explain. Adoption figures are Anthropic's own and are not independently verified. For MCP in depth, see How the Model Context Protocol Works. Figure labels: how they work.
How it works
A skill is a folder
The format is deliberately plain. A skill is a directory containing at minimum a SKILL.md file, which has YAML frontmatter followed by Markdown instructions; scripts, reference documents and assets can sit alongside it in optional scripts/, references/ and assets/ folders.2 The aim, in the project's words, is to package "procedural knowledge and company-, team-, and user-specific context into portable, version-controlled folders that agents load on demand".1 Anthropic says it developed skills while working on Claude Code, which handled general knowledge work well but "often lacked the procedural knowledge that real business tasks need".5
The frontmatter rules
Only two frontmatter fields are required. The name must be 1 to 64 characters of lowercase letters, numbers and hyphens, may not start or end with a hyphen or contain consecutive hyphens, and must match the parent directory name.2 The description must be 1 to 1,024 characters and should say both what the skill does and when to use it, with keywords that help an agent recognize relevant tasks.2 Optional fields cover a license, a compatibility note (up to 500 characters), free-form metadata and an experimental allowed-tools list of pre-approved tools.2 The description does the routing work: it is the only part of a skill an agent reads before deciding whether to use it.
Progressive disclosure: three stages
Agents load a skill in stages, so a long list of skills doesn't fill the context window. At discovery, the agent loads only each skill's name and description, about 100 tokens per skill. At activation, when a task matches a description, it reads the full SKILL.md body, which the specification recommends keeping under 5,000 tokens and 500 lines. At execution, it loads or runs files from scripts/, references/ and assets/ only when the task calls for them.12 The specification also advises keeping file references one level deep from SKILL.md and splitting long instructions into referenced files.2
Where a skill runs
The format doesn't dictate the runtime; supported script languages depend on the agent, with Python, Bash and JavaScript common.2 In Claude, Anthropic's documentation says skills run in a code execution environment with filesystem and bash access: skills exist as directories on a virtual machine, and Claude reads SKILL.md with bash only when a request matches. A bundled script runs through bash, and "only their output enters context", so deterministic code costs no context to describe.4
Skills and MCP do different jobs
A skill teaches an agent how to do something; MCP connects an application to the external data and tools it can reach. The MCP specification describes the protocol as "a standardized way to connect LLMs with the context they need", defined by a revision such as 2026-07-28.3 Anthropic's own architecture diagram shows both side by side, with skills on the agent's virtual machine and MCP servers, local or remote, equipped alongside.4
What changed on October 22, 2026
Anthropic announced it is donating Agent Skills to the Agentic AI Foundation (AAIF) under the Linux Foundation, which it co-founded with Block and OpenAI in 2025, and which already holds MCP.5 The donation covers the Agent Skills name and logo, the GitHub organization and the agentskills.io domain.5 Engineers from Anthropic, Google, OpenAI and other companies will maintain the standard as individuals; the proposed first roadmap covers versioned releases, a formal proposal process and security guidance for people who write and install skills.5 Anthropic says more than 70 platforms have integrated the standard, including ChatGPT, Cursor, GitHub Copilot and VS Code, and that 1 million skills have been published and nearly 280 million installed; these are Anthropic's figures.5 The AAIF's site lists Agent Skills among its projects.6
The security caveat
Because a skill can bundle code and instructions, it is a way to change what an agent does. Anthropic's documentation says to use skills only from trusted sources, such as ones you wrote yourself or got from Anthropic, because a malicious skill can direct Claude to call tools or run code in ways that don't match its stated purpose, with risks including data exfiltration and unauthorized system access.4 It advises auditing every bundled file for unexpected network calls, file access patterns or operations that don't match the skill's purpose.4 The risk is related to prompt injection, since in both cases the agent acts on text it was given.
Sources
- Agent Skills project, Agent Skills overview, retrieved 2026-10-24.
- Agent Skills project, Specification, retrieved 2026-10-24.
- Model Context Protocol, Specification, version 2026-07-28, retrieved 2026-10-24.
- Anthropic, Agent Skills overview (Claude Platform docs), retrieved 2026-10-24.
- Anthropic, Donating Agent Skills to the Agentic AI Foundation, Oct 22, 2026, retrieved 2026-10-24.
- Agentic AI Foundation, AAIF projects, retrieved 2026-10-24.