Open standard for extending AI agents with specialized knowledge and workflows. A skill is a folder containing a SKILL.md file with YAML frontmatter and instructions, optionally bundling scripts, references and assets. Loaded through progressive disclosure so many skills cost little context until used. Originally developed by Anthropic and released as an open standard.
Agent Skills
Agent Skills is an open format for giving an AI agent a capability it did not previously have. A skill is a folder containing, at minimum, a SKILL.md file — YAML frontmatter that says what the skill does and when to use it, followed by markdown instructions the agent follows once it decides to. Alongside it a skill may bundle scripts/ for deterministic work, references/ for documentation loaded on demand, and assets/ for templates and data. It was originally developed by Anthropic, released as an open standard, and has since been adopted across a wide range of agent products.
- Six frontmatter fields - The standard defines
nameanddescriptionas required, plus optionallicense,compatibility,metadataandallowed-tools. Anything beyond those is a tool-specific extension and does not travel. - Progressive disclosure - Only
nameanddescriptionare held for every installed skill; the body loads on activation, and bundled files load only when the instructions call for them. - A folder, so it versions - A skill lives in source control, diffs in a pull request, and reviews like any other artifact rather than sitting in a chat history.
- Portable across agents - The same folder is read by Claude Code, Cursor, GitHub Copilot, VS Code, Gemini CLI, Codex, Goose, OpenHands and others, so procedural knowledge is authored once.
For API teams, a skill is where the operating manual finally becomes machine-actionable — the governance rules, the onboarding sequence, the way this organization designs and reviews an API, packaged so an agent can follow it rather than infer it. The description field carries disproportionate weight, because it is the only part loaded up front and therefore the entire basis on which a skill is chosen. Agent Skills sits in the same agentic stack as AGENTS.md and AGENT.md, which give an agent project context, and MCP, which connects it to live services — the difference being that a skill describes the job to be done rather than the codebase or the connection.
Referenced in API Evangelist papers
This standard shows up in my published research. These reports read the machine-readable evidence provider by provider — and put this standard in the context of a real sector.
The Fundamentals of Markdown
SKILL.md sits in the same markdown control layer as AGENTS.md and the vendor instruction files — the plain-text substrate agents actually read.
The Model Context Protocol Standard
The other half of the agent-artifact layer. MCP connects an agent to a running service; a skill hands it the procedure. Discovery is unsolved for both.
The State of Artificial Intelligence APIs
agent_skills reach 50.5% of the upper band across 1,683 skill files — harder to fake than an MCP server, because a skill has to describe a job rather than an endpoint.
Referenced on the API Evangelist blog
Where this standard shows up across sixteen years of my writing at apievangelist.com — how it fits into API design, governance, and the agentic turn.
Markdown Became the Control Plane for AI
2026-08-10
