Agent Skills

Agent Skills is an open specification defining how AI agents package and load procedural knowledge. A skill is a folder containing a SKILL.md file — YAML metadata plus instructions — that an agent activates only when a task calls for it, optionally accompanied by scripts, reference documents and templates. Anthropic released the specification as an independent open standard at agentskills.io on 18 December 2025.^[1][3]

Background

Skills began as an internal Claude feature: rather than lengthening the system prompt with every possible procedure, the model received a short catalogue of skills and fetched the full instructions when a matching task appeared. In December 2025 Anthropic published the format as a specification and reference SDK, following the same playbook that turned its Model Context Protocol into a broadly adopted standard.^[4]

Adoption was unusually fast. Within 48 hours Microsoft had integrated the format into VS Code and OpenAI into ChatGPT and Codex CLI; the reference repository passed 20,000 stars over the same period.^[2] The launch came days after the Linux Foundation announced the Agentic AI Foundation (9 December 2025), established with Anthropic, OpenAI and Block as founding members to steward agent interoperability specs.^[5]

Specification

A skill is a directory with a required SKILL.md file:^[1]

`` skill-name/ ├── SKILL.md # required: metadata + instructions ├── scripts/ # optional: code the agent can run ├── references/ # optional: documentation loaded on demand └── assets/ # optional: templates and other resources `

The frontmatter requires name (max 64 characters, lowercase letters, digits and hyphens, matching the directory name) and description (max 1024 characters, written to help the agent decide when to use the skill). Optional fields cover license, compatibility, arbitrary metadata, and an experimental allowed-tools list of pre-approved tools. The Markdown body carries the instructions with no prescribed structure.[1]

The central design idea is progressive disclosure. At startup the agent loads roughly a hundred tokens of name-and-description metadata for every skill; the full body loads only when the skill activates; supporting files load only when referenced. The specification recommends keeping SKILL.md under 500 lines and under 5,000 tokens, pushing detail into separate files so the context window stays small.[1] A reference validator (skills-ref validate) checks conformance.

Relationship to MCP and Prompts

Skills and Model Context Protocol are complementary rather than competing. MCP standardises how an agent talks to external systems — servers, tools, resources. Skills standardise how a procedure is stored and invoked — the recipe, not the connection. Prompts describe the one-off instruction; a skill is a versioned, shareable directory that can bundle the working code and reference material a prompt can only describe.

Because skills are plain files in a repository, they are reviewable, diffable and distributable through the same channels as source code. That has made skills a natural unit for sharing domain expertise — regulatory checklists, deployment runbooks, format conventions — across teams and, increasingly, across vendors.

>Key Takeaways

• Agent Skills packages agent instructions as SKILL.md` folders with optional scripts and references.
• Anthropic published it as an open standard on 18 December 2025; Microsoft and OpenAI adopted it within days.
• Progressive disclosure keeps metadata small and loads detail only when needed.
• Skills complement MCP: skills carry procedures, MCP carries connections.
• Plain-file skills are reviewable and portable — but they execute code and should be vetted like dependencies.

See Also

• AI Agents
• Agentic AI
• Model Context Protocol
• Prompt Engineering
• Context Engineering
• Prompt Injection
• Anthropic
• Claude Code
• Cursor Code Editor