A recurring task, such as adding a newly discovered book to a reading list, can be captured once as a skill instead of being re-specified each time. Agent Skills is an open, framework-independent standard for packaging these reusable workflows so compatible LLM agent clients can discover and use them. section 6.0 section 1.5
Tools provide discrete functionality; a skill describes the procedure for completing a task, typically using one or more tools. A skill bundle contains a SKILL.md workflow and may include executable scripts, reference documents, and other assets. section 6.1.1 section 6.1.2
A skill bundle has these components:
- SKILL.md: YAML frontmatter followed by the procedural workflow. The required frontmatter fields are name and description. section 6.1.2
- Optional frontmatter: license, compatibility, metadata, and allowed-tools can provide additional information about use and requirements. section 6.1.2
- Optional resources: scripts/, references/, and assets/ live alongside SKILL.md. The workflow can reference resources when they are needed; resource files should avoid deep nesting. section 6.1.2
Table 6.1 Fields that can be included in a skill’s frontmatter
|
Field
|
Required
|
Description
|
|
name
|
Yes
|
A unique
identifier for the skill. Must be lowercase letters, numbers, and hyphens
only. Cannot start or end with a hyphen. Maximum 64 characters.
|
|
description
|
Yes
|
Describes
what the skill’s procedural workflow does and in what scenarios it should be
applied. Maximum 1024 characters.
|
|
license
|
No
|
The name of
the license that covers the skill (e.g. MIT) or the name of the license file
that is bundled in the skills resources.
|
|
compatibility
|
No
|
Describes
any environment constraints or requirements the skill has. Maximum 500
characters.
|
|
metadata
|
No
|
An
arbitrary key-value map for additional properties not covered by the
standard, like author or version.
|
|
allowed-tools
|
No
|
A
space-delimited list of tools (each specified by name) the LLM agent can use
to execute the skill.
|
The frontmatter field table gives the required fields, optional fields, and their constraints. section 6.1.2
Clients discover skill directories in project and user scope locations. For example, .agents/skills/ under the project directory or home directory is listed for all agent clients; clients may also use their own locations. Skills are progressively disclosed: after discovery, activation makes the workflow and bundled resources available, and the agent executes the procedure for the task. section 6.1.2 section 6.1.1
A discovery implementation can scan scope paths, validate each bundle, and return skills keyed by name. Validation can accept cosmetic issues with warnings while skipping fatal errors: an overlong name is cosmetic in this approach, whereas a missing SKILL.md or invalid frontmatter is fatal. section 6.3.2
Reading-list workflow
Document the repeated procedure for fetching information about a book from the web and adding it to a reading list. Once the skill is available to the agent, a user can request the task without restating the procedure. section 6.0
