Skill Specification

Complete technical specification for the Agent Skills format. SKILL.md structure, YAML frontmatter fields, directory layout, file references, and validation rules.

Directory Structure

A skill is a directory that must include a SKILL.md file:

skill-name/
└── SKILL.md          # Required

SKILL.md Format

The SKILL.md file has two parts: YAML frontmatter (metadata) followed by Markdown content (instructions).

Frontmatter

The frontmatter block is at the top of the file between --- delimiters:

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

With optional fields:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Required Fields

Field	Rules
name	Max 64 characters. Only lowercase letters, numbers, and hyphens are allowed. Cannot start or end with a hyphen. No consecutive hyphens. Must match the parent directory name.
description	Max 1,024 characters. Cannot be empty. Should describe what the skill does and when to use it.

Optional Fields

Field	Rules
license	License name or reference to a bundled license file.
compatibility	Max 500 characters. Indicates environment requirements like intended product, system packages, and network access.
metadata	Key-value pairs for extra properties like author and version.
allowed-tools	Space-separated list of pre-approved tools the skill can use. (Experimental; support varies between agents.)

Name Field Rules

The name field identifies your skill and has strict formatting requirements:

1–64 characters long
Only lowercase letters, numbers, and hyphens (a-z, 0-9, -)
Cannot start or end with a hyphen
No consecutive hyphens (--)
Must match the folder name containing the skill

name: pdf-processing
name: data-analysis
name: code-review
name: seo-blog-writer

Description Field Guidelines

The description field tells AI agents when to activate your skill, so it should be clear and include relevant keywords.

Effective descriptions:

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.

description: Generate descriptive commit messages by analyzing git diffs. Use when
the user asks for help writing commit messages or reviewing staged changes.

Avoid vague descriptions like "Helps with PDFs", "Processes data", or "Does stuff with files." These reduce discoverability and make it hard for AI agents to decide when to use your skill.

Always write descriptions in third person: "Processes Excel files" instead of "I can help you process Excel files."

Body Content

The Markdown body after the frontmatter contains your skill's instructions. There are no format restrictions — write anything that helps AI agents perform the task well.

Progressive Disclosure

Organize your skills for efficient context usage:

Metadata (~100 tokens)

The name and description load at startup for all skills.

Instructions (under 5,000 tokens recommended)

The complete SKILL.md body loads when the skill activates.

Resources (as needed)

Files in scripts/, references/, or assets/ load only when necessary.

Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files.

File References

When referencing other files in your skill, use relative paths from the skill root:

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains where one reference file points to another reference file, as agents may not reliably follow multi-level chains.

File Requirements for Skill

Property	Requirement
Format	`.md` (Markdown)
Encoding	UTF-8
Size	Under 100KB (most skills are 1–10KB)
Language	English recommended for widest reach

Validation

You can validate your skills using the official reference library:

skills-ref validate ./my-skill

This checks that your SKILL.md frontmatter is valid and follows all naming conventions. The reference library is available at github.com/agentskills/agentskills.