An agent skill is a reusable, documented workflow that an LLM agent can discover, activate, and execute. A skill defines the steps for a task; tools provide discrete functionality the agent can invoke along the way. The workflow is written once rather than repeated in every prompt. section 6.1.1 section 6.6
Maintaining a research list
A skill can instruct an agent to find a paper, categorize it, summarize it, and add it to a list. The agent may use web search, file-reading, and board tools while following the saved procedure. section 6.1.1
The Agent Skills open standard packages a workflow in a directory containing SKILL.md. Its YAML frontmatter requires a name and description; the Markdown body contains the procedure. Optional scripts/, references/, and assets/ directories hold executable code, supporting documentation, and other files. The workflow can reference resources at the steps where they are needed. section 6.1.2 section 6.1.1
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.
|
Use the frontmatter field table to check required fields, naming constraints, and optional metadata. section 6.1.2
A skill-enabled agent uses a staged lifecycle:
- Discover skills from the configured scope and disclose a catalog of their names, descriptions, and locations to the model. section 6.6 section 6.2.2
- Activate a selected skill to disclose its complete information, including the workflow and available resources. The model can use UseSkillTool, or a user can request explicit activation with run_with_skill(). section 6.6 section 6.1.2
- Execute the workflow, using tools and referenced resources as needed. section 6.1.1 section 6.1.2
A Skill implementation stores frontmatter, location, and scope. Its resources property finds bundled files; catalog() formats discovery information; and read_body() loads the workflow, raising errors for unreadable files, invalid frontmatter separation, or an empty body. section 6.2.2
Scope controls availability: user-scoped skills are accessible across projects, while project-scoped skills are limited to their project. In the illustrated framework, discovery occurs on each run, and scope selection is coarser than assigning individual tools. The explicit_only_skills parameter can hide specified skills from autonomous model activation. section 6.6 section 6.5





