Agent Skills Specification: Portable SKILL.md Format for AI Agents

The Agent Skills specification defines a portable, directory-based format for packaging AI agent capabilities. If you build or maintain agent skills that need to work across different agent products, this is the standard you follow. It covers the required SKILL.md file, optional directories for scripts and references, naming rules, and validation.

What it does

The specification gives you a single, predictable way to describe what a skill does, how an agent should use it, and what files it needs. An agent product reads the SKILL.md frontmatter at startup to learn which skills are available, then loads the full instructions only when a task activates the skill. This progressive loading keeps context usage low while still making detailed instructions accessible on demand.

Before you start

• A skill is a directory. At minimum it must contain a SKILL.md file.
• The name field in frontmatter must match the parent directory name exactly.
• Names are restricted to lowercase letters, numbers, and hyphens. No consecutive hyphens, no leading or trailing hyphens.
• The description field is required and must be 1-1024 characters.
• For validation, install the skills-ref library.

Directory structure

A skill directory looks like this:

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

You can add any other files or directories you need. The spec only mandates SKILL.md.

SKILL.md format

The file starts with YAML frontmatter (between --- delimiters) followed by Markdown body content.

Frontmatter fields

Field	Required	Constraints
name	Yes	Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen.
description	Yes	Max 1024 characters. Non-empty. Describes what the skill does and when to use it.
license	No	License name or reference to a bundled license file.
compatibility	No	Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.).
metadata	No	Arbitrary key-value mapping for additional metadata.
allowed-tools	No	Space-separated string of pre-approved tools the skill may use. (Experimental)

Minimal example:

---
name: skill-name
description: A description of what this skill does and when to use it.
---

Example with optional fields:

---
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"
---

name field

The required name field:

• Must be 1-64 characters
• May only contain unicode lowercase alphanumeric characters (a-z, 0-9) and hyphens (-)
• Must not start or end with a hyphen (-)
• Must not contain consecutive hyphens (--)
• Must match the parent directory name

Valid examples:

name: pdf-processing

name: data-analysis

name: code-review

Invalid examples:

name: PDF-Processing  # uppercase not allowed

name: -pdf  # cannot start with hyphen

name: pdf--processing  # consecutive hyphens not allowed

description field

The required description field:

• Must be 1-1024 characters
• Should describe both what the skill does and when to use it
• Should include specific keywords that help agents identify relevant tasks

Good example:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

Poor example:

description: Helps with PDFs.

license field

The optional license field:

• Specifies the license applied to the skill
• We recommend keeping it short (either the name of a license or the name of a bundled license file)

Example:

license: Proprietary. LICENSE.txt has complete terms

compatibility field

The optional compatibility field:

• Must be 1-500 characters if provided
• Should only be included if your skill has specific environment requirements
• Can indicate intended product, required system packages, network access needs, etc.

Examples:

compatibility: Designed for Claude Code (or similar products)

compatibility: Requires git, docker, jq, and access to the internet

compatibility: Requires Python 3.14+ and uv

Most skills do not need the compatibility field.

metadata field

The optional metadata field:

• A map from string keys to string values
• Clients can use this to store additional properties not defined by the Agent Skills spec
• We recommend making your key names reasonably unique to avoid accidental conflicts

Example:

metadata:
  author: example-org
  version: "1.0"

allowed-tools field

The optional allowed-tools field:

• A space-separated string of tools that are pre-approved to run
• Experimental. Support for this field may vary between agent implementations

Example:

allowed-tools: Bash(git:*) Bash(jq:*) Read

Body content

The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.

Recommended sections:

• Step-by-step instructions
• Examples of inputs and outputs
• Common edge cases

Note that the agent will load this entire file once it's decided to activate a skill. Consider splitting longer SKILL.md content into referenced files.