Table of Contents
What Is Agent Skills? The SKILL.md Standard for AI Agents, Explained
Every team that wired a coding agent into its stack this year has hit the same wall: the agent is smart in general and useless on your specific workflow until someone writes the same onboarding paragraph into a system prompt, again, for the third tool this quarter. On October 22, 2026, Anthropic closed one path out of that problem for good. It handed Agent Skills, the folder-and-markdown format it built for exactly this job, to the Agentic AI Foundation (AAIF), the Linux Foundation fund that already runs MCP, per Anthropic's newsroom post. No single vendor owns the spec anymore.
Here is what that actually changes for you, how a skill is built, and where the format still has sharp edges.
A skill is a folder, not a feature
A skill is a directory with one required file, SKILL.md, plus whatever scripts or reference docs the task needs, per the agentskills.io specification. The folder name and the name field in the frontmatter must match. Here is the smallest valid one, adapted from the official quickstart:
---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.) or generate a random dice roll.
---
To roll a die, run a command that generates a random number from 1 to the
given number of sides:
echo $((RANDOM % <sides> + 1))
Replace `<sides>` with the number on the die (6 for a standard die, 20 for a d20).That is the whole mechanism. name and description load into every agent's context at session start, a few dozen tokens each. The agent only reads the markdown body, the part that actually tells it what to do, once your request matches the description. Anthropic calls this progressive disclosure, and it is the one design choice that makes 1,000 installed skills cheaper on context than 10 verbose system prompts, per Anthropic's engineering writeup.
For anything past a one-liner, the folder grows three optional siblings, per the spec: scripts/ for code the agent can execute instead of reasoning through a task by hand, references/ for documentation too long to put in the body, and assets/ for templates and files the skill hands back to the user.
pdf-processing/
SKILL.md # required: name + description + instructions
scripts/ # extract.py, fill_form.py (code, not prose)
references/ # field-mapping.md (loaded only on demand)
assets/ # cover-letter-template.docxWho actually runs this now
AAIF predates this week's news by ten months. Anthropic, Block, and OpenAI founded it in December 2025 by donating MCP, AGENTS.md, and Block's goose framework, respectively. What changed on October 22 is the fourth founding-style contribution: Agent Skills joins a now-10-project portfolio that also includes the Agent2Agent protocol, Agent Router, and agentgateway, per the Linux Foundation's press release. Anthropic donated the Agent Skills name, logo, GitHub organization, and the agentskills.io domain itself, not just a promise to behave neutrally. David Soria Parra and Mahesh Murag, both Anthropic engineers, stay on as lead maintainers, but they now answer to a cross-company governance process instead of a product roadmap meeting.
That distinction matters more than it sounds. MCP went through the identical move in December 2025 and did not fragment, it absorbed Google's and Microsoft's engineering input and kept shipping. The honest read is that a donation to AAIF is now the standard playbook for a company that wants its format adopted by competitors without looking like it is giving up control. It worked once already.
Where it already runs
The numbers are the part worth sitting with. Since the open-standard launch in December 2025, more than 70 agent platforms have integrated Agent Skills, including ChatGPT, Cursor, GitHub Copilot, and VS Code, and the community has published roughly 1 million skills with close to 280 million installs, per Anthropic's donation announcement. Microsoft shipped native support inside VS Code and Copilot. Coding agents including Cursor, Goose, Amp, and OpenCode adopted it within weeks of the December launch, per VentureBeat's reporting. Partner-built skills from Atlassian, Figma, Canva, Stripe, Notion, and Zapier shipped in the same directory, per the same report.
That is wide coverage for a format barely a year old. It is not deep coverage yet: discovery conventions differ by client (VS Code defaults to .agents/skills/, Claude Code uses its own skills directory), and there is still no single marketplace where you install a vetted skill the way you'd pull an npm package. You find skills through GitHub, a vendor's own directory, or word of mouth.
Shipping one in five minutes
Skip the theory. If you're on VS Code with GitHub Copilot, this is the entire setup, per the official quickstart:
mkdir -p .agents/skills/roll-dice
# then write SKILL.md into that folder (the example above)Open the Copilot Chat panel, switch to Agent mode, and type /skills to confirm roll-dice shows up in the list. Ask the agent to "roll a d20." Per the documented flow: the agent matches your request against the skill's description, loads the markdown body, and runs the shell command with <sides> substituted for 20. It should ask permission to run the terminal command first; approve it once and it returns a number between 1 and 20.
The same folder works unmodified in Claude Code and OpenAI Codex, because the format, not the client, defines the behavior. Write the skill once, drop it in a repo, and every compatible agent your team runs picks it up the same way, which is the actual pitch for portability.
The catch: nobody vets what you install
The spec is simple on purpose, and simple formats get abused on purpose too. A skill is instructions plus executable code that an agent will run with your permissions. Anthropic's own engineering post is blunt about it: install skills only from trusted sources, and audit anything from a less-trusted one before use, paying attention to bundled scripts and any instruction that tells the agent to reach out to an external network address, per Anthropic's writeup. There is no AAIF-run security review gate today. The foundation's proposed roadmap covers versioned releases, a formal change-proposal process, and security guidance for skill authors and installers, but none of that exists yet, per the donation announcement. Treat a skill pulled from a random GitHub repo exactly like you'd treat a postinstall script in a package.json you didn't write.
The second limit is model-dependent reliability. Agent Skills documentation itself notes that tool-use reliability varies across models: some follow the instructions in a skill's body and run the commands consistently, others try to answer from general knowledge instead and skip the skill entirely, per the quickstart. A skill is a strong nudge, not a guarantee, and the gap shows up most on smaller or older models.
Agent Skills vs MCP: two different jobs
Teams keep asking which one replaces the other. Neither does. The clean distinction, per Anthropic's own framing: MCP is a live client-server protocol that connects an agent to external tools, data, and running processes, with its own auth and transport. Agent Skills is a static folder of instructions that tells the agent how to use whatever it already has access to, MCP-connected or not.
| Agent Skills | MCP | |
|---|---|---|
| What it is | A folder: SKILL.md + optional scripts/references/assets | A client-server protocol over JSON-RPC |
| What it provides | Procedural knowledge (how to do a task) | Live access (tools, data, running servers) |
| Loaded when | Agent matches your request to the description field | Connection established at session start |
| Needs a running process | No, it's a static file | Yes, an MCP server |
| Governs | agentskills.io / AAIF | modelcontextprotocol.io / AAIF |
| Typical use | Formatting conventions, review checklists, domain procedures | Database access, internal APIs, file systems |
A skill can tell your agent how to use an MCP-connected database correctly. It cannot connect to that database on its own. If you only install one of the two this quarter, install MCP servers for anything that needs live access, and write a skill for anything that is pure procedure your team keeps re-explaining.
Ship a skill now, wait on the marketplace
If your team already runs Cursor, Copilot, or Claude Code and has a workflow you explain to every new hire or re-type into every new chat, write that as a SKILL.md this week. The format is stable, the governance question that used to be a real adoption risk (what happens if Anthropic changes the rules unilaterally) is now closed, and the five-minute setup above is the whole cost. Start with the procedures that cost you the most repeated context: code review standards, a specific deploy checklist, a legal or finance formatting rule nobody remembers correctly on the first try.
Hold off on betting a production workflow on a skill you pulled from a public directory you don't control, and don't expect a vetted, npm-style marketplace to show up before the AAIF ships its proposal process and security guidance. For now, the format is ready. The supply chain around it isn't.