Every volume declares a primary role using theDocumentation Index
Fetch the complete documentation index at: https://agentvolumes.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
role field in [volume]. The role communicates the package’s intended shape to tooling, bibliothecas, and consumers: how many components it exports, whether it integrates with external services, and whether it’s primarily a dependency bundle. Choosing the right role also keeps your package discoverable — search filters and compatibility checks use the role as a signal. You can combine roles using the secondary-roles field when your volume genuinely spans multiple concerns.
Overview
component
One primary component. The simplest role — use it for focused, single-purpose packages.
plugin
Multiple components extending a runtime in a specific domain. Use it when you’re bundling
related capabilities together.
provider
Integrations with external services. Use it when your package wraps an API or service (GitHub,
Slack, Postgres, etc.).
meta
A dependency bundle with no mandatory exported components. Use it to group and re-export a
curated set of volumes.
component — single primary component
A component package exports exactly one component. This is the strictest role: the spec requires exactly one [[components]] entry. If you need to export multiple components, use plugin, provider, or another applicable role instead.
Use component when you are publishing a single focused agent, skill, tool, hook, command, or server and want tooling to enforce that shape.
The spec enforces the one-component constraint for
role = "component" packages. A validator will
reject the manifest if you declare more than one [[components]] entry under this role.plugin — multiple components in a specific domain
A plugin package exports multiple components that together extend a runtime for a particular domain. Think of it as a coherent feature pack — a research assistant that ships an agent, several skills, and a tool would use role = "plugin".
Use plugin when you have two or more related components that belong together in a single distributable unit.
provider — external service integration
A provider package integrates with one or more external services. It should declare provider metadata at the volume level, the component level, or both using the providers field. Provider declarations are discovery and compatibility metadata — they tell consumers and search indexes which external services your package integrates with, without turning those services into Agent Volumes dependency declarations.
Use provider when your package is primarily a bridge to an external API, data source, or platform service.
meta — dependency bundle
A meta package is a lightweight dependency bundle. It carries no mandatory exported components — its value is in the [dependencies] table, which pulls in a curated set of volumes for consumers. You can think of it like a meta-package in other ecosystems: install this one volume to get a whole toolkit.
Use meta when you want to publish a curated collection of volumes as a single installable unit, without shipping new component code yourself.
A
meta package has no mandatory [[components]] entries. Its [dependencies] participate in
ordinary dependency resolution and single-version enforcement like any other volume dependency.
The v0.1 core does not assign special normative semantics to the full transitive dependency
closure of role = "meta" packages.Combining roles with secondary-roles
When your volume genuinely spans multiple roles, declare the primary role in role and additional roles in secondary-roles:
Quick decision guide
Use the table below to pick the right role for what you’re building:| What you’re building | Role to use |
|---|---|
| One focused agent, skill, tool, hook, command, or server | component |
| A suite of related components for a specific domain | plugin |
| A wrapper around an external API or service | provider |
| A multi-component pack that also integrates with external services | plugin + secondary-roles = ["provider"] |
| A curated collection of existing volumes | meta |