The Agent Skills Standard Explained (SKILL.md, 2026)

A skill you write for Claude Code can also run in Codex, Copilot, Cursor and a long list of other agents, because they all read the same SKILL.md format. That format is the Agent Skills open standard. This guide explains what the spec actually requires, how it keeps context small, and where Claude Code goes beyond it, so you know which skills will travel and which won’t.

Everything here is checked against the specification at agentskills.io and the official Claude Code skills docs as of October 2026.

Where the standard came from

Anthropic introduced Agent Skills in an engineering post in October 2025 and, per an update to that post dated 18 December 2025, published the format as an open standard “for cross-platform portability”. The specification and reference code now live at agentskills.io and the agentskills GitHub organisation, which the site describes as open to community contributions.

Anthropic’s own skills, such as the document skills behind pdf, docx and xlsx, live in the anthropics/skills repository, whose README points to agentskills.io for the standard itself.

Who supports it

The clients page lists dozens of products, including Claude Code and claude.ai, OpenAI Codex, GitHub Copilot in VS Code, Cursor, Gemini CLI, Goose, Amp, OpenCode, Roo Code and OpenHands. The list changes often, so check it rather than relying on a count.

Anatomy of a skill

A skill is a directory. Only SKILL.md is required:

pdf-report/
├── SKILL.md          # required: frontmatter + instructions
├── scripts/          # optional: code the agent can run
├── references/       # optional: docs loaded only when needed
└── assets/           # optional: templates, images, data

A minimal SKILL.md:

---
name: pdf-report
description: Builds a branded PDF report from a CSV. Use when the user asks for a report, summary PDF or export of tabular data.
license: MIT
---

# PDF report

1. Read the CSV and summarise each column.
2. Run scripts/build_report.py with the summary as JSON.
3. If the brand guide is needed, read references/brand.md.

The spec recommends keeping SKILL.md under 500 lines and referencing other files with relative paths one level deep.

The frontmatter fields the spec allows

Field	Required	Rules
name	Yes	1–64 chars; lowercase a-z, digits and -; no leading, trailing or double hyphen; must match the folder name
description	Yes	1–1024 chars; say what the skill does and when to use it
license	No	License name or a bundled license file
compatibility	No	1–500 chars on environment needs; the spec notes most skills don’t need it
metadata	No	String-to-string map for anything else
allowed-tools	No	Experimental; space-separated tools, e.g. Bash(git:*) Read

The description is the most important line you’ll write. Agents decide whether to load a skill from it, so put the trigger (“Use when the user asks for…”) in plain words.

Progressive disclosure: why skills are cheap

The standard is built around loading as little as possible:

Tier	What loads	When	Budget the spec suggests
Metadata	name + description	At startup, for every skill	About 100 tokens per skill
Instructions	SKILL.md body	When the skill is activated	Under 5,000 tokens recommended
Resources	scripts/, references/, assets/	Only when the instructions call for them	No fixed limit

Anthropic’s post compares this to a manual: table of contents first, then the chapter, then the appendix. In practice, it means you can install many skills without filling the context window. Our context management guide shows how to check what’s loaded in Claude Code.

Validating a skill

The reference library, skills-ref, has a validator:

git clone https://github.com/agentskills/agentskills
cd agentskills/skills-ref
pip install -e .        # or: uv sync
skills-ref validate ./path/to/pdf-report

It also offers read-properties and to-prompt. Its README says it is “intended for demonstration purposes only” and not for production, so treat it as a lint pass, not a gate. It isn’t published as a package; install from source as above.

What Claude Code adds on top

Claude Code follows the standard and, in its docs’ words, extends it with “invocation control, subagent execution, and dynamic context injection”. The extra frontmatter includes:

Claude Code field	What it does
disable-model-invocation	Only you can run the skill (as /name), Claude won’t auto-load it
user-invocable	Hide it from the / menu but let Claude use it
argument-hint, arguments	Document and name arguments for /name arg
context: fork, agent	Run the skill in a forked subagent context
model, effort	Override model or effort for the skill
paths	Only offer the skill when matching files are involved
hooks	Attach hooks scoped to the skill
when_to_use, disallowed-tools, background, shell	Extra routing and tool control

The body can use $ARGUMENTS, $0/$1, ${CLAUDE_SKILL_DIR} and !`command` injection. In Claude Code every field is optional; if name is missing, the folder name is used. The full walkthrough is in our Claude Code skills guide, and custom commands are covered in the slash commands cheatsheet.

The portability trap

Those extensions are where cross-tool sharing breaks. Claude Code’s docs note that when you upload a skill to claude.ai or the Skills API, only the six spec fields are accepted, and an unknown key fails with an error like:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Other clients may silently ignore fields they don’t know, which can be worse: a skill you marked disable-model-invocation could auto-load elsewhere.

Writing skills that travel

1. Stick to spec fields in skills you publish. Keep Claude Code extras in a separate, Claude-only skill if you need them.
2. Name the folder and name identically, lowercase with hyphens.
3. Put the trigger in description, not just a summary.
4. Avoid tool-specific instructions like “use the Task tool”. Describe the outcome (“delegate the search to a subagent if available”).
5. Make scripts self-contained: state dependencies in compatibility, and fail with clear messages.
6. Validate with skills-ref validate before you share.

Where to find standard skills

• Anthropic’s repo: add it in Claude Code with /plugin marketplace add anthropics/skills. Browse examples such as skill-creator and mcp-builder in our directory.
• Our roundup of the best Claude Code skills.
• If you’re deciding whether something should be a skill at all, read skills vs subagents vs hooks.

Skills in your Claude kit

Skills are the most portable layer of a Claude kit: CLAUDE.md and hooks are Claude Code-specific, but a spec-clean skill moves with you to Codex or Copilot. That’s why multi-runtime kits are built mostly from skills; our Claude Code vs Codex comparison covers how the two tools load them.