A general-purpose model knows a lot, but it does not know your team's release checklist, your database migration rules or the exact order of steps a workflow needs. Agent Skills are one answer to that gap. A skill is a folder with a SKILL.md file of instructions, plus optional scripts, reference files and assets, that an agent loads only when a task calls for it.
Anthropic introduced Agent Skills in its October 16, 2025 engineering post, which compares building a skill to "putting together an onboarding guide for a new hire." Anthropic later published the format as an open standard, and the survey by Xu and Yan (2026) describes skills as "composable packages of instructions, code, and resources that agents load on demand."
The Agent Skills format is no longer a single-vendor project: in October 2026, the Agentic AI Foundation, which already hosts MCP, took Agent Skills on as one of four new projects.
This explainer covers how a skill is laid out, how progressive disclosure keeps context small, what research says about why skills help, how skills relate to the Model Context Protocol (MCP), and the security risks of installing skills from other people.
To write your own, see our step-by-step guide to writing a SKILL.md, which covers names, descriptions that trigger, where each tool looks for skills and how to test them.
Skills sit next to three older ways of giving an agent know-how, and each has limits:
- A long system prompt holds every instruction all the time, whether or not the task needs it.
- A tool or function call gives the agent one action at a time. It does not say in which order to call tools or what to do when one fails.
- Retrieval (RAG) adds passages of text to the context. Jiang et al. (2026), covered below, found that skills mostly help by stabilizing what the agent does, not by adding missing facts.
Progressive disclosure: three levels of loading
Anthropic calls progressive disclosure "the core design principle that makes Agent Skills flexible and scalable." The agent does not read every skill in full at the start. It loads more detail only as the task needs it. The Agent Skills specification gives three levels.
Level 1: metadata in the system prompt
At startup, the agent pre-loads the name and description of every installed skill into its system prompt, Anthropic says. The specification puts this metadata at about 100 tokens per skill. Only two frontmatter fields are required: name (up to 64 characters, lowercase letters, numbers and hyphens, matching the folder name) and description (up to 1,024 characters, saying what the skill does and when to use it). Optional fields are license, compatibility, metadata and the experimental allowed-tools.
---
name: database-migration-validator
description: Validates PostgreSQL schema migrations, checks for locking hazards, and runs dry-run queries against a staging replica. Use when the user asks to run or validate a database migration or schema change.
metadata:
version: "1.2.0"
---The description does the work that a trigger list would do in other systems. Anthropic tells skill authors to "pay special attention to the name and description of your skill," because Claude uses them to decide whether to load the skill.
Level 2: the SKILL.md body
When the agent decides a skill fits the task, it reads the full SKILL.md into context. In Anthropic's example, Claude does this by running a Bash tool to read the file. The specification sets no format rules for the body. It recommends step-by-step instructions, examples of inputs and outputs, and common edge cases, and it recommends keeping the body under 5,000 tokens and the file under 500 lines.
For an operations skill, a body might include, for example:
- Requirements: the command-line tools, environment variables and permissions the task needs.
- Numbered steps: the exact commands and flags, in order.
- Known failures: what to do for common error codes and timeouts.
- Checks: what the agent must confirm before it calls the task done.
Level 3: files loaded on demand
When a skill needs more than one file can hold, SKILL.md points to other files in the skill folder by relative path. The specification names three optional folders: scripts/ for executable code, references/ for extra documentation, and assets/ for templates and data files. It says to keep references one level deep from SKILL.md.
Anthropic's PDF skill is the reference example. Its SKILL.md refers to two extra files, reference.md and forms.md. The form-filling instructions sit in forms.md, so the core file stays lean and Claude reads forms.md only when it fills out a form.
database-migration-validator/
├── SKILL.md # Level 2: core instructions
├── scripts/
│ └── lock_analyzer.py # Run by the agent, not read into context
├── references/
│ └── postgres_locks.md # Level 3: loaded on demand
└── assets/
└── migration_report.md # Level 3: output templateWhy skills help: procedural anchoring
A study by researchers at Princeton, UC San Diego, Stanford, USC and Johns Hopkins, Jiang et al. (2026), asks when skills help and where they fail. The authors normalized 8,135 trial records from controlled experiments across several benchmarks, agent harnesses and models, then open-coded 240 sampled trajectories into a taxonomy of skill-use modes.
Their main findings, in the paper's terms:
- Skills work "when noisy trajectories become procedural anchors that stabilize execution."
- Procedural anchoring accounts for 65.7% of skill cases, against 4.5% for explicit knowledge injection. The authors conclude that skills "stabilize action rather than inject missing facts."
- In matched comparisons, skills beat Workflow Memory (the same past trajectories distilled into a procedural memory instead of a SKILL.md) by 6.06 points.
- Retrieval is a separate problem. As the pool of available skills grows from 5 to 100, the precision of the skills agents actually use falls from 29.6% to 3.3%.
- Skills fail "under brittle assumptions, incompatible contexts, or insufficient adaptation."
The retrieval result matters for teams with large skill libraries. Adding more skills does not help if the agent cannot pick the right one, which puts weight on clear, specific descriptions.
Compared with plain documentation or retrieved text, a skill differs in a few ways:
- How it arrives: retrieval adds passages by text similarity. A skill is loaded when the agent judges, from its description, that the task matches.
- What it says: API documentation describes what exists. A skill body gives steps, in order.
- Failure handling: the specification recommends that a skill cover common edge cases, so recovery steps can be written down rather than guessed.
- Context cost: until a skill is activated, only its metadata sits in context.
Bundled scripts and the MCP boundary
Some jobs are a poor fit for token generation. Anthropic's example: "sorting a list via token generation is far more expensive than simply running a sorting algorithm." It adds that "many applications require the deterministic reliability that only code can provide." Skills can bundle scripts for this. Supported languages depend on the agent; the specification lists Python, Bash and JavaScript as common options.
# skills/git-release-manager/scripts/validate_semver.py
import sys, re
def validate(version_str):
pattern = r"^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
return bool(re.match(pattern, version_str.strip()))
if __name__ == "__main__":
if len(sys.argv) < 2 or not validate(sys.argv[1]):
sys.exit(1)
sys.exit(0)Instead of checking a version string in its reasoning, the agent runs the script and reads the exit code:
python3 skills/git-release-manager/scripts/validate_semver.py "v2.1.4-rc.1"In Anthropic's PDF example, a bundled Python script extracts all form fields, and Claude can run it "without loading either the script or the PDF into context." Anthropic notes that because code is deterministic, the workflow is "consistent and repeatable."
Skills vs. MCP
Skills and the Model Context Protocol (MCP) do different jobs. Xu and Yan put it this way: skills supply "the 'what to do'" and MCP supplies "the 'how to connect.'"
- MCP is the connection layer. It uses JSON-RPC messages between a client in the agent's host and servers that expose tools, resources and prompts from outside systems such as databases or GitHub. Our MCP architecture explainer covers the protocol in detail.
- A skill is the procedure layer. It can tell the agent which MCP tools to call, in what order, and what to do when one returns an error. Anthropic says it will explore how skills "can complement Model Context Protocol (MCP) servers by teaching agents more complex workflows that involve external tools and software."
+-------------------------------------------------------------+
| Agent Reasoning Loop |
+-------------------------------------------------------------+
|
| Reads skill instructions
v
+-------------------------------------------------------------+
| Agent Skill Layer |
| - SKILL.md (steps and edge cases) |
| - Bundled scripts (deterministic work) |
| - References and assets (loaded on demand) |
+-------------------------------------------------------------+
|
| Calls MCP tools
v
+-------------------------------------------------------------+
| Model Context Protocol (MCP) Client |
| - Tool discovery and calls (JSON-RPC) |
| - Transport (stdio / Streamable HTTP) |
+-------------------------------------------------------------+
|
+---------------------+---------------------+
| |
v v
+-----------------------+ +-----------------------+
| Database MCP Server | | GitHub MCP Server |
+-----------------------+ +-----------------------+Security risks and governance
Skills mix natural-language instructions with code that the agent runs, so a bad skill can do real harm. Anthropic warns that "malicious skills may introduce vulnerabilities in the environment where they're used or direct Claude to exfiltrate data and take unintended actions."
What the studies found
Xu and Yan summarize three studies on skill security:
- Prompt injection: Schmotz et al. (2025) showed that malicious instructions in long SKILL.md files and referenced scripts can exfiltrate data such as internal files or passwords. They also showed that a benign approval with a "Don't ask again" option in a popular coding agent can carry over to related harmful actions.
- Vulnerabilities at scale: a study that analyzed 31,132 skills from two marketplaces found that 26.1% contain at least one vulnerability. Data exfiltration showed up in 13.3% and privilege escalation in 11.8%. Skills that bundle scripts were 2.12 times more likely to have a vulnerability than instruction-only skills.
- Confirmed malicious skills: a follow-up study behaviorally checked 98,380 skills and confirmed 157 as malicious. One actor accounted for 54.1% of the confirmed cases.
The same risk shows up outside skills: a planted instruction file can steer a coding agent, as in the AGENTS.md attack on Codex.
What to do about it
Anthropic's advice is to install skills only from trusted sources. For a less-trusted skill, it says to read every bundled file first, paying attention to code dependencies, bundled scripts and images, and any instruction to connect to untrusted network sources.
Xu and Yan go further and propose a Skill Trust and Lifecycle Governance Framework. It is a proposal, not a shipped product:
- Four gates: static analysis (G1), an LLM check that the instructions match the skill's stated purpose (G2), a run in a behavioral sandbox (G3), and a check of a declared permission manifest against observed behavior (G4).
- Four trust tiers: an unvetted community skill (T1) gets instructions-only access, and a vendor-certified skill (T4) gets full capabilities. T1 and T2 skills never get script execution.
- Ongoing monitoring: unexpected tool calls or permission probes lead to demotion or removal, and a clean record can lead to promotion.
Agents that write their own skills
Anthropic says it hopes to let agents "create, edit, and evaluate Skills on their own." Research systems already learn skills. Xu and Yan list SAGE, which uses reinforcement learning with a skill library and reaches 60.7% Scenario Goal Completion on AppWorld, 8.9 points above baseline GRPO, with 59% fewer generated tokens. They also list SEAgent, which explores software on its own and raised success on five new software environments in OSWorld from 11.3% to 34.5%.
Jiang et al. found that "exact ground-truth invocation is neither sufficient nor necessary" for success, and that skills fail under brittle assumptions. A skill an agent writes for itself needs the same review as one a person writes.
Sources
- Agent Skills for Large Language Models: Architecture, Acquisition, Security, and the Path Forward (Xu and Yan, arXiv:2602.12430)
- Equipping agents for the real world with Agent Skills (Anthropic Engineering, October 16, 2025)
- Demystifying Agent Skills: Why They Work, Until They Don't (Jiang et al., arXiv:2608.14036)
- Agent Skills specification
- Agent Skills overview
- Model Context Protocol
