Agent Skills: the open format, which tools read it, and portable skills

The format in brief

Agent Skills is a lightweight, open format for packaging what an agent needs to do a specific job: instructions, reference material, scripts and templates, in a folder an agent can discover and load on demand. It was originally developed by Anthropic, released as an open standard, and is now adopted by a long list of agent products, including ChatGPT and Codex.

The format defines what goes inside a skill folder. It deliberately does not define where skill folders live; each agent chooses its own locations. That split explains most portability questions: the contents travel well, the paths differ.

What the specification says

A skill is a directory containing at least a SKILL.md file:

skill-name/
├── SKILL.md       # required: metadata + instructions
├── scripts/       # optional: executable code
├── references/    # optional: documentation
└── assets/        # optional: templates, resources

SKILL.md must start with YAML frontmatter:

Field	Required	Constraint
name	Yes	1 to 64 characters, lowercase letters, digits and hyphens; no leading, trailing or double hyphens; must match the folder name
description	Yes	1 to 1,024 characters; what the skill does and when to use it
license	No	License name or bundled license file
compatibility	No	Up to 500 characters of environment requirements
metadata	No	String-to-string map for anything else
allowed-tools	No	Experimental; pre-approved tools, support varies

The body after the frontmatter is free-form Markdown. The spec recommends step-by-step instructions, examples of inputs and outputs, and common edge cases, with the main file kept under 500 lines. File references should be relative to the skill root and only one level deep.

Progressive disclosure

The spec’s central idea is that an agent reveals a skill in three stages:

1. Discovery. At startup the agent loads only each skill’s name and description, roughly 100 tokens per skill.
2. Activation. When a task matches, the agent reads the full SKILL.md (the spec suggests under 5,000 tokens).
3. Execution. The agent follows the instructions and reads references or runs scripts only as needed.

This is why an agent can have many skills installed with a small fixed cost. Codex implements the same model and adds a budget: its catalog of skill names, descriptions and paths uses at most 2% of the context window by default. See what Codex skills are for the Codex specifics.

Which tools read Agent Skills

The Agent Skills client showcase lists the products that support the format. At the time of writing it includes:

• Coding agents and CLIs: ChatGPT and Codex, Claude Code, Gemini CLI, OpenCode, Amp, Factory, Goose, Roo Code, Kiro, Mux, OpenHands, Letta, Firebender, Command Code, VT Code, Mistral Vibe, Autohand, fast-agent, Tabnine CLI and pi.
• Editors and IDEs: VS Code, GitHub Copilot, Cursor, JetBrains Junie, TRAE, Emdash.
• Platforms and frameworks: Claude, Databricks Genie Code, Snowflake Cortex Code, Spring AI, Laravel Boost, Qodo, Ona, Agentman and others.

The list grows often, so check the showcase for the current set.

Where each tool looks for skills

The paths below come from each product’s documentation. Only verified locations are listed.

Tool	Project skills	Personal skills
Codex	.agents/skills (working directory up to repo root)	~/.agents/skills
Gemini CLI	.gemini/skills or .agents/skills	~/.gemini/skills or ~/.agents/skills
OpenCode	.opencode/skills, .claude/skills, .agents/skills	~/.config/opencode/skills, ~/.claude/skills, ~/.agents/skills
VS Code / GitHub Copilot	.github/skills, .claude/skills, .agents/skills	~/.copilot/skills, ~/.claude/skills, ~/.agents/skills
Cursor	.agents/skills, .cursor/skills	~/.agents/skills, ~/.cursor/skills
Claude Code	.claude/skills	~/.claude/skills

Codex additionally reads /etc/codex/skills for machine-wide admin skills and its bundled system skills. Claude Code’s documentation does not list .agents/skills, so it needs its own copy or a symlink.

The .agents/skills convention

The Agent Skills implementation guide describes .agents/skills/ as a widely adopted convention for cross-client sharing: if every agent scans it, a skill installed for one is visible to the others. Codex uses it as its primary location, and the table above shows how many others read it too. For a team that uses more than one agent, .agents/skills in the repository is the natural home for shared skills.

Writing a skill that works everywhere

1. Use only name and description unless you need more. They are the two fields every implementation must support. Add license and metadata freely; avoid allowed-tools in a portable skill because its behavior differs between agents.
2. Keep the folder name equal to name. The spec requires it, and tools that are lenient today may not be tomorrow.
3. Describe outcomes, not one agent’s tools. “Run the test suite with pnpm test” works in any agent. “Use the Bash tool” or “call update_plan” ties the skill to one product.
4. Make scripts self-contained. A shebang, a clear dependency list (put it in compatibility too) and readable error messages. Every agent runs scripts differently, but all of them can run a command.
5. Use relative paths from the skill root for references and scripts.
6. Keep vendor metadata in separate files. Codex reads agents/openai.yaml for UI metadata, invocation policy and tool dependencies; it lives beside SKILL.md, so the core file stays portable.
7. Front-load the description. Agents with tight catalog budgets, Codex included, may shorten descriptions. The first clause should still identify the job.

Example: one folder for Codex and Claude Code

Keep the skill in .agents/skills, which Codex reads, and link it into .claude/skills for Claude Code:

mkdir -p .agents/skills .claude
# write the skill once
ls .agents/skills/release-notes/SKILL.md
# expose the whole folder to Claude Code
ln -s ../.agents/skills .claude/skills
git add .agents/skills .claude/skills

Codex follows symlinked skill folders when scanning. On Windows, where symlinks need extra permissions, a copy maintained by a small sync script is the simpler option. For everything else that differs between the two agents, from instruction files to permissions, see Codex vs Claude Code.

Validate against the spec

The Agent Skills project publishes a reference validator:

skills-ref validate ./release-notes

It checks the frontmatter and naming rules. Behavior still needs testing in each agent you care about: whether the skill appears, whether it triggers on the requests you expect, and whether its scripts run in that agent’s sandbox. For Codex, the first skill tutorial shows the test loop and the SKILL.md reference covers every field in detail.

Every skill on this site follows the specification, so the folders you install from here work in any of the tools above, not only Codex.