An Agent Skill is a folder with a SKILL.md file that an AI agent loads when a task calls for it. On 2026-10-22 Anthropic announced that it is donating the Agent Skills standard to the Agentic AI Foundation (AAIF), which operates under the Linux Foundation.[1] This guide explains what a skill contains, how an agent loads one without filling its context window, what the donation does and does not change, and what to audit before you install a skill someone else wrote. It builds on how AI agents work and what is the Model Context Protocol.
What a skill is
The project's overview describes Agent Skills as "a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows."[2] At its core a skill is a folder containing a SKILL.md file, with metadata (name and description, at minimum) and instructions that tell the agent how to perform a specific task.[2] The specification shows the layout:[3]
skill-name/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ...A minimal SKILL.md is YAML frontmatter followed by Markdown. This example follows the specification's own optional-fields example:[3]
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
author: example-org
version: "1.0"
---The body after the frontmatter has no format restrictions. The specification recommends step-by-step instructions, examples of inputs and outputs, and common edge cases.[3]
The frontmatter rules
| Field | Required | Constraint in the specification |
|---|---|---|
name | Yes | 1 to 64 characters; lowercase letters, numbers and hyphens; no leading, trailing or consecutive hyphens; must match the parent directory name |
description | Yes | 1 to 1024 characters; should say what the skill does and when to use it |
license | No | A license name or a reference to a bundled license file |
compatibility | No | Up to 500 characters on environment requirements |
metadata | No | Arbitrary string-to-string map |
allowed-tools | No | Space-separated pre-approved tools; marked experimental |
Source: the Agent Skills specification, read 2026-10-23.[3]
The description does the routing work. The specification's own contrast is a good description ("Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.") against a poor one ("Helps with PDFs.").[3] Claude's documentation says the same thing from the runtime side: the description is what Claude matches your request against when deciding whether to trigger the skill.[4]
How an agent loads a skill: progressive disclosure
The reason skills scale is that the agent does not read them all up front. The specification describes three stages:[3]
- Metadata (about 100 tokens). The
nameanddescriptionof every installed skill are loaded at startup. - Instructions (under 5,000 tokens recommended). The full
SKILL.mdbody is read when the skill is activated. - Resources (as needed). Files in
scripts/,references/andassets/are loaded only when required.
Claude's documentation gives the same three levels and adds a detail about scripts: when a skill's instructions mention an executable script, Claude runs it through bash and only the output enters the context, not the script's code.[4] The specification also advises keeping SKILL.md under 500 lines and file references one level deep.[3]
Our interpretation: this makes a skill different from a long system prompt in one practical way. An installed but unused skill costs roughly its description, so the real limit is how many descriptions the agent can tell apart, not how many tokens of instructions you have written. The documentation does not publish a limit on that, and we have not tested one. For the broader problem of what stays in a window, see AI agent memory and long context windows.
What the October 2026 donation changes
According to Anthropic's announcement, the donation covers the Agent Skills standard, its name and logo, the GitHub organization and the agentskills.io domain.[1] Several facts from that page matter:
- Home. AAIF is described as a neutral home for the standard. Anthropic co-founded AAIF with Block and OpenAI and had previously donated MCP to it.[1] The Linux Foundation's December 2025 announcement lists MCP, Block's goose and OpenAI's AGENTS.md as the founding projects.[5]
- Maintainers. Engineers from Anthropic, Google, OpenAI and other companies will maintain the standard as individuals, with David Soria Parra and Mahesh Murag as Lead Maintainers.[1]
- Roadmap. The proposed roadmap is versioned releases, a formal proposal process and security guidance for people who write and install skills.[1]
- Adoption. Anthropic reports more than 70 agent platforms, including ChatGPT, Cursor, GitHub Copilot and VS Code, have integrated the standard since its December 2025 publication, and cites 1 million published skills and nearly 280 million installs.[1] Those are Anthropic's figures; we could not check them against an independent count.
- Membership is optional. People can use or contribute to the standard without joining AAIF.[1]
What it does not change: the file format described above is unchanged by the announcement, and nothing on the pages we read says it will be. The roadmap items are described as proposed, so versioning and the proposal process are plans, not shipped features.
Portable format, non-portable runtime
A skill that validates against the specification can still behave differently in different products. Claude's documentation is explicit about this for its own surfaces:[4]
| Surface | Network access | Sharing |
|---|---|---|
| Claude API | None; no runtime package installation | Workspace-wide |
| Claude Code | Full, same as any program on the user's computer | Personal (~/.claude/skills/) or project (.claude/skills/) |
| claude.ai | Varies by user and admin settings | Individual user only |
Source: Claude Platform documentation, read 2026-10-23.[4] Custom skills also do not sync across these surfaces; each must be uploaded or installed separately.[4]
Naming is a small example of the gap. Claude's documentation adds rules the open specification does not list: names cannot contain XML tags or the reserved words "anthropic" and "claude".[4] If you want a skill to travel between products, validate it against the specification (the project provides a skills-ref validate command[3]) and then against each product's own rules.
Security: a skill is a supply chain
Claude's documentation states the risk plainly: use skills only from trusted sources, because a malicious skill can direct Claude to call tools or run code in ways that do not match its stated purpose, and depending on access this could lead to data exfiltration or unauthorized system access.[4] Its audit advice is specific:[4]
- Review every bundled file:
SKILL.md, scripts, images and other resources. - Look for unexpected network calls, file access patterns and operations that do not match the stated purpose.
- Be wary of skills that fetch external content, since fetched text can carry instructions and even trustworthy skills can change if their dependencies do.
- Take extra care before putting skills into production systems with sensitive data.
The practical trade-off is that the same property that makes skills useful, bundled executable code the agent runs on your behalf, is what makes a third-party skill risky. The allowed-tools field is experimental and its support varies between implementations,[3] so do not treat it as a security boundary. This is the prompt-injection and tool-misuse surface covered in how AI agents work, and how to secure them, applied to files you install rather than text you retrieve.
Anthropic's announcement names security guidance for skill authors and installers as part of the proposed roadmap.[1] Until that exists, a reasonable policy for a team is to pin skills in version control, review diffs when they change, and install nothing from a marketplace listing you have not read.
What to do this week
- Inventory. List the skills your agents can currently load and where each came from.
- Audit third-party ones against the checklist above, including scripts.
- Write descriptions as routing rules. Say what the skill does and when to use it, with the keywords a user would actually type.
- Keep bodies short. Under 500 lines, with detail pushed into
references/. - Test where it runs. Check network, package and sharing behaviour in each product you target.
What remains uncertain
We did not read the AAIF governance charter, the first versioned specification (none is referenced yet), or any independent measurement of skill adoption. AAIF's own site, read 2026-10-23, described the foundation only briefly and did not mention Agent Skills, so the announcement on Anthropic's site is our only primary source for the donation terms.
