# Agent Skills

> Source: https://aiwiki.ai/wiki/agent_skills
> Updated: 2026-06-03
> Categories: AI Agents, Anthropic, Developer Tools
> From AI Wiki (https://aiwiki.ai), a free encyclopedia of artificial intelligence. Quote with attribution.

**Agent Skills** are a lightweight, open format for extending [AI agents](/wiki/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](/wiki/anthropic), first shipped inside [Claude](/wiki/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].

## The SKILL.md format

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
```

## How skills load: progressive disclosure

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]:

1. **Discovery.** At startup the agent reads only the `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.
2. **Activation.** When a task matches a skill's description, the agent reads the full `SKILL.md` body into context. The spec recommends keeping this under about 5,000 tokens.
3. **Execution.** The agent follows the instructions, loading bundled files or running scripts only if and when the task calls for them.

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.

## Relationship to the Model Context Protocol

Agent Skills are frequently compared to the [Model Context Protocol](/wiki/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].

## Where skills work

Anthropic shipped Agent Skills across its own products first. Skills run in the [Claude](/wiki/claude_ai) apps, in [Claude Code](/wiki/claude_code), in the [Claude Agent SDK](/wiki/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].

## Open standard and ecosystem

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].

## Security and governance

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.

## Significance

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.

## References

1. Anthropic. "Equipping agents for the real world with Agent Skills." Anthropic Engineering, October 16, 2025 (updated December 18, 2025). https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
2. Anthropic. "anthropics/skills" repository (Agent Skills specification and example skills). GitHub. https://github.com/anthropics/skills
3. Agent Skills. "Overview" and "Specification." agentskills.io. https://agentskills.io/home and https://agentskills.io/specification
4. Xu, Renjun; Yan, Yang. "Agent Skills for Large Language Models: Architecture, Acquisition, Security, and the Path Forward." arXiv:2602.12430, February 2026. https://arxiv.org/abs/2602.12430
5. Ling, George; Zhong, Shanshan; Huang, Richard. "Agent Skills: A Data-Driven Analysis of Claude Skills for Extending Large Language Model Functionality." arXiv:2602.08004, February 8, 2026. https://arxiv.org/abs/2602.08004
6. paperclipped. "Agent Skills Open Standard Explained: SKILL.md Specification Adopted by Claude Code, Codex, Cursor and 32 Tools." 2026. https://www.paperclipped.de/en/blog/agent-skills-open-standard-interoperability/
7. The New Stack. "Agent Skills: Anthropic's Next Bid to Define AI Standards." 2025. https://thenewstack.io/agent-skills-anthropics-next-bid-to-define-ai-standards/
8. Unite.AI. "Anthropic Opens Agent Skills Standard, Continuing Its Pattern of Building Industry Infrastructure." December 2025. https://www.unite.ai/anthropic-opens-agent-skills-standard-continuing-its-pattern-of-building-industry-infrastructure/