What is SKILL.md? The Agent Skills standard and which agents support it

A SKILL.md is the entry file of an Agent Skills folder: YAML frontmatter with a name and a description, followed by Markdown instructions the agent reads when it decides the skill applies. Write one and you can hand the same folder to a lot of different agents, because the format is an open standard rather than one vendor's config file. The catch is the part nobody puts in the headline: every client reads the same SKILL.md format, but they disagree about the folder it lives in, so portability is real for the file and patchy for the path.

#What is a SKILL.md file?

Anthropic, which wrote the format, describes skills as "organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks". The specification puts it structurally: a skill is a directory containing, at minimum, a SKILL.md.

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

The three optional directories are conventions, not requirements. scripts/ holds code the agent can run, references/ holds documentation it can open when a task calls for it, and assets/ holds templates and data files.

What makes the layout worth following is progressive disclosure, which is the design idea the spec is built around. The name and description load at startup for every installed skill, at roughly 100 tokens per skill for the two fields together. The rest of the SKILL.md body loads only when the skill is activated, and the spec recommends keeping that body under 5000 tokens and the file under 500 lines. Everything in scripts/, references/ and assets/ loads only when it is needed. That is why a large skill does not cost you context you are not using.

#What does the spec actually require?

Six frontmatter fields exist in the standard, and only two of them are required.

A minimal skill is therefore four lines of frontmatter and a body:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---

The body has no format rules at all. The spec recommends step-by-step instructions, examples of inputs and outputs, and common edge cases, and that is as prescriptive as it gets.

If you want the naming rules enforced rather than remembered, the project ships a reference validator:

skills-ref validate ./my-skill

#Which agents support Agent Skills?

The showcase at agentskills.io/clients.md is the list the standard keeps of products that read the format. We counted it on 21 September 2026 and it names 46 clients.

They are not all coding agents, which is the interesting part. The list covers terminal agents (Claude Code, Codex CLI, OpenCode, Goose, Mistral AI Vibe), editors and IDEs (Cursor, VS Code, JetBrains Junie, TRAE, Kiro, Roo Code), general assistants (the Claude app, ChatGPT), personal agents that run on your own hardware (OpenClaw, Hermes Agent, ZeroClaw, nanobot), and a long tail of platform-specific agents such as Databricks Genie Code, Snowflake Cortex Code, Pulumi Neo and Laravel Boost.

Two things follow from a list that shape. First, a skill you write for one agent is very often readable by another with no changes to the file. Second, "supports Agent Skills" is a claim about reading SKILL.md, not a promise that every client exposes the same behaviour around it.

#Where does each agent look for skills?

This is where portability gets practical, and where most of the friction is. Every path below is quoted from that client's own documentation.

The practical reading: .agents/skills/ is the nearest thing to a neutral location, and five of the six agents above document it. Claude Code is the exception in that table. Its skills page lists personal skills at ~/.claude/skills/, project skills at .claude/skills/, the same .claude/skills/ path in a managed settings directory or a directory passed with --add-dir, plugin skills at <plugin>/skills/, and legacy command files at .claude/commands/<skill-name>.md. Apart from the plugin folder, every one of those paths is under .claude/. Cursor and Copilot both read .claude/skills anyway, which is why a Claude Code project often works in those two without being moved.

Gemini CLI splits this across two pages. Its skills page documents where skills live and says the SKILL.md body and folder structure are added to the conversation history. The frontmatter is on its page about creating skills, which lists two fields: name, a unique identifier that should match the directory name, and description, which is how Gemini decides when to use the skill.

#Why do clients add their own frontmatter fields?

Because the spec deliberately stops at six fields, and an agent that wants to control model choice, tool permissions or activation triggers has to put that somewhere.

Claude Code is the clearest case. Its documentation lists 20 frontmatter fields, six of which are the spec's own. The other 14 are its own: when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, disallowed-tools, model, effort, context, agent, background, hooks, paths and shell. It also treats every field as optional and only description as recommended, which is looser than the spec's own two required fields.

Cursor takes a smaller bite: name and description required, then paths, disable-model-invocation, icon, color and metadata. Note that paths and disable-model-invocation appear in both Cursor's list and Claude Code's, while icon and color are Cursor's alone. Codex keeps the two required fields and pushes optional metadata into a separate agents/openai.yaml file rather than into the frontmatter.

The portable habit that falls out of this: keep the six spec fields in SKILL.md, and treat anything else as a client-specific extra that other tools may reject. The reference validator, skills-ref validate, reports an error for any frontmatter key outside those six, and Claude Code's own docs say that uploading a skill with such a key to claude.ai or the Skills API fails with a hard error instead of ignoring the field. The metadata map exists precisely so that extra properties have a defined home, and the spec advises making your key names unique enough to avoid collisions.

Availability inside a single product varies too, and it is worth checking rather than assuming. OpenAI's documentation says standalone skills "are available in the ChatGPT desktop app, Codex CLI, and IDE extension", while skills bundled in plugins are "also available in Chat and Work across ChatGPT on the web, desktop, and mobile". GitHub says agent skills "work with Copilot cloud agent, Copilot code review, the GitHub Copilot CLI, the GitHub Copilot app, and agent mode in Visual Studio Code and JetBrains IDEs".

#How do you check a skill before you install it?

A skill is instructions plus, very often, scripts that an agent will run with your permissions. The two vendors who say the most about this say the same thing.

Anthropic's own guidance is to install skills only from trusted sources, and, when installing from a less trusted source, to audit it thoroughly before use. It names the risks plainly: a malicious skill can introduce vulnerabilities, direct the agent to exfiltrate data, or take actions you did not intend. OpenClaw's skills documentation is blunter still: "Treat third-party skills as untrusted code. Read them before enabling. Prefer sandboxed runs for untrusted inputs and risky tools."

Our own checklist for reading one before you enable it is at the skill security audit guide. Nothing on ClawDocx is an endorsement of a third-party skill, and a skill being listed somewhere popular is not a review.

The minimum worth doing, every time: open the SKILL.md and read it end to end, open every file in scripts/ and read those too, check what allowed-tools asks to pre-approve, and look at what the instructions tell the agent to do with network access and with your files.

#Who owns the standard?

The format was developed by Anthropic and released as an open standard, and the repository describes it as adopted by a growing number of agent products and open to contributions from the broader ecosystem. The licensing is split the way documentation projects usually split it: code in the repository is licensed under Apache 2.0, and the documentation under CC-BY-4.0.

Anthropic's engineering post introducing skills is dated 16 October 2025, and is still the clearest statement of why the format looks the way it does: as agents get more capable, the argument runs, they need "more composable, scalable, and portable ways" to be given domain-specific expertise, and a folder of Markdown is about as portable as that gets.

#Where to go next

If you want the standard as a reference page rather than an explainer, the Agent Skills hub tracks the format, the client count and the per-client folders. If you are writing your first skill for a specific agent, Understanding Skills walks through how OpenClaw loads and prioritises them, and Building Custom Skills covers writing one from scratch.