AgentSkills.site

SKILL.md: The Agent Skill File Format

The specification fits on one page. What it doesn't tell you is which fields survive the trip to another agent, which ones a runtime silently ignores, and which one makes your skill vanish entirely. That needs all five implementations open at once.

Published

AgentSkills.site editorial

A SKILL.md is a markdown file with YAML frontmatter that turns a folder into an agent skill. The frontmatter tells an agent when the skill is relevant; the body tells it what to do once it is.

---
name: deploy-staging
description: Deploy or roll back a service to staging. Use when asked to ship,
  deploy, release, or revert.
---

Step-by-step instructions for the agent to follow.

That is a complete, valid skill. Two fields and a body — everything else is optional.

The format is the Agent Skills open standard, developed at Anthropic and released for anyone to implement. It is now read by a long list of agents, which is what makes the file portable: the same SKILL.md runs in Claude Code, Codex, Cursor, OpenClaw and others without modification.

The directory

A skill is a folder, not just a file. The conventions:

my-skill/
├── SKILL.md          # required
├── scripts/          # optional: executable code the agent can run
├── references/       # optional: documentation loaded on demand
└── assets/           # optional: templates, images, data files

Only SKILL.md is required, and the folder may contain anything else you need. The three named directories are conventions the spec recommends rather than a rigid schema — but they map onto how agents load material, which is the next section.

Frontmatter, with the constraints that actually bite

Field Required Constraint
name Yes 1–64 characters. Lowercase letters, digits and hyphens only. No leading, trailing or consecutive hyphens. Must match the parent directory name
description Yes 1–1024 characters. What the skill does and when to use it
license No A licence name, or a reference to a bundled licence file
compatibility No Up to 500 characters. Environment requirements — intended product, system packages, network access
metadata No A map of string keys to string values. Where runtimes put their own extensions
allowed-tools No Space-separated list of pre-approved tools. Experimental

Two of these deserve more than a table row.

name must match the folder. A mismatch is a silent failure, and so is the wrong filename case — skill.md rather than SKILL.md is one of the most commonly reported causes of a skill never appearing. See agent skills not working.

allowed-tools is experimental, and the specification says support "may vary between agent implementations." It is the field people reach for when they want to constrain what a skill can do, and it is the least reliable field in the format. Do not treat it as a security control.

How agents load a skill

The format is built around progressive disclosure — three stages, so that a large skill library costs almost nothing until it's needed:

Stage What loads Cost
Discovery name and description only, for every installed skill ~100 tokens per skill
Activation The full SKILL.md body, when a task matches Recommended under 5,000 tokens
Execution Files in scripts/, references/, assets/ Only when the instructions call for them

This is the single most important thing to understand about the format, because it explains the two rules that otherwise look arbitrary.

Why the description carries so much weight. At discovery time it's the only thing the agent sees. It is not a summary for humans; it is the entire basis on which the agent decides whether to read the rest.

Why SKILL.md should stay short. The spec recommends keeping it under 500 lines and moving detail into references/. A long body isn't just untidy — it's loaded in full the moment the skill activates.

What's standardised, and what isn't

Here is where the specification stops and reality starts. Every runtime that implements the standard adds things, and those additions are the reason a "portable" skill sometimes isn't.

Where skills live is not standardised at all

The spec says nothing about directories. Every runtime chose its own, and the results are genuinely different:

Runtime Roots Notable
Claude Code ~/.claude/skills/, .claude/skills/, plugin skills, enterprise settings Documented precedence chain; nested project scoping
Codex $HOME/.agents/skills, .agents/skills up the project chain Also scans ~/.codex/skills, which its own source marks deprecated
Cursor Eight roots Reads .claude/skills/ and .codex/skills/ for compatibility
OpenClaw Six roots, in a documented precedence order Explicitly refuses Codex's root; offers a migration command instead
Hermes Agent ~/.hermes/skills/ plus configured external_dirs Category-organised

One convention has emerged from the bottom up rather than from the spec: .agents/skills is read natively by Codex, Cursor and OpenClaw. A skill kept there is shared across three runtimes with no copying. That's the closest thing to a portable location the ecosystem has.

Full detail per runtime is in each cluster: Claude Code, Codex, Cursor, OpenClaw, Hermes.

The context budget is not standardised

Discovery costs tokens, so runtimes cap the index — with different numbers, and one publishing none:

Runtime Documented budget
Codex 2% of the context window or 8,000 characters, whichever is smaller
Claude Code Approximately 1% of context
OpenClaw ~97 characters per skill plus field lengths, against a configurable ceiling; degrades by shortening then dropping descriptions
Cursor None published

This is why description-length advice varies so widely. The spec permits 1,024 characters; OpenClaw's own authoring guide asks for under 160; practical reports in Claude Code suggest under 200 when running many skills. All three are correct for their runtime.

Invocation is not standardised

Runtime Explicit invocation
Claude Code, Cursor /skill-name
Codex $skill-name in the CLI and IDE; @skill-name in ChatGPT
OpenClaw $name as a composable reference in a message, /name as a standalone command, up to eight per message

Automatic invocation — the agent choosing a skill from its description — exists everywhere, but the control for turning it off is spelled differently in each: disable-model-invocation in Cursor, OpenClaw and Claude Code; policy.allow_implicit_invocation in Codex's agents/openai.yaml.

Name collisions are not standardised

Install the same skill name twice and behaviour diverges sharply. Claude Code applies a precedence chain (enterprise over personal over project). OpenClaw takes the highest-priority root. Codex shows both, without merging. Cursor documents nothing.

Runtime-specific frontmatter

Each runtime extends the format. These fields work at home and travel nowhere:

Field Runtime What it does
paths Cursor Scopes a skill to files matching glob patterns — triggering on files touched rather than on phrasing
metadata.openclaw.requires / os / install OpenClaw Dependency gating; a skill hides when its binary, env var or platform is absent
command-dispatch: tool OpenClaw The slash command bypasses the model entirely
agents/openai.yaml Codex UI metadata, invocation policy, MCP dependencies
context: fork Claude Code The skill runs as a forked subagent
metadata.hermes.requires_toolsets Hermes Agent Conditional activation against available toolsets

Most of these degrade harmlessly — another runtime ignores what it doesn't recognise. One does not. Adding Cursor's paths field to a skill in Claude Code makes it entirely undiscoverable, per a public issue read to resolution. That is the sharpest portability trap in the format, and it's invisible from either vendor's documentation alone.

Validating a skill

The standard ships a reference library for checking frontmatter and naming conventions:

skills-ref validate ./my-skill

It checks the format, not the behaviour. Whether the description actually triggers is a separate question with its own method.

What SKILL.md is not

Three distinctions that account for most of the confusion around the format:

Not a persistent instruction file. AGENTS.md, CLAUDE.md and Cursor rules load on every task; a skill loads when it's relevant. The difference is context cost, and it's the whole basis for choosing between them — see Codex skills vs AGENTS.md and Cursor skills vs rules.

Not an MCP server. MCP gives an agent access to a system; a skill gives it the judgement to use that access well. They are complementary layers, and there is now a standard that packages both together — Agent Skills vs MCP.

Not a plugin. A plugin is an envelope. It may contain skills, MCP servers, both, or neither — many published plugins contain no skills at all.

Caveats

  • We have not run any of these runtimes. Everything here is the published specification or documented runtime behaviour, with per-runtime detail carried from the research behind each cluster.
  • The standard's origin date is not stated here. Secondary sources give conflicting dates and we could not confirm either against a primary source; rather than pick one, we've left it out.
  • Runtime behaviour, budgets and field sets are as documented on 16 August 2026. These products ship frequently, and the divergences above are the fastest-moving part of this page.

Sources

Where the format meets real runtimes