Skip to main content
A Skill component packages reusable task knowledge that teaches an agent runtime how to perform a specific type of task. Unlike a Tool (which an agent calls as a function) or an Agent (which operates autonomously), a Skill provides structured instructions and patterns that the runtime loads into its context and interprets. The runtime — not the skill itself — decides when and how to apply the knowledge.

​
What a skill is

A skill is instructions and knowledge, not executable code. When a runtime loads a skill, it becomes part of the agent’s available context. The runtime activates the skill’s guidance when it determines it is relevant to the current task. A skill can include reference materials, templates, example outputs, and step-by-step patterns. This distinction matters: if you need the agent to call an external API, use a Tool. If you need to define an invocable slash command, use a Command. If you want to teach the agent how to approach a category of task, use a Skill.

​
Entrypoint format

Skill entrypoints must be Markdown (.md) files with YAML frontmatter compatible with the Agent Skills specification. The Agent Skills spec defines the frontmatter shape; Agent Volumes adds the packaging and distribution layer on top without replacing it. The portable validation minimum requires:
  • The entrypoint file exists and is a Markdown file.
  • The frontmatter is Agent Skills-compatible and includes a description field sufficient for discovery.

​
Required frontmatter

At minimum, your skill’s Markdown file must include a description field in its YAML frontmatter:
The description field is used by runtimes and tooling to discover and select the skill. Keep it concise and specific.

​
Declaring a skill in volume.toml

Add a [[components]] entry with type = "skill" and point entrypoint to your Markdown skill file.
A volume can export multiple skills alongside other component types:

​
Skill semantics

The spec defines three behavioral properties for skills:
  • Loaded into context: A skill provides structured instructions, patterns, or knowledge that a runtime loads into its context.
  • Not independently executable: A skill does not run on its own — it augments what an agent can do.
  • Reference materials included: A skill can include templates, example outputs, and reference content alongside its instructions.
The Agent Skills spec and Agent Volumes are designed to be compatible. The volume.toml manifest is a package-level addition — it doesn’t replace the skill’s own frontmatter. Both layers coexist in a valid skill component.

​
Optional fields

Place each skill in its own subdirectory to keep related reference materials together:

​
Component identifier

Once published, reference the skill component using a purl identifier:
Other components in the same or different volumes can declare a dependency on this skill: