What are Agent Skills?
Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. The format is standardized at agentskills.io and supported by 27+ AI agents.
The SKILL.md Format
At its core, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials.
Frontmatter Fields
Every SKILL.md file starts with YAML frontmatter. Two fields are required; the rest are optional.
| Field | Required | Description |
|---|---|---|
| name | Yes | Max 64 chars. Lowercase letters, numbers, hyphens. |
| description | Yes | Max 1024 chars. What the skill does and when to use it. |
| license | No | License name or reference to a bundled license file. |
| compatibility | No | Environment requirements: intended product, packages, network access. |
| metadata | No | Arbitrary key-value pairs for additional properties. |
| allowed-tools | No | Space-delimited list of pre-approved tools. Experimental. |
Progressive Disclosure
Skills are designed for efficient context management. Agents don’t load everything at once:
Discovery
At startup, agents load only the name and description of each available skill (~100 tokens). Just enough to know when a skill might be relevant.
~100 tokensActivation
When a task matches a skill's description, the agent reads the full SKILL.md instructions into context.
<5000 tokensExecution
The agent follows instructions, loading referenced files or executing bundled scripts only as needed.
As neededSkills vs Rules vs AGENTS.md
These three are often confused. Here’s the distinction:
| Concept | Purpose | Loaded |
|---|---|---|
| Rules | “Always do this” — universal project constraints | Every prompt |
| AGENTS.md | “How this project works” — build steps, conventions | Every prompt |
| Skills | “How to do this task” — modular capabilities | On demand |
The key test: Would you want this applied to every single task? If yes, it’s a rule. If no, it’s a skill. “Never commit .env files” is a rule. “How to generate release notes in our format” is a skill.
Adoption
The Agent Skills format was originally developed by Anthropic, released as an open standard, and adopted by a growing ecosystem of AI development tools. Compatible agents include Claude Code, Cursor, OpenAI Codex, Gemini CLI, VS Code, GitHub Copilot, Amp, Roo Code, Goose, and many more.