AI Agent Skills Explained: How SKILL.md Files Work

AI agent skills are the folders that teach an agent how to do a job

On 22 October 2026, Anthropic donated Agent Skills, the open format it built for Claude Code, to the Agentic AI Foundation (AAIF) under the Linux Foundation, the same body that already holds the Model Context Protocol. By that date more than 70 agent platforms, including ChatGPT, Cursor, GitHub Copilot and VS Code, had adopted the format since Anthropic opened it up in December 2025. For anyone building or buying AI agents, ai agent skills are now one of the two open standards, alongside MCP, that decide how much an agent can do without custom code.

AI agent skills are folders of instructions, scripts and reference files, organized around a required SKILL.md file, that an agent loads only when a task calls for them. The format lets a person or a team package procedural knowledge once and reuse it across any agent that supports the open standard, from Claude to ChatGPT to Cursor.

How AI agent skills work

A skill is, at minimum, a directory containing a SKILL.md file. According to the format's specification at agentskills.io, that file needs YAML frontmatter with two required fields: name (up to 64 characters, lowercase letters, numbers and hyphens only, and it must match the parent directory's name) and description (up to 1,024 characters, explaining what the skill does and when to use it). Four fields are optional: license, compatibility (for environment requirements such as "requires git, docker, jq"), metadata (a free-form key-value map), and an experimental allowed-tools field that pre-approves a space-separated list of tools, written like Bash(git:*) Bash(jq:*) Read.

Anthropic's original 16 October 2025 engineering post, "Equipping agents for the real world with Agent Skills," describes the mechanism behind that frontmatter as progressive disclosure, in three levels:

1. Metadata, about 100 tokens, the name and description of every installed skill, loaded into the system prompt at startup so the agent knows what is available.
2. Instructions, the full SKILL.md body, recommended to stay under 5,000 tokens, loaded only once the agent decides a skill is relevant to the current task.
3. Resources, the files inside a skill's optional scripts/, references/ and assets/ folders, read only as the task actually needs them.

As Anthropic put it in that post, "agents with a filesystem and code execution tools don't need to read the entirety of a skill into their context window when working on a particular task," which is why a skill's total bundled content is effectively unbounded even though only a sliver of it loads for any one job. The scripts/ folder holds executable code (commonly Python, Bash or JavaScript, depending on what the agent supports), references/ holds extra documentation such as a REFERENCE.md or domain-specific files, and assets/ holds templates, images or data files.

Examples

Anthropic's own PDF skill, bundled in its public skills repository, is the example used in its launch post. Claude can already read PDFs, but the skill adds the ability to fill out a form: the SKILL.md references a separate forms.md file with form-filling instructions and a pre-written Python script that extracts form fields, so Claude can run that script as a tool without ever loading the PDF or the script itself into its context window.

The Model Context Protocol's own documentation, in its "Build with Agent Skills" guide for the 2026-07-28 spec revision, ships a reference set of skills for building MCP servers themselves, packaged as the mcp-server-dev plugin. It has three composing skills: build-mcp-server, an entry point that asks what the server connects to, who will use it and what kind of auth it needs, then routes to the other two; build-mcp-app, which adds interactive chat widgets such as pickers and dashboards; and build-mcpb, which packages a local stdio server with its own runtime into a single .mcpb file so a user without Node or Python installed can still run it. Installing the set in Claude Code is two commands:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install mcp-server-dev

When to use a skill, and when to reach for MCP instead

A skill fits a task that needs procedural knowledge an agent does not already have: a specific review checklist, a recurring multi-step workflow, or formatting rules unique to one document type. Anthropic describes writing one as being like "putting together an onboarding guide for a new hire."

A skill is not the right tool for reaching a live API, a database or an external file system. Anthropic's own roadmap in that October 2025 post says it plans to "explore how Skills can complement Model Context Protocol (MCP) servers by teaching agents more complex workflows that involve external tools and software," which as of this writing is still a stated direction rather than a shipped feature. In practice, MCP servers remain the layer that gives an agent tools and data access, and skills remain the layer that tells the agent how to use them well.

Because a skill bundles both instructions and executable code, it also carries a real security surface. Anthropic's guidance is direct: install skills only from sources you trust, and when a skill comes from somewhere less trusted, read its bundled files first, paying attention to its code dependencies and to any instruction that directs the agent to connect to an external network source before you ever run it.

What's new (as of 25 October 2026)

• 22 October 2026: Anthropic donated the Agent Skills name, logo, GitHub organization and the agentskills.io domain to the Agentic AI Foundation (AAIF) under the Linux Foundation, the foundation it co-founded with Block and OpenAI and that already holds the Model Context Protocol. David Soria Parra and Mahesh Murag are the project's Lead Maintainers, with engineers from Anthropic, Google, OpenAI and other companies maintaining the standard as individuals from here.
• By that announcement, more than 1 million skills had been published and nearly 280 million installed, with over 70 agent platforms, including ChatGPT, Cursor, GitHub Copilot and VS Code, having integrated the format since Anthropic published it as an open standard on 18 December 2025.
• The AAIF's proposed next steps for the standard include versioned releases, a formal proposal process and security guidance for people writing and installing skills, following the governance pattern Anthropic already used when it donated MCP to the same foundation.
• The Model Context Protocol's 2026-07-28 documentation now treats Agent Skills as a supported way to build MCP servers, not just a separate format: its mcp-server-dev plugin uses the SKILL.md format to scaffold a new server and pick a deployment path (remote Streamable HTTP, an MCP Bundle, or local stdio) based on how the finished server will be used.

Key takeaways

• AI agent skills are folders built around a required SKILL.md file with name and description fields; everything else, including scripts, references and assets, loads only when the agent decides it needs them. Source: agentskills.io specification.
• Anthropic built the format for Claude Code in October 2025 and published it as an open standard that December; more than 70 agent platforms adopted it within about ten months. Source: Anthropic, 22 October 2026.
• On 22 October 2026, Anthropic donated Agent Skills to the Agentic AI Foundation under the Linux Foundation, the same foundation that holds the Model Context Protocol, putting both major agent-extension standards under one governance body.
• Skills carry procedural instructions; MCP servers carry the tools and data connections. Anthropic has stated it still plans to explore combining the two more directly.
• Because a skill can bundle executable code, Anthropic recommends installing skills only from trusted sources and auditing anything from elsewhere before running it.

FAQ

What is the difference between AI agent skills and MCP servers?

Skills package procedural instructions, scripts and reference files that an agent loads only when a task needs them. MCP servers expose tools, resources and prompts that let an agent call external APIs, databases or files. Anthropic has said the two are meant to complement each other, with skills eventually teaching agents how to use the tools an MCP server provides, though a combined workflow has not shipped yet.

Do I need Claude to use AI agent skills?

No. Anthropic built the format for Claude Code, but it published Agent Skills as an open standard in December 2025, and more than 70 agent platforms, including ChatGPT, Cursor, GitHub Copilot and VS Code, had adopted it by 22 October 2026.

How do I create an AI agent skill?

Create a directory whose name matches the name field inside a SKILL.md file (lowercase letters, numbers and hyphens only, no leading or trailing hyphen), write a description that says what the skill does and when to use it, and put the instructions in the Markdown body below the YAML frontmatter. Keep that file under roughly 500 lines by moving longer reference material into a references/ folder.

Is it safe to install a skill someone else wrote?

Only if it comes from a source you trust. Anthropic's own guidance warns that a skill's bundled instructions and code can direct an agent to take unintended actions or send data somewhere it should not, and recommends auditing any skill from a less-trusted source, including its scripts and any instruction that reaches out to an external network address, before installing it.

AI Agents Listing's skills directory lists the agent skills builders can browse today, alongside the MCP servers and agents that use them.