1# Specification
2
3This document defines the Agent Skills format.
4
5## Contents
6
7- [Directory structure](#directory-structure)
8- [SKILL.md format](#skillmd-format)
9 - [Frontmatter (required)](#frontmatter-required)
10 - [Body content](#body-content)
11- [Optional directories](#optional-directories)
12- [Progressive disclosure](#progressive-disclosure)
13- [File references](#file-references)
14- [Validation](#validation)
15
16## Directory structure
17
18A skill is a directory containing at minimum a `SKILL.md` file:
19
20```
21skill-name/
22└── SKILL.md # Required
23```
24
25<Tip>
26 You can optionally include [additional directories](#optional-directories) such as `scripts/`, `references/`, and `assets/` to support your skill.
27</Tip>
28
29## SKILL.md format
30
31The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.
32
33### Frontmatter (required)
34
35```yaml
36---
37name: skill-name
38description: A description of what this skill does and when to use it.
39---
40```
41
42With optional fields:
43
44```yaml
45---
46name: pdf-processing
47description: Extract text and tables from PDF files, fill forms, merge documents.
48license: Apache-2.0
49metadata:
50 author: example-org
51 version: "1.0"
52---
53```
54
55| Field | Required | Constraints |
56| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
57| `name` | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. |
58| `description` | Yes | Max 1024 characters. Non-empty. Describes what the skill does and when to use it. |
59| `license` | No | License name or reference to a bundled license file. |
60| `compatibility` | No | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). |
61| `metadata` | No | Arbitrary key-value mapping for additional metadata. |
62| `allowed-tools` | No | Space-delimited list of pre-approved tools the skill may use. (Experimental) |
63
64#### `name` field
65
66The required `name` field:
67
68- Must be 1-64 characters
69- May only contain unicode lowercase alphanumeric characters and hyphens (`a-z` and `-`)
70- Must not start or end with `-`
71- Must not contain consecutive hyphens (`--`)
72- Must match the parent directory name
73
74Valid examples:
75
76```yaml
77name: pdf-processing
78```
79
80```yaml
81name: data-analysis
82```
83
84```yaml
85name: code-review
86```
87
88Invalid examples:
89
90```yaml
91name: PDF-Processing # uppercase not allowed
92```
93
94```yaml
95name: -pdf # cannot start with hyphen
96```
97
98```yaml
99name: pdf--processing # consecutive hyphens not allowed
100```
101
102#### `description` field
103
104The required `description` field:
105
106- Must be 1-1024 characters
107- Should describe both what the skill does and when to use it
108- Should include specific keywords that help agents identify relevant tasks
109
110Good example:
111
112```yaml
113description: 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.
114```
115
116Poor example:
117
118```yaml
119description: Helps with PDFs.
120```
121
122#### `license` field
123
124The optional `license` field:
125
126- Specifies the license applied to the skill
127- We recommend keeping it short (either the name of a license or the name of a bundled license file)
128
129Example:
130
131```yaml
132license: Proprietary. LICENSE.txt has complete terms
133```
134
135#### `compatibility` field
136
137The optional `compatibility` field:
138
139- Must be 1-500 characters if provided
140- Should only be included if your skill has specific environment requirements
141- Can indicate intended product, required system packages, network access needs, etc.
142
143Examples:
144
145```yaml
146compatibility: Designed for Claude Code (or similar products)
147```
148
149```yaml
150compatibility: Requires git, docker, jq, and access to the internet
151```
152
153<Note>
154 Most skills do not need the `compatibility` field.
155</Note>
156
157#### `metadata` field
158
159The optional `metadata` field:
160
161- A map from string keys to string values
162- Clients can use this to store additional properties not defined by the Agent Skills spec
163- We recommend making your key names reasonably unique to avoid accidental conflicts
164
165Example:
166
167```yaml
168metadata:
169 author: example-org
170 version: "1.0"
171```
172
173#### `allowed-tools` field
174
175The optional `allowed-tools` field:
176
177- A space-delimited list of tools that are pre-approved to run
178- Experimental. Support for this field may vary between agent implementations
179
180Example:
181
182```yaml
183allowed-tools: Bash(git:*) Bash(jq:*) Read
184```
185
186### Body content
187
188The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.
189
190Recommended sections:
191
192- Step-by-step instructions
193- Examples of inputs and outputs
194- Common edge cases
195
196Note 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.
197
198## Optional directories
199
200### scripts/
201
202Contains executable code that agents can run. Scripts should:
203
204- Be self-contained or clearly document dependencies
205- Include helpful error messages
206- Handle edge cases gracefully
207
208Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript.
209
210### references/
211
212Contains additional documentation that agents can read when needed:
213
214- `REFERENCE.md` - Detailed technical reference
215- `FORMS.md` - Form templates or structured data formats
216- Domain-specific files (`finance.md`, `legal.md`, etc.)
217
218Keep individual [reference files](#file-references) focused. Agents load these on demand, so smaller files mean less use of context.
219
220### assets/
221
222Contains static resources:
223
224- Templates (document templates, configuration templates)
225- Images (diagrams, examples)
226- Data files (lookup tables, schemas)
227
228## Progressive disclosure
229
230Skills should be structured for efficient use of context:
231
2321. **Metadata** (\~100 tokens): The `name` and `description` fields are loaded at startup for all skills
2332. **Instructions** (\< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated
2343. **Resources** (as needed): Files (e.g. those in `scripts/`, `references/`, or `assets/`) are loaded only when required
235
236Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files.
237
238## File references
239
240When referencing other files in your skill, use relative paths from the skill root:
241
242```markdown
243See [the reference guide](references/REFERENCE.md) for details.
244
245Run the extraction script:
246scripts/extract.py
247```
248
249Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
250
251## Validation
252
253Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate your skills:
254
255```bash
256skills-ref validate ./my-skill
257```
258
259This checks that your `SKILL.md` frontmatter is valid and follows all naming conventions.