Agent Skills (SKILL.md): The Open Standard Explained

Agent skills are how you teach an AI agent a job once and have it remember: a folder of instructions the agent loads when the job comes up. Because the format is an open standard, the same folder works in Claude, Codex, Cursor, Copilot and dozens of other agents, so a skill you write today keeps working when you switch tools.

The format in one minute

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

SKILL.md starts with YAML frontmatter. Only two fields are required (specification):

Field	Required	Rules
name	Yes	1–64 characters: lowercase letters, numbers and hyphens; no leading, trailing or double hyphens; must match the folder name
description	Yes	1–1,024 characters: what the skill does and when to use it
license	No	A licence name or a bundled licence file
compatibility	No	Up to 500 characters on environment needs (product, packages, network)
metadata	No	String key-value pairs, such as author and version
allowed-tools	No	Pre-approved tools, e.g. Bash(git:*) Read (experimental; support varies)

The spec’s own example:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Instructions follow in plain Markdown. You can check a skill against the spec with the reference validator, skills-ref validate ./my-skill (agentskills/agentskills).

Why skills don’t clog the context window

Agents use progressive disclosure (agentskills.io):

1. Discovery: only each skill’s name and description load at startup (about 100 tokens each).
2. Activation: when a task matches, the agent reads the full SKILL.md (the spec suggests under 5,000 tokens and 500 lines).
3. Execution: scripts, references and assets load only if the instructions call for them.

So a library of fifty skills costs a few thousand tokens until one is used.

Who supports it

Tool	Where it reads skills	Source
Claude apps	Upload a ZIP in Customize > Skills	Help Center
Claude Code	~/.claude/skills/, .claude/skills/	Docs
OpenAI Codex and ChatGPT	.agents/skills/, ~/.agents/skills/	OpenAI
Cursor	.cursor/skills/, .agents/skills/, plus .claude/skills/	Cursor
GitHub Copilot	.github/skills, .claude/skills, .agents/skills	GitHub
Gemini CLI	.gemini/skills/, .agents/skills/	Gemini CLI

agentskills.io lists about 40 more clients, including OpenClaw, Goose, OpenCode, Roo Code, Kiro, Amp, Junie and Hermes Agent. The safest portable location is .agents/skills/, which Codex, Cursor, Copilot and Gemini CLI all read.

Product-specific extras sit on top of the standard: Claude Code adds fields such as disable-model-invocation and context, and Codex reads an optional agents/openai.yaml for display names and invocation policy. Agents ignore fields they don’t know, so extras don’t break portability.

A short history

Date	What happened
16 Oct 2025	Anthropic launches skills in the Claude apps, Claude Code and the API (Anthropic)
18 Dec 2025	Anthropic publishes Agent Skills as an open standard, with org-wide skill provisioning and a partner directory (Anthropic)
Dec 2025	OpenAI Codex adopts SKILL.md (reported by secondary sources; no dated OpenAI changelog found)
20 Jan 2026	Vercel launches the skills CLI and the skills.sh directory (Vercel)
Feb 2026	Security researchers find malicious skills on OpenClaw’s ClawHub registry (below)

Skills vs MCP servers vs prompts

	What it gives the agent	Example
Prompt	One-off instructions in this chat	“Summarise this in three bullets”
Skill	Reusable know-how, loaded when needed	“How we write release notes, with our template”
MCP server	Tools and live data	A connection to your CRM, calendar or database

The strongest setups pair them: an MCP server connects the agent to n8n or your CRM, and a skill tells it how your team uses them.

Safety: read before you install

A skill can include scripts, so installing one is like installing software. In February 2026, Koi Security found 341 malicious skills among 2,857 on OpenClaw’s ClawHub, most dropping a macOS password stealer (The Hacker News). Snyk scanned 3,984 skills from ClawHub and skills.sh and found at least one security flaw in 36.82% of them (Snyk). ClawHub has since added VirusTotal scanning, which OpenClaw itself calls “not a silver bullet” (OpenClaw).

The rules: install from sources you trust (your own, Anthropic’s, well-known repos), read every script, and be wary of skills that fetch URLs or ask for credentials.

Where to go next

• Claude skills: using skills in the Claude app
• Claude Code skills: installing and writing them for coding
• Codex skills: the OpenAI version
• The skills hub: free sources and marketplaces