Agent Skills: The Open Standard for Teaching AI Agents

Agent Skills is an open standard for teaching AI agents how to do specific tasks: a skill is a folder containing a SKILL.md file with a name, a description, and instructions, which any compatible agent loads on demand when the task at hand matches. The format was created by Anthropic, released as an open standard at agentskills.io, and has since been adopted by most of the major coding agents, which is the point. A procedure you write once, as a skill, now runs in whichever agent your teammates happen to use.

The problem the standard solves is older than the standard. Every team that works with AI agents accumulates procedural knowledge: how to run the release checklist, how to review a migration, how to structure a bug report, how to verify a UI change. Before skills, that knowledge lived in three bad places. It lived in people's heads, so it got re-typed into chat over and over. It lived in ever-growing instruction files that agents carry in full on every request, whether relevant or not. Or it lived in tool-specific config formats, so a procedure written for one agent had to be rewritten for the next.

The organizing principle of Agent Skills is progressive disclosure: agents see only a skill's name and description at startup, and load the full instructions only when a task actually calls for them. That single design choice is what makes the format cheap enough to keep dozens of skills installed and simple enough for many tools to implement. This article covers what the format specifies, how it became a cross-vendor standard, which tools support it, what portability buys you in practice, and, just as important, what a portable skill cannot standardize.

What an Agent Skill Looks Like

A skill is a directory. The only required file is SKILL.md, which contains YAML frontmatter followed by Markdown instructions:

release-checklist/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation loaded on demand
└── assets/           # Optional: templates, data files

The frontmatter requires exactly two fields. name must be lowercase letters, numbers, and hyphens, maximum 64 characters, and must match the folder name. description is up to 1,024 characters and should say both what the skill does and when to use it, because the description is the only thing the agent sees before deciding to load the skill. The spec also defines four optional fields: license, compatibility (environment requirements, such as "requires git and docker"), metadata (arbitrary key-value pairs), and an experimental allowed-tools field for pre-approving tool use.

---
name: release-checklist
description: Run the pre-release verification checklist. Use before tagging a release or when the user asks to ship.
---

Everything below the frontmatter is plain Markdown instructions. There are no format restrictions on the body; the spec recommends step-by-step instructions, input/output examples, and edge cases, and suggests keeping SKILL.md under 500 lines with detailed reference material split into separate files.

Loading happens in three stages. At startup, the agent reads only name and description for every installed skill, roughly 100 tokens each. When a task matches a description, the agent reads the full SKILL.md body into context. During execution, it loads bundled reference files or runs bundled scripts only as needed. A team can keep thirty skills installed and pay the context cost of the two that a given task actually touches. For the mechanics of writing a good one, see our guide to creating a Claude Code skill.

From Anthropic Feature to Open Standard

Anthropic introduced skills in October 2025 as a feature of Claude Code and the Claude apps: reusable instruction folders that Claude would load when relevant. The format spread fast for a mundane reason. It was just Markdown in folders, checked into git, so nothing about it was actually proprietary, and other tools began reading the same files.

In December 2025, Anthropic formalized that reality by releasing Agent Skills as an open standard, publishing the specification, a reference validation library (skills-ref), and governance at agentskills.io, with development open to contributions on GitHub. The move mirrors what Anthropic did with the Model Context Protocol a year earlier, and the two standards are complementary: MCP defines how an agent connects to tools and data, while skills define what the agent should do with them. An MCP server gives an agent hands; a skill gives it the procedure.

Which Tools Support Agent Skills

As of mid-2026, agentskills.io lists more than 40 tools that support the format. The list spans direct competitors, which is what makes it a real standard rather than one vendor's feature:

• Anthropic: Claude Code, the Claude apps, and the Claude API
• OpenAI: Codex
• Google: Gemini CLI
• Microsoft/GitHub: GitHub Copilot and VS Code
• Editors and IDE agents: Cursor, JetBrains Junie, Kiro, Trae, Roo Code
• Terminal and open-source agents: OpenCode, Amp, Goose, OpenHands, Factory, Mistral Vibe
• Platform agents: Snowflake Cortex Code, Databricks Genie Code, Pulumi Neo, Tabnine, Qodo

Support depth varies. Every adopter reads name, description, and the instruction body; not every adopter implements the experimental allowed-tools field or discovers skills from the same directories. Claude Code reads .claude/skills/, Codex and several others read .agents/skills/, and a common repo pattern is to keep skills in one canonical directory and symlink the other. Check the current adopter list at agentskills.io before assuming a specific tool is covered, since it grows monthly.

What Portability Actually Buys a Team

The concrete payoff: you write the procedure once, and every agent follows it.

Before the standard, a team running Claude Code and Cursor side by side maintained two copies of every procedure, in two formats, that drifted apart within weeks. Now the deploy checklist, the migration review procedure, and the test-writing conventions live in one folder in the repo, and whichever agent a developer opens follows the same steps. Three things fall out of that:

Procedures survive tool churn. Teams switch agents more often than they rewrite process docs. A skill written during your Claude Code era still works if half the team moves to Codex, because the investment was in the procedure, not the tool.

Procedures get reviewed like code. Skills live in the repo, so a change to the release checklist goes through a pull request. The version that runs is the version that was reviewed, which is not true of knowledge that lives in chat history.

Vendors can ship expertise, not just integrations. This is the part we have a direct stake in. Shiplight, our verification platform for AI-native development, installs into coding agents as a browser MCP server plus skills such as /shiplight verify and /shiplight create-yaml-tests. We ship our verification procedures as skills precisely because the standard makes them portable: one skill folder teaches Claude Code, Codex, Cursor, and Gemini CLI the same verification workflow, instead of us maintaining four integrations. See how Shiplight works with coding agents for the details.

What Stays Agent-Specific

The standard deliberately specifies the format, not the runtime, so individual agents layer their own extensions on top. Claude Code is the clearest example. Beyond the spec's fields, it adds invocation control (disable-model-invocation: true makes a skill runnable only by the human, via /skill-name, which you want for deploys; user-invocable: false makes a skill loadable only by the model, for background knowledge), subagent execution (context: fork runs the skill in an isolated subagent, with an agent field to pick which type), plus hooks, paths-scoped activation, per-skill model overrides, and dynamic context injection via inline shell commands.

None of that breaks portability, because unknown frontmatter fields are simply ignored by other agents. A skill using context: fork still runs in Cursor; it just runs inline instead of in a subagent. The instructions carry; the execution refinements degrade. The practical rule: put the procedure in the portable parts, and treat vendor extensions as per-agent tuning. The spec's compatibility field exists for the cases where a skill genuinely requires one environment.

Skills vs Prompt Files vs Agent-Native Rules

Skills did not replace agents' native configuration; they sit alongside it. CLAUDE.md and AGENTS.md files hold always-loaded facts about a project: architecture, conventions, commands. Cursor rules attach instructions to file globs. Skills hold procedures that load on demand. The failure mode skills fix is the instruction file that grew into a procedure manual, paying full context cost on every request; the general discipline is covered in our context engineering guide.

Rule of thumb: if it is a fact the agent should always know, it belongs in the instruction file. If it is a procedure the agent should follow sometimes, it belongs in a skill.

What a Portable Skill Cannot Standardize

Honesty about the limits keeps expectations right, and there are three the format cannot paper over.

Capability. A skill is instructions, not ability. If the skill says "verify the change in a real browser" and the agent has no browser tool, the instructions are inert. Portable procedures still depend on each agent's tools, which is why skills and MCP servers so often ship together.

Permissions. The spec's allowed-tools field is explicitly experimental, and each agent enforces its own permission model regardless of what a skill requests. The same skill may run unattended in one agent and stop for approval at every command in another. Nothing in the standard can grant access an agent's own policy denies, and that is the correct design; a text file you downloaded should not be able to expand what an agent may touch.

Loading judgment. Whether a skill activates at the right moment depends on each agent's matching between task and description, and models differ. A description that reliably triggers Claude Code may under-trigger elsewhere. Well-written, keyword-rich descriptions narrow the gap; they do not close it. Teams should spot-check that critical skills actually fire in each agent they support rather than assuming portability of judgment along with portability of text.

If your procedures are single-agent forever, agent-native config may honestly be enough, and the standard buys you little today. Its value compounds with tool diversity, and tool diversity is the direction most teams are heading.

Frequently Asked Questions

Related Reading

• Claude Code skills, the deepest skills implementation and where most teams start.
• Codex skills, how OpenAI's agent reads the same standard.
• How to create a Claude Code skill, the writing craft behind a skill that actually triggers.
• Best Claude Code skills for testing, concrete skills worth installing for verification work.
• Context engineering for coding agents, the discipline progressive disclosure belongs to.

External references: agentskills.io, the Agent Skills specification, and the Claude Code skills documentation.