What is a skill?

Agent Skills is an open, lightweight format for extending the capabilities of AI agents with specialized knowledge and workflows.

 

Essentially, a skill is a directory containing a SKILL.md file. This file includes metadata (name and description, at a minimum) and instructions on how the agent should perform a specific task. Skills may also include scripts, templates, and references.

my-skill/ ├── SKILL.md # Required: instructions + metadata ├── scripts/ # Optional: executable code ├── references/ # Optional: documentation └── assets/ # Optional: templates, resources

How the skill works

Skill uses a gradual revelation method to effectively manage context:

1. Discovery : Upon startup, agents only upload the name and description of each available skill, just enough to know when it might be relevant.
2. Activation : When a task matches the skill description, the agent reads the entire SKILL.md instruction into context.
3. Execution : The agent follows the instructions, optionally loading referenced files or executing packaged code as needed.

This approach allows agents to operate quickly while also providing them with access to more context as needed.

File SKILL.md

Each skill begins with a SKILL.md file containing the YAML header and Markdown instructions :

--- name: pdf-processing description: Extract PDF text, fill forms, merge files. Use when handling PDFs. --- # PDF Processing ## When to use this skill Use this skill when the user needs to work with PDF files. ## How to extract text 1. Use pdfplumber for text extraction. ## How to fill forms .

The following introductory section is required at the beginning of the SKILL.md file:

1. Name: A short identifier
2. Description: When should you use this skill?

The Markdown body contains practical instructions and has no specific restrictions on structure or content.

This simple format has several key advantages:

1. Self-documentation : Skill creators or users can read the SKILL.md file and understand what it does, making it easier to test and improve the skill.
2. Scalable : Skills can range in complexity from simple written instructions to executable code, assets, and templates.
3. Easy to move : Skills are just files, so they are easy to edit, version, and share.