What are Agent Skills? The SKILL.md standard and who reads it

What’s in a skill

The specification is short. A skill is a directory with a SKILL.md in it, optionally beside scripts/, references/ and assets/ folders; the file is YAML frontmatter followed by Markdown, and the body has no required shape. A complete one:

.agents/skills/sql-migration/SKILL.md

---
name: sql-migration
description: Writes a reversible database migration for this project. Use when asked to add, change or drop a table or column.
---

1. Read references/conventions.md for naming and column types.
2. Write the forward and the backward migration in one file under migrations/.
3. Run scripts/check.sh against a scratch database before saying it is done.

Two fields are required. The name is up to 64 lowercase letters, digits and single hyphens, and matches the folder; the description is up to 1,024 characters and says both what the skill does and when to use it, because that sentence is all the agent sees until it decides to load the skill. Four more are optional: license, compatibility (up to 500 characters on what the skill needs, such as a tool or network access), metadata for anything else, and an experimental allowed-tools list of tools the skill may use without asking. The specification budgets about 100 tokens a skill for that listing, recommends under 5,000 tokens for the body, and suggests keeping SKILL.md under 500 lines, with longer material in the files beside it that the body points to. Its reference tool checks a skill with skills-ref validate ./my-skill.

The standard is developed in the open at agentskills/agentskills, whose home page says it “was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products”; its list of clients had 45 entries on October 9, 2026. The specification says what goes inside a skill and nothing about where skills live, which is why the folders below differ.

How an agent uses one

Every agent here does the same three things in its own way. At the start of a session it lists each skill’s name and description for the model. When a task matches a description, the model loads the body: Claude Code and OpenCode through a skill tool, Codex by reading the file through its shell, Pi with its ordinary read tool. Files beside SKILL.md are opened only when the instructions call for them, so a large skill costs little until it is used. You can also start a skill by hand, and each agent spells that differently: /name in Claude Code, Copilot and Cursor, $name in Codex, @name in OpenCode 2, /skill:name in Pi.

Which agents read it, and from where

In the first four rows, the project folders and OpenCode’s and Pi’s home folders are what we saw on October 9, 2026; Claude Code’s and Codex’s home folders, and the other rows, are each maker’s docs read the same day, linked from its name.

So .agents/skills/ is the closest thing to a shared folder. The standard’s guide for agent makers calls it “a widely-adopted convention for cross-client skill sharing” while noting the specification itself doesn’t require it, and that “some implementations also scan .claude/skills/” because so many skills already live there. OpenClaw is the different one: it is a personal agent with a workspace of its own rather than a coding agent you start inside a project, so its .agents/skills/ is the one in that workspace, and OpenClaw’s skills come from there, from your home folder and from its registry.

One copy for every agent

In a project, keep the skill in .agents/skills/ and link it into .claude/skills/ for Claude Code:

mkdir -p .claude/skills
ln -s ../../.agents/skills/sql-migration .claude/skills/sql-migration

We tried it on October 9, 2026, after first putting one probe skill in each agent’s folder to see who read what (the table’s tested rows). With the skill kept once in .agents/skills/ and linked from .claude/skills/: Claude Code and Codex listed it and used it when a question matched its description; OpenCode listed it once, although it reached it through both folders, and loaded it with its skill tool; Pi listed it once we had trusted the folder, and listed no project skill at all before that. For skills you want in every project, the same pattern works at home: ~/.agents/skills/ is read by Codex, OpenCode, Pi, Gemini CLI, Copilot, Cursor and OpenClaw, and a link from ~/.claude/skills/ covers Claude Code; Hermes needs ~/.agents/skills added to the skills.external_dirs list in its config.

Two cautions. OpenClaw refuses a skill folder in its workspace that is a symlink pointing outside it unless you allow that target in its settings, so give OpenClaw a copy or allow the folder you link to. And Hermes, Pi and Gemini CLI load a project’s skills only once you trust the project, which is a feature, not a fault (below).

What doesn’t travel

Only name and description mean the same thing everywhere. The rest is where the same file meets different readers:

• A name that breaks the rules. With a skill named “Display Probe” in a folder called display-probe, all four tested agents loaded it, each showing it differently: Claude Code by the folder’s name, OpenCode under the folder as its ID with the name as a label, Codex and Pi by the name as written, which made Pi’s command /skill:Display Probe. VS Code’s docs say a skill whose name doesn’t match its folder silently fails to load, and Cursor’s that the two must match.
• No description. Claude Code uses the body’s first line instead; OpenCode keeps the skill but never shows it to the model; Codex and Pi drop it.
• disable-model-invocation: true, which keeps a skill for when you call it by name, works in Claude Code, OpenCode 2, Pi, VS Code and Cursor; Codex ignores it and has its own setting in an agents/openai.yaml file inside the skill.
• allowed-tools pre-approves tools in Claude Code and Copilot; OpenCode, Pi and Codex don’t act on it, and their own permission settings decide what the skill’s commands may do.
• Two skills with one name. The standard’s guide calls “project-level skills override user-level skills” the convention, and Pi, Hermes, OpenClaw and Gemini CLI follow it; Claude Code does the opposite; Codex shows both; OpenCode follows it within each kind of folder, but its own personal folder beats a project’s .agents/skills/.

A skill meant for several agents is therefore best written to the specification alone, with any agent’s extras added knowing the others will ignore them. Claude Code’s skills and OpenCode’s each have a page with their extras.

Skills beside AGENTS.md, MCP and plugins

An AGENTS.md file is read at the start of every session, so it suits facts every task needs; a skill suits a procedure some tasks need, because it costs nothing until it is used. An MCP server gives an agent tools and data from outside, such as a database or an API, and a skill can teach it to use them well. A plugin is packaging that can carry skills, MCP servers and more in one install, as the plugins guide describes for Claude Code and Codex.

Before you use someone else’s

A skill is instructions an agent follows with your access, and often scripts it runs. Anthropic’s skills overview says to use skills “only from trusted sources” and warns that “malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks.” The agents differ on whether a repository you clone gets to load its skills before you have looked: Pi, Hermes and Gemini CLI wait until you trust the project. Claude Code, Codex and OpenCode, run non-interactively in our test, loaded and used the skills of a repository they had never seen without asking. With them, the skills in a repository are part of what you trust when you run an agent in it.