Agent Skills specification

The format behind “skills”. A skill is a folder with a SKILL.md file: YAML frontmatter with a name and a description, then Markdown instructions. It can also hold scripts/, references/ and assets/. Agents read only the name and description until a task matches, then load the rest.

Anthropic first developed the format and then published it as an open standard. The spec site’s client list now includes ChatGPT & Codex, Claude, Claude Code, Gemini CLI, Cursor, GitHub Copilot, VS Code and 40+ others.

When to use it

• You’re writing a skill and want it to work in more than one agent.
• You’re checking a skill someone sent you: a valid name is 1–64 lowercase letters, numbers and hyphens, matches its folder, and the description is 1,024 characters or less.
• You’re adding skill support to your own agent (see “Client implementation” in the docs).

Where each agent looks for skills

Agent	Project	User
Codex	.agents/skills/ (current dir up to repo root)	~/.agents/skills/
Gemini CLI	.agents/skills/ or .gemini/skills/	~/.agents/skills/ or ~/.gemini/skills/
Cursor	.agents/skills/ or .cursor/skills/ (also reads .claude/skills/, .codex/skills/)	~/.agents/skills/, ~/.cursor/skills/

.agents/skills/ works in all three. Taken from each vendor’s docs on 2026-09-25.

Before you rely on it

Only name and description are required, and each product adds its own optional fields. Codex reads agents/openai.yaml; Cursor adds fields like paths and disable-model-invocation. A skill that depends on those fields won’t behave the same everywhere. allowed-tools is still marked experimental.