ToolingPublished ExplainedAll news from that day
How an agent loads a skill in three steps
A skill is a folder with one required SKILL.md file; the agent reads a short description of each skill at start-up and opens the rest only when a task needs it.
Check our sources · 15 facts from 2 sources
Illustration made with AI for ai notis
Key points
- A skill is a directory with at least a SKILL.md file holding YAML frontmatter and Markdown. The name (1-64 characters) and description (1-1024 characters) fields are required.
- The specification has three levels: name and description (about 100 tokens) at startup, instructions of under 5000 tokens, as recommended, when a skill is activated, and resources as needed.
- The specification says to keep SKILL.md under 500 lines, move detail to files in scripts/, references/ or assets/, and keep file references one level deep from SKILL.md.
What happened
A skill is a directory that contains, at minimum, a file called SKILL.md. That file holds YAML frontmatter followed by Markdown instructions. The frontmatter has two required fields. The name is at most 64 characters, uses only lowercase letters, numbers and hyphens, and must match the parent directory name.
The description is at most 1024 characters and should say both what the skill does and when to use it. Four fields are optional: license, compatibility (at most 500 characters, for environment needs), metadata (a map of string keys to string values) and allowed-tools, which is experimental.
The Markdown body has no format restrictions. A skill folder may also hold scripts for executable code, references for extra documentation that the agent reads when needed, and assets for templates, images and data files. The specification describes progressive disclosure in three levels.
At start-up the agent loads the name and description of all skills, labelled about 100 tokens. When a skill is activated the full SKILL.md body is loaded, and the specification recommends under 5,000 tokens. Files in scripts, references and assets are loaded only when required.
The specification suggests keeping SKILL.md under 500 lines and moving detail into separate files, one level deep. A reference library, skills-ref, can validate a skill's frontmatter. Anthropic said on 22 October 2026 that it is donating the standard to the Agentic AI Foundation.
Underlined sentences link to the facts we checked. Dotted words open a short explainer.
Fact 1 of 15 · from Agent Skills project
A skill is a directory containing, at minimum, a SKILL.md file
Fact 9 of 15 · from Agent Skills project
The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions.
Fact 10 of 15 · from Agent Skills project
scripts/ Contains executable code that agents can run. ... references/ Contains additional documentation that agents can read when needed ... assets/ Contains static resources: Templates ... Images ... Data files
What it means for you
Our viewThe format rewards a short, precise description, because the name and description are the only parts loaded for every skill at start-up, and the specification says it should state what the skill does and when to use it.
Keep the instructions in SKILL.md compact and put detail in separate reference files, so the agent reads them only when a task needs them. The allowed-tools field is marked experimental in the specification, so avoid building a workflow on it yet.
To check a skill you have written, run skills-ref validate on it, then read the description and ask whether it says when the skill should be used.
It adds no new facts.
Your reaction
We count reactions per story and day, never who reacted. The counts help us choose what goes in the monthly issue. If you are signed in, your own page shows yours too.
We count reactions per story and day, never who reacted. They help choose what goes in the monthly issue.
Check our sources
Every sentence above is checked against these 2 sources.
1 Agent Skills specification
Open the source archived copy-
A skill is a directory containing, at minimum, a SKILL.md file.
citeA skill is a directory containing, at minimum, a SKILL.md file
-
The SKILL.md file must contain YAML frontmatter followed by Markdown content.
citeThe SKILL.md file must contain YAML frontmatter followed by Markdown content.
-
The name field is required, must be 1-64 characters, may contain only lowercase alphanumeric characters and hyphens, must not start or end with a hyphen, and must match the parent directory name.
citeThe 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
-
The description field is required, must be 1-1024 characters, and should describe both what the skill does and when to use it.
citeThe required description field: Must be 1-1024 characters Should describe both what the skill does and when to use it
-
The optional fields are license, compatibility, metadata and allowed-tools.
citelicenseNoLicense name or reference to a bundled license file. compatibilityNoMax 500 characters. ... metadataNoArbitrary key-value mapping ... allowed-toolsNoSpace-separated string of pre-approved tools the skill may use. (Experimental)
-
The compatibility field must be 1-500 characters if provided and can indicate intended product, required system packages or network access needs.
citeThe optional compatibility field: Must be 1-500 characters if provided ... Can indicate intended product, required system packages, network access needs, etc.
-
The metadata field is a map from string keys to string values.
citeThe optional metadata field: A map from string keys to string values
-
The allowed-tools field is a space-separated string of pre-approved tools, and the specification marks it experimental.
citeThe 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
-
The Markdown body after the frontmatter has no format restrictions.
citeThe Markdown body after the frontmatter contains the skill instructions. There are no format restrictions.
-
A skill directory may contain scripts/ for executable code, references/ for additional documentation the agent can read when needed, and assets/ for static resources such as templates, images and data files.
citescripts/ Contains executable code that agents can run. ... references/ Contains additional documentation that agents can read when needed ... assets/ Contains static resources: Templates ... Images ... Data files
-
The specification's progressive disclosure has three levels: metadata of about 100 tokens (name and description) loaded at startup for all skills, instructions under 5000 tokens recommended loaded when the skill is activated, and resources loaded only as needed.
citeMetadata (~100 tokens): The name and description fields are loaded at startup for all skills Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required
-
The specification says to keep the main SKILL.md under 500 lines and move detailed reference material to separate files.
citeKeep your main SKILL.md under 500 lines. Move detailed reference material to separate files.
-
The specification says to keep file references one level deep from SKILL.md.
citeKeep file references one level deep from SKILL.md. Avoid deeply nested reference chains.
-
The specification names the skills-ref reference library for validating skills with the command skills-ref validate.
citeUse the skills-ref reference library to validate your skills: skills-ref validate ./my-skill
2 Donating Agent Skills to the Agentic AI Foundation
Open the source archived copy-
Anthropic's post of 22 October 2026 says it is donating Agent Skills to the Agentic AI Foundation.
cite
Every sentence above is checked against these 2 sources. Each fact has its own address you can cite.
Source 1 · Agent Skills project
Agent Skills specification
A skill is a directory containing, at minimum, a SKILL.md file.
A skill is a directory containing, at minimum, a SKILL.md file
The SKILL.md file must contain YAML frontmatter followed by Markdown content.
The SKILL.md file must contain YAML frontmatter followed by Markdown content.
The name field is required, must be 1-64 characters, may contain only lowercase alphanumeric characters and hyphens, must not start or end with a hyphen, and must match the parent directory name.
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
Show all 14 factsShow fewer facts
The description field is required, must be 1-1024 characters, and should describe both what the skill does and when to use it.
The required description field: Must be 1-1024 characters Should describe both what the skill does and when to use it
The optional fields are license, compatibility, metadata and allowed-tools.
licenseNoLicense name or reference to a bundled license file. compatibilityNoMax 500 characters. ... metadataNoArbitrary key-value mapping ... allowed-toolsNoSpace-separated string of pre-approved tools the skill may use. (Experimental)
The compatibility field must be 1-500 characters if provided and can indicate intended product, required system packages or network access needs.
The optional compatibility field: Must be 1-500 characters if provided ... Can indicate intended product, required system packages, network access needs, etc.
The metadata field is a map from string keys to string values.
The optional metadata field: A map from string keys to string values
The allowed-tools field is a space-separated string of pre-approved tools, and the specification marks it experimental.
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
The Markdown body after the frontmatter has no format restrictions.
The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions.
A skill directory may contain scripts/ for executable code, references/ for additional documentation the agent can read when needed, and assets/ for static resources such as templates, images and data files.
scripts/ Contains executable code that agents can run. ... references/ Contains additional documentation that agents can read when needed ... assets/ Contains static resources: Templates ... Images ... Data files
The specification's progressive disclosure has three levels: metadata of about 100 tokens (name and description) loaded at startup for all skills, instructions under 5000 tokens recommended loaded when the skill is activated, and resources loaded only as needed.
Metadata (~100 tokens): The name and description fields are loaded at startup for all skills Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required
The specification says to keep the main SKILL.md under 500 lines and move detailed reference material to separate files.
Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files.
The specification says to keep file references one level deep from SKILL.md.
Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains.
The specification names the skills-ref reference library for validating skills with the command skills-ref validate.
Use the skills-ref reference library to validate your skills: skills-ref validate ./my-skill
Source 2 · Anthropic · 22 Oct 2026
Donating Agent Skills to the Agentic AI Foundation
Anthropic's post of 22 October 2026 says it is donating Agent Skills to the Agentic AI Foundation.
Topics
The morning email
On the mornings we publish: the three top stories and up to four short ones. Free.
We email you a link to confirm. An issue may include one sponsor, always labelled Sponsored · Advertisement. Our emails count opens and clicks, not who made them. Unsubscribe in one click. What we keep