Agent Skills
Last reviewed
Jun 3, 2026
Sources
8 citations
Review status
Source-backed
Revision
v1 · 1,567 words
Improve this article
Add missing citations, update stale details, or suggest a clearer explanation.
Suggest edit
CtrlK
Last reviewed
Jun 3, 2026
Sources
8 citations
Review status
Source-backed
Revision
v1 · 1,567 words
Add missing citations, update stale details, or suggest a clearer explanation.
Agent Skills are a lightweight, open format for extending AI agents with specialized knowledge and workflows. A skill is a folder containing a single SKILL.md file plus optional scripts, reference documents, and assets. The SKILL.md file holds a short block of metadata and a set of plain-language instructions that tell an agent how to perform a particular task, from filling PDF forms to following a company's brand guidelines. The format was created by Anthropic, first shipped inside Claude products in October 2025, and then released as a cross-vendor open standard in December 2025. Within roughly two months it had been adopted by more than thirty competing coding agents and developer tools, making it one of the fastest-spreading interoperability standards in the agent ecosystem [1][2][6].
The basic idea is to keep procedural knowledge outside the model's weights. Instead of retraining a model every time it needs to learn a new workflow, a skill packages that workflow as a versioned folder the agent reads on demand. This makes capabilities portable: a skill authored once can run on any compatible agent, and a team can store its conventions in a Git repository where every developer picks them up regardless of which tool they prefer [3][6].
Every skill lives in its own directory, and the only mandatory file is SKILL.md. The file begins with YAML frontmatter followed by Markdown instructions. The specification published at agentskills.io defines a small set of fields [3]:
| Field | Required | Constraints |
|---|---|---|
name | Yes | Max 64 characters; lowercase letters, numbers, and hyphens only; no leading, trailing, or consecutive hyphens; must match the parent directory name |
description | Yes | Max 1024 characters; describes what the skill does and when to use it |
license | No | License name or a reference to a bundled license file |
compatibility | No | Max 500 characters; notes environment needs such as required packages or network access |
metadata | No | Arbitrary key-value map for properties the spec does not define |
allowed-tools | No | Space-separated list of pre-approved tools; marked experimental, and support varies between agents |
A minimal skill needs only the two required fields. The Markdown body below the frontmatter has no format restrictions; authors are encouraged to include step-by-step instructions, example inputs and outputs, and common edge cases. The spec recommends keeping the body under about 500 lines and moving longer reference material into separate files [3].
Alongside SKILL.md, a skill can bundle three conventional folders: scripts/ for executable code the agent can run, references/ for documentation it can read when needed, and assets/ for templates, images, or data files. Files are referenced by relative path from the skill root. A typical layout looks like this:
pdf-processing/
SKILL.md # required: metadata + instructions
scripts/ # optional: executable code
references/ # optional: documentation
assets/ # optional: templates, resources
The mechanism that makes skills practical is progressive disclosure, which loads detail in three stages so that an agent can keep many skills available without flooding its context window [1][3]:
name and description of every installed skill into its system prompt, roughly 100 tokens per skill. This is just enough for the model to know when a skill might be relevant.SKILL.md body into context. The spec recommends keeping this under about 5,000 tokens.The payoff is that an agent can carry dozens of skills at a near-zero baseline cost, because the heavy material stays on disk until a specific task pulls it in. This design is a direct answer to the context-window pressure that builds up when developers try to stuff every possible instruction into a single system prompt.
Agent Skills are frequently compared to the Model Context Protocol (MCP), another open standard that Anthropic introduced in 2024. The two are complementary rather than competing. MCP is a wire protocol that connects an agent to external tools, data sources, and services; it answers the question "what can I access?" Skills are a packaging format for procedural knowledge; they answer "how should I work?" In Anthropic's framing, skills "complement MCP servers by teaching agents more complex workflows that involve external tools and software" [1]. A skill can describe a multi-step process that calls several MCP tools in sequence, while MCP handles the actual connections. The survey literature treats the pair as adjacent layers of the same agent stack [4][5].
Anthropic shipped Agent Skills across its own products first. Skills run in the Claude apps, in Claude Code, in the Claude Agent SDK, and on the Claude Developer Platform [1]. Anthropic also published a public repository, anthropics/skills, containing the specification, a skill template, and example skills spanning document creation (docx, pdf, pptx, xlsx), development tasks, and design work. Most of the repository is licensed under Apache 2.0, though the document-creation skills are shared as source-available reference implementations rather than open source [2].
On December 18, 2025, Anthropic republished the format as an open standard for cross-platform portability, with a dedicated specification site at agentskills.io and a community repository for discussion and contributions [1][3][6]. Adoption was unusually fast. Reporting at the time noted that within 48 hours Microsoft had integrated the format into Visual Studio Code and OpenAI had added it to both ChatGPT and its Codex CLI, while the open-standard repository drew roughly 20,000 GitHub stars in the same window [6][7]. Partner-built skills from Canva, Stripe, Notion, and Zapier were available around launch [8].
By March 2026, around 32 tools from competing companies read the same SKILL.md files from the same directory structure [6]. The published client list includes Google's Gemini CLI, JetBrains' Junie, AWS's Kiro, Block's Goose, Sourcegraph's Amp, Cursor, GitHub Copilot, Snowflake's Cortex Code, Databricks Genie Code, ByteDance's TRAE, Mistral's Vibe, and the Spring AI framework, among others [3]. Because the format is just files in a folder, a skill written for one agent can usually be copied into another agent's skills directory and run without modification [6].
The community ecosystem grew quickly. A February 2026 data-driven study by George Ling, Shanshan Zhong, and Richard Huang analyzed 40,285 publicly listed skills from a major marketplace and found that skill content is heavily concentrated in software-engineering workflows, with widespread overlap between skills aiming at the same intent and a pronounced supply-demand imbalance across categories [5].
Letting an agent read instructions and execute scripts from a downloaded folder carries obvious risks. Anthropic's own guidance is blunt: install skills only from trusted sources, and thoroughly audit anything else, paying particular attention to bundled scripts, code dependencies, and any instruction that tells the agent to reach out to external network sources [1]. Skills can carry prompt-injection payloads, perform state-changing or system-level actions, or quietly exfiltrate data, and the allowed-tools field is one early attempt to constrain what a skill is permitted to do.
Empirical work has started to quantify the problem. A February 2026 survey by Renjun Xu and Yang Yan reported that 26.1% of community-contributed skills contained vulnerabilities, and proposed a Skill Trust and Lifecycle Governance Framework built around a four-tier, gate-based permission model for managing those risks [4]. The data-driven analysis by Ling and colleagues reached a similar conclusion, flagging non-trivial safety risks among skills that can change system state [5]. These findings echo the broader security concern around agent extensibility: every mechanism that makes an agent easier to extend also widens its attack surface.
Agent Skills matter because they decouple capability from model training. New behaviors can be added, audited, versioned, and shared as ordinary files, which suits enterprise workflows where teams want consistent, reviewable procedures rather than opaque model updates. The standard also fits a now-familiar pattern: Anthropic introduced a format inside its own products, opened it, and watched rivals adopt it, much as it did with MCP. Whether skills settle into a durable industry baseline or fragment into incompatible dialects will depend on how the governance and security questions are resolved, since the same portability that drove adoption is also what lets an untrusted folder run on dozens of different agents.