The SKILL.md file format

The front matter fields, the rules a skill must pass to load, and the limits on its size.

ReferenceDeveloperChecked 2026-10-10

A skill is a file at skills/<area>/<name>/SKILL.md. It starts with YAML front matter between --- lines, then the instructions in Markdown. The layout follows the open Agent Skills format. Skills are written by Adapt Leads, so this page is for reading the shelf, not for uploading.

Top-level fields

Field	Required	Rule
`name`	Yes	Lower-case letters, digits and hyphens, 64 characters at most, and the same as the folder name
`description`	Yes	What it does and when to use it. 1,024 characters at most
`metadata`	Yes	A map of the fields below. Every value is a string

Other top-level fields from the standard (license, compatibility, allowed-tools) may appear. Any other field is refused.

Metadata fields

Field	Values	Meaning
`area`	The folder above the skill's own	`agents`, `platform-help`, `workflows` and so on
`shelf`	`public` or `private`	Public skills are about operating Adapt Leads. Private ones stay on our servers
`tools`	Space-separated tool names	Every tool the skill may call
`approval`	`none` or `card`	`none`: the skill can only read. `card`: it may call prepare tools, and each makes a card you approve
`task`	`write`, `work` or `answer`	The kind of AI task, which decides which helper does it
`max_rounds`	1 to 8	Rounds with tools in one run
`cap_usd_run`	A number above 0, at most the hard ceiling	The most one run may cost, in US dollars
`max_cards`	0 to 10	Approval cards one run may make
`version`	Any short string	A change to the file changes its hash, which is recorded with each run

Example front matter

---
name: answer-a-question
description: Answers a question about how Adapt Leads works from the help pages, and says plainly when the help does not cover it.
metadata:
  area: platform-help
  shelf: public
  tools: "search_help"
  approval: none
  task: answer
  max_rounds: "3"
  cap_usd_run: "0.03"
  max_cards: "0"
  version: "1"
---

What the loader refuses

A refused skill never loads, so it never runs.

A tool that does not exist, or whose name reads as deleting or cancelling.
A prepare tool listed under approval: none, or with max_cards of 0.
A name that does not match its folder, or an unknown field.
A body that names a data source.
A body over 20,000 characters.
A tool listed twice.

The body

The instructions follow the front matter. Ours start with a voice line, then numbered steps, then a short "Never" list. The code checks the rules that matter, so the instructions say "do not work around that" rather than relying on the model.