Agent Skills open standard, explained
The Agent Skills open standard explained: the SKILL.md format, its six frontmatter fields, progressive loading, and how Claude Code, Codex, and Cursor read it.
A team writes a solid code review skill for Claude Code. Two months later half the team is also using Codex, and someone rewrites the same procedure as a Codex skill, then a third person ports it to Cursor. Three copies drift apart. They didn't need to: all three tools read the same format.
This guide explains the Agent Skills standard from its specification, and how Claude Code, Codex, and Cursor use it, checked on 16 November 2026.
What the standard is
Agent Skills is an open format for packaging instructions and resources an agent loads when it needs them. Per agentskills.io, Anthropic developed it, released it as an open standard, and it's now open to contributions on GitHub.
A skill is a folder:
code-review/
├── SKILL.md # required: metadata and instructions
├── scripts/ # optional: code the agent can run
├── references/ # optional: docs loaded when needed
└── assets/ # optional: templates, schemas, images
The spec defines what goes inside the folder. It doesn't mandate where skill folders live; each tool picks its own locations.
The SKILL.md format
YAML frontmatter, then markdown instructions:
---
name: code-review
description: Reviews a diff for security, error handling, and test coverage
against this team's checklist. Use when asked to review a change or PR.
license: Apache-2.0
---
# Code review
1. Run `git diff main...HEAD`.
2. Check each item in [the checklist](references/CHECKLIST.md).
3. Report findings by severity, with file and line.
The six frontmatter fields in the spec:
| Field | Required | Rules |
|---|---|---|
name | Yes | Up to 64 characters; lowercase letters, numbers, hyphens; no leading, trailing, or double hyphens; must match the folder name |
description | Yes | Up to 1024 characters; what the skill does and when to use it |
license | No | A license name or a bundled license file |
compatibility | No | Up to 500 characters; environment needs, such as required tools |
metadata | No | Any string key-value pairs |
allowed-tools | No | Experimental; pre-approved tools, space-separated |
The body has no format rules. The spec recommends steps, input and output examples, and edge cases, and keeping SKILL.md under 500 lines.
How agents load skills
The spec calls it progressive disclosure, in three stages:
- Discovery: at startup, the agent loads only each skill's name and description, about 100 tokens each.
- Activation: when a task matches the description, it reads the full
SKILL.md. The spec recommends under 5,000 tokens. - Resources: files in
scripts/,references/, orassets/load only when the instructions call for them.
This is why the description matters most. It's the only part the agent sees before deciding, so it should say what the skill does and when to use it, with the words a user would type.
How Claude Code, Codex, and Cursor read it
| Claude Code | Codex | Cursor | |
|---|---|---|---|
| Project skills | .claude/skills/ | .agents/skills/, from the current directory up to the repo root | .cursor/skills/, .agents/skills/, .claude/skills/ |
| User skills | ~/.claude/skills/ | ~/.agents/skills/ | ~/.cursor/skills/, ~/.agents/skills/, ~/.claude/skills/ |
| Extensions to the spec | disable-model-invocation, argument-hint, subagent execution, shell output injected into the prompt | Plugins for distribution | /skill-name invocation |
Claude Code's docs say its skills follow the standard and extend it. Codex's docs say its skills build on it, and that Codex follows symlinked skill folders. Cursor's docs say it also loads .claude/skills/ and .codex/skills/ for compatibility, and picks up nested skill folders in monorepos.
One skill folder for all three
- Keep skills in
.claude/skills/. Claude Code and Cursor read it. - Add a symlink so Codex finds the same folders:
ln -s ../.claude/skills .agents/skills, run from the repository root aftermkdir .agents. - Use only the six spec fields in shared skills. Claude Code's docs note that claude.ai uploads and the Skills API reject unknown fields with an error, and other tools may ignore them.
- Keep tool-specific instructions out of shared skills, or put them in a separate skill for that tool.
The skills-ref library validates a skill: skills-ref validate ./code-review.
What skills are not for
Skills hold procedures: how to review, how to migrate, how to release. They're a poor home for decisions that change, such as "we're on Postgres 16 until Q2" or "the v1 endpoint stays until March". A skill is edited by whoever opens a pull request, has no owner or approval, and doesn't say when it stopped being true. See CLAUDE.md vs skills vs hooks vs subagents for what belongs where.
Where Lockstep fits
Lockstep keeps team decisions separate from skills. It captures decisions from PRDs, Slack, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions on the ones that apply. Its Standards & Skills feature manages Claude Code skills and rolls them out by team, repository, path, or task type; whether a skill was actually invoked isn't something it can observe, and it reports that honestly. Session briefings and managed skills work in Claude Code only; Codex isn't supported.
See how it works.
Sources checked 16 November 2026
- https://agentskills.io
- https://agentskills.io/specification
- https://agentskills.io/client-implementation/adding-skills-support
- https://code.claude.com/docs/en/skills
- https://developers.openai.com/codex/skills
- https://cursor.com/docs/skills
Related reading
For working examples, see Claude Code skills: 6 examples. For Cursor's rules versus skills, see Cursor rules vs skills vs AGENTS.md vs CLAUDE.md. For the always-loaded counterpart, see AGENTS.md examples. For how Antigravity, Claude Code, and Codex compare overall, see Gemini CLI vs Claude Code vs Codex CLI. For OpenCode's skill folders, see OpenCode vs Claude Code.
Frequently asked questions
- What is the Agent Skills open standard?
- An open format for giving AI agents task-specific instructions and resources. A skill is a folder containing a SKILL.md file with name and description frontmatter and markdown instructions, optionally with scripts, references, and assets. Anthropic developed it and released it as an open standard, documented at agentskills.io.
- Which tools support Agent Skills?
- Claude Code's docs say its skills follow the standard, OpenAI's docs say ChatGPT and Codex skills build on it, and Cursor loads SKILL.md folders too. Each tool reads from its own directories, so check where each one looks.
- What fields does a SKILL.md file need?
- Two are required: name, up to 64 lowercase letters, numbers, and hyphens, matching the folder name, and description, up to 1024 characters saying what the skill does and when to use it. Optional fields are license, compatibility, metadata, and the experimental allowed-tools.
- Where should I put skills so Claude Code and Codex both find them?
- Claude Code reads .claude/skills/, Codex reads .agents/skills/, and Cursor reads both. Keep one copy in .claude/skills/ and add .agents/skills as a symlink to it; Codex's docs say it follows symlinked skill folders.
- Can I use Claude Code frontmatter fields like disable-model-invocation in other tools?
- Not portably. Claude Code adds fields such as disable-model-invocation and argument-hint on top of the standard. Other tools may ignore them, and claude.ai uploads and the Skills API reject unknown fields with an error. Stick to the six spec fields for skills you share across tools.
Keep reading