An Agent Skill is a folder containing a SKILL.md file — YAML frontmatter with a name and description, then plain Markdown instructions an AI agent loads on demand. Anthropic shipped the format for Claude on October 16, 2025, then published it as an open standard at agentskills.io on December 18, 2025. Microsoft folded it into VS Code and OpenAI added it to Codex within 48 hours, and by mid-2026 the official client showcase lists 40+ adopters — Cursor, Gemini CLI, GitHub Copilot, OpenCode, Goose, JetBrains Junie, Roo Code, and Databricks among them. The same skill folder now works across competing agents the way an MCP server does for tools.
That portability triggered a land rush. An early-2026 ecosystem measurement study (arXiv:2602.08004) counted more than 40,000 publicly listed skills on a single major marketplace by early February 2026 — weeks after the open standard shipped. Growth like that outran security: Snyk's ToxicSkills audit, published the same week, found critical issues in 13.4% of the skills it scanned. This page covers the spec, what actually supports it, and when a skill is the wrong tool.
What is a SKILL.md file?
The specification is deliberately tiny — Simon Willison called it readable in a few minutes. A skill is a directory whose name matches the name field, with optional scripts/, references/, and assets/ subdirectories. The frontmatter has exactly two required fields:
| Field | Required | Constraints |
|---|---|---|
| name | Yes | ≤ 64 chars, lowercase letters/numbers/hyphens, must match the directory name |
| description | Yes | ≤ 1024 chars — what the skill does and when to use it |
| license | No | License name or bundled file reference |
| compatibility | No | ≤ 500 chars — environment requirements, most skills omit it |
| metadata | No | Arbitrary string key-value map (author, version) |
| allowed-tools | No | Space-separated pre-approved tools — experimental, support varies |
---
name: release-notes
description: Drafts release notes from merged PRs since the last tag. Use when
the user asks for release notes, a changelog entry, or a version announcement.
---
1. Run `git log $(git describe --tags --abbrev=0)..HEAD --oneline`.
2. Group commits by conventional-commit type (feat, fix, chore).
3. Write user-facing notes — name the feature, not the commit.
4. Link each entry to its PR. See references/TEMPLATE.md for the format.The body has no format restrictions. The spec's only structural advice: keep SKILL.md under 500 lines and push detail into references/ files the agent reads only when needed. The skills-ref reference library in the agentskills/agentskills repo validates frontmatter and naming.
How does progressive disclosure keep skills cheap?
Skills load in three stages, and the staging is the whole trick. At startup the agent sees only each skill's name and description — roughly 100 tokens per skill. When a task matches a description, the full SKILL.md body loads (the spec recommends staying under 5,000 tokens). Bundled scripts and reference files load only if the instructions call for them. An agent can carry fifty skills for the context cost of one always-on instructions file — which is exactly the problem with stuffing every workflow into AGENTS.md or CLAUDE.md, where every line taxes every request whether it is relevant or not.
The catch: activation depends entirely on the description. A vague description: Helps with PDFs means the agent never pulls the skill in, and you will not get an error — just an agent improvising the workflow you already wrote down. Write descriptions the way you would write a function's docstring for a caller who only reads signatures: what it does, plus the trigger phrases a user would actually say.
Which tools support Agent Skills?
Adoption at launch included Microsoft, OpenAI, Cursor, and GitHub, with partner skills authored by Atlassian, Figma, Canva, Stripe, Notion, and Zapier. The agentskills.io showcase now lists 40+ clients. In Claude Code skills live in .claude/skills/ (project) or ~/.claude/skills/ (personal); OpenCode, Codex CLI, Gemini CLI, Goose, Amp, Kiro, Factory, and VS Code each document their own directory but read the same format. Cursor adopted the standard too — its older rules system still exists alongside it, and Cursor rules and skills covers when to reach for which.
Portability advice from the spec maintainers is blunt: stick to the core fields. Agent-specific frontmatter extensions are the one place implementations diverge, so a skill that uses only name and description runs everywhere; one that leans on allowed-tools may silently lose its permissions hints outside Claude Code. Vercel's skills.sh CLI (launched January 20, 2026) installs a skill once and symlinks it into the directory conventions of 50+ different agents.
Are marketplace skills safe to install?
Treat them like curl | sh from an unmoderated forum. Snyk's ToxicSkills research (February 5, 2026) scanned 3,984 skills from ClawHub and skills.sh: 36% had at least one security flaw, 534 (13.4%) had at least one critical issue, and 76 were confirmed malicious — all 76 carried a malicious code payload, and 91% also used prompt injection. One documented sample hid a base64-obfuscated one-liner that exfiltrated ~/.aws/credentials to an attacker server via curl. Days earlier, Koi Security's audit of 2,857 ClawHub skills (February 1, 2026) had found 341 malicious — 335 of them traced to a single coordinated operation, ClawHavoc — and OWASP stood up an Agentic Skills Top 10 project with malicious skills as its first entry (AST01).
The structural problem is that a skill inherits the full permission set of the agent running it — filesystem, shell, cloud credentials, outbound network — while also steering the agent's reasoning in natural language. That dual surface is what makes skills a sharper supply-chain risk than npm packages, and it is the same class of failure catalogued in how AI agents get compromised. Practical floor: read every line of a third-party skill before installing, including bundled scripts; prefer skills from named vendors over anonymous marketplace uploads; and pin to a reviewed copy instead of auto-updating.
Skills, MCP servers, or AGENTS.md — which one do I want?
| Mechanism | What it carries | Loaded | Reach for it when |
|---|---|---|---|
| Agent Skill | Procedural knowledge — how to do a task | On demand, by description match | A multi-step workflow you repeat but don't need every session |
| MCP server | Live tools and data — things the agent calls | Per session (tool search defers definitions) | The agent needs to query or act on an external system |
| AGENTS.md / CLAUDE.md | Always-on conventions and constraints | Every request | Rules that must never be skipped — style, safety, project layout |
| Slash command | A workflow the human triggers explicitly | On invocation | You want deterministic activation, not description matching |
Skills carry knowledge; MCP carries capability. A skill cannot give the agent access to your issue tracker — that is an MCP server's job, covered in MCP servers for Claude Code — but a skill is the right place for the ten-step procedure describing how your team triages those issues. Both are harness components in the Agent = Model + Harness framing: the model is rented, the skills folder is yours.
When NOT to write a skill
- •The rule applies to every request. "Always use single quotes" belongs in AGENTS.md. A skill the agent must consult constantly defeats progressive disclosure and adds an activation step that can silently fail.
- •Activation must be guaranteed. Description matching is probabilistic. If skipping the procedure is unacceptable — deploy checklists, security gates — use a hook or a slash command instead.
- •You are wrapping a single CLI flag. A skill that says "run prettier" is context overhead with no information. Modern models already know the tool; skills earn their place on multi-step, team-specific procedure.
- •You expect it to be stable infrastructure. OSS Insight's analysis of the 2026 explosion argues the ecosystem is growing without converging: a few repos hold most of the stars, the long tail goes unused, and skills break when the model, the agent framework, or the instruction parsing changes underneath them. Budget for maintenance like any other code.