For about two years, teaching an AI coding tool how you work meant writing the same instructions three or four times over. A .cursorrules file for one editor, a rules directory for another, a differently-named markdown file for a third. Same content, four formats — and none of it travelled when you switched tools, which in this ecosystem happened roughly every quarter.
Agent Skills is the format that ended that. It is deliberately unambitious: a skill is a folder, the folder has a SKILL.md file, the file has two required fields. The interesting part isn’t the design — it’s that a large slice of the agent ecosystem agreed to read the same thing, which is what turns a file format into leverage.
What is agentskills.io?
agentskills.io is the home of the Agent Skills specification: the documentation, a reference validator, and a showcase of the clients that support it. The format was originally developed by Anthropic, released as an open standard, and has since been adopted by a growing list of agent products. Development happens in the open — there’s a public GitHub repository and a Discord, and the standard describes itself as open to contributions from the broader ecosystem.
Its own framing: a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows, where a skill is a folder containing a SKILL.md file with metadata and instructions, optionally bundled with scripts, reference material and templates. If you want the concept before the specification, what an AI agent skill is covers that ground.
What problem does a shared skill format solve?
“Write once, run anywhere” is the short answer, but the alternative wasn’t nothing — it was per-vendor prompt files, and they failed in three ways.
They didn’t travel. Instructions written for one tool were dead weight the moment you tried another. Every switch meant a translation pass, and translation passes don’t happen; knowledge just gets left behind.
They didn’t compose. A flat rules file competes with itself — everything loads all the time, so your tenth procedure degrades the first nine. Skills load on demand, so the tenth costs almost nothing until you need it.
They had no distribution story. You can’t share a .cursorrules file with someone on a different editor. A skill folder is portable by construction, which is what makes public libraries possible at all: a library of skills is only useful because it isn’t addressed to one vendor’s customers.
The value of a standard isn’t the format. It’s that the thing you wrote last year still runs in the tool you picked this morning.
What does the format actually specify?
Three things: a directory layout, a small frontmatter schema, and a loading model.
The directory. A skill is a directory containing, at minimum, a SKILL.md file. The spec names three optional conventions — scripts/ for executable code the agent can run, references/ for documentation it reads on demand, assets/ for templates and static resources — and allows any other files you like.
The frontmatter. Only two fields are required: name (lowercase, hyphenated, matching the parent directory name) and description (saying both what the skill does and when to use it). Optional fields cover license, a compatibility string for environment requirements, a free-form metadata map, and allowed-tools, which the spec explicitly marks as experimental with support varying between implementations. Everything after the frontmatter is plain Markdown with no format restrictions. What goes in SKILL.md walks through the anatomy and the exact limits.
The loading model. Agents load skills through progressive disclosure, in three stages. At startup, only each skill’s name and description load — roughly 100 tokens apiece — just enough for the agent to know a skill might be relevant. When a task matches the description, the full SKILL.md body loads. Bundled files load only when the instructions reach for them. That explains the two practical rules the spec gives authors: keep SKILL.md under 500 lines, and treat the description as a trigger rather than as documentation.
Notice what isn’t in it: no install command, no registry, no directory path an agent must use, no runtime API. The spec covers the artifact, not the plumbing.
Why portability matters when you’re choosing what to invest in
Writing a good skill is real work — encoding a review checklist, a positioning framework or a deployment procedure well enough that an agent applies it consistently takes an afternoon at minimum. That effort is only worth spending if the result outlives the tool you wrote it in, and under the standard it does. The same folder is read by Claude Code from ~/.claude/skills/, by Codex from ~/.agents/skills/, by Cursor from ~/.cursor/skills/, by OpenClaw and Hermes Agent from their own roots — and by whatever replaces them, provided it reads the format. The skill is a versionable text asset in your repository, not configuration held inside a vendor’s product.
There’s a team dimension too. Most engineering organisations are not standardised on one agent and won’t be: one person is in Claude Code, another in Cursor, a third has moved to Codex, and CI runs something else again. A skill committed to the repository is the only form of shared agent knowledge that reaches all of them at once — a governance argument as much as a convenience one. Your review standards, a clean-code skill say, live in one reviewable file rather than four people’s private settings.
Use the jobs-to-be-done skill to analyse why our customers actually hire our product, working from the interviews in this folder
Jobs to Be DoneThat skill is one directory containing one SKILL.md, and it runs identically in every compatible agent.
How do I check whether an agent supports it?
Three checks, in increasing order of confidence.
Look it up in the client showcase. agentskills.io maintains a list of compatible clients — currently including Claude, Claude Code, Codex and ChatGPT, Cursor, GitHub Copilot, VS Code, Gemini CLI, OpenCode, Goose, Amp, OpenHands, Kiro, Factory, OpenClaw and Hermes Agent, among dozens of others. Each entry links to that client’s own skills documentation.
Read the agent’s own skills page. This is where you find the thing the standard deliberately doesn’t specify: which directory that agent reads. Claude Code documents ~/.claude/skills/ and .claude/skills/; Codex documents $HOME/.agents/skills and .agents/skills; Cursor documents .cursor/skills/ and .agents/skills/ plus fallbacks. If an agent’s docs name a skills directory and a SKILL.md file, it supports the format in the way that matters to you.
Test it. Drop a folder with a trivial SKILL.md into the documented path, start a session, and ask the agent to use it by name. Two minutes, and it settles the question — including for agents that support the format without appearing in any list. Our installation guide covers the per-agent paths in detail.
To validate a skill you wrote, agentskills.io publishes a reference library, skills-ref, with a validate command that checks frontmatter and naming conventions against the spec.
What’s settled, and what isn’t
Being straight about this matters more than boosterism, because the standard is young.
Settled: the core file format. A folder, a SKILL.md, name and description required, Markdown body, progressive disclosure as the loading model. That much is stable, documented, and read by a large and still-growing set of clients. A skill written to that shape today will be read tomorrow.
Not settled: almost everything around distribution. Because the spec covers the artifact rather than how it reaches a machine, the ecosystem has several parallel answers — the skills.sh CLI, Claude Code’s plugin marketplaces, the separate Agent Plugins packaging spec, and each agent’s own installer. They coexist rather than compete, but expect to meet more than one.
Also not settled: the edges of the frontmatter. allowed-tools is labelled experimental in the spec itself, and individual clients recognise extra fields the spec doesn’t define. Sticking to the documented fields is what keeps a skill portable. Invocation syntax is out of scope entirely — slash commands in some agents, a $skill-name prefix in others.
The honest summary: the format is the settled part and the packaging is the moving part, which is the right way round, since the format is what your writing effort is stored in.
Frequently asked questions
Who owns or governs the Agent Skills standard?
The format was originally developed by Anthropic and released as an open standard. Development now happens publicly, with a GitHub repository and a Discord for discussion, and the standard describes itself as open to contributions from the broader ecosystem. Beyond that, no formal foundation or steering body is published on agentskills.io — so it is best understood as an open, publicly developed specification with an originating vendor, rather than a standard under independent governance.
What version of the specification should I target?
The specification page doesn’t publish a version number; it is maintained as a living document describing the current format. In practice you target the documented fields as they stand: name and description required, license, compatibility, metadata and allowed-tools optional, with allowed-tools flagged experimental. For a machine check, the skills-ref library published alongside the spec has a validate command that checks a skill directory against the current rules.
Is a skill written for Claude Code portable to other agents?
Usually, and the exception is instructive. A skill that sticks to the specified frontmatter fields and plain Markdown instructions works anywhere the format is read. What doesn’t travel is client-specific extras: frontmatter keys only one agent recognises, and body features only one product implements. Spec-conformant frontmatter plus ordinary Markdown is portable; anything beyond it is a local enhancement, not part of the skill.
Does adopting the standard lock me into a particular agent or vendor?
No, and that’s the point of it. Because the skill is a plain directory of Markdown files kept in your own repository or home directory, moving to a different agent means pointing that agent at the same folder rather than rewriting anything. That is the reverse of the situation the format replaced, where instructions lived in vendor-specific configuration and every tool switch meant a translation pass that in practice never happened.
Where to go from here
To use skills rather than write them, the fastest path is installing an existing library and pointing your agent at a task you were doing anyway. To write one, how to write an agent skill covers the authoring craft and what goes in SKILL.md covers the file itself. If you’re weighing the format against a runtime integration, skills compared with MCP draws that line.
Either way, the standard’s practical promise is worth restating: what you write is a folder, the folder is yours, and it keeps working when you change tools.