Every volume must contain aDocumentation Index
Fetch the complete documentation index at: https://agentvolumes.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
volume.toml file at its root. This file is the normative human-authoring format for package metadata: it declares who published the volume, what components it exports, which runtimes it targets, what permissions it needs, and which other volumes it depends on. Tooling validates manifests against a canonical parsed-data model derived from the TOML source, so the structure you write here is the source of truth for everything downstream — resolution, installation, trust, and discovery.
Schema version
The[volume] table must include schema, set to the integer 1. Key order is not semantically significant. Tooling rejects manifests with unrecognized schema versions.
[volume] table
The [volume] table carries package identity and discovery metadata.
Required fields
Manifest schema version. Currently
1.Volume identifier. Use a bare name for scopeless volumes (
my-agent) or @scope/name for scoped
volumes (@acme/research-pack). Name segments must be lowercase alphanumeric with hyphens, 1–128
characters, not starting or ending with a hyphen, and without consecutive hyphens. Scoped
identifiers also include a scope segment up to 64 characters, so the full scoped volume.name can
be longer than a bare name.SemVer 2.0.0 version string (e.g.,
1.4.0).One-line summary of the volume. Maximum 256 characters.
SPDX license expression (e.g.,
Apache-2.0, MIT, Apache-2.0 OR MIT).Primary package role. One of:
component, plugin, provider, meta. See Package
roles for guidance on choosing the right role.Optional fields
URL to the volume’s homepage or documentation site.
URL to the source repository.
URL to extended documentation.
Freeform keywords for search discovery (e.g.,
["research", "arxiv", "academic"]).Additional package roles layered on top of the primary role (e.g.,
["provider"]).External services the volume integrates with at the volume level (e.g.,
["github", "slack"]).
These are discovery hints, not dependency declarations. See
Compatibility for common provider examples and naming
guidance.[publisher] table
The [publisher] table is required in every volume.toml, including scoped volumes and role = "meta" volumes. It identifies the publisher entity, not their verification status — verification is managed by the bibliotheca.
Publisher identifier. For scopeless volumes, identifies the owner of the volume name. For scoped
volumes, identifies the owning scope (without the
@ prefix).[[components]] array
Declare every component the volume exports as an array of TOML tables. A component without a corresponding [[components]] entry is not exported, even if its entrypoint file exists in the volume.
Required fields per component
Component type. One of:
agent, skill, command, tool, hook, mcp-server, lsp-server.Component name. Lowercase alphanumeric with hyphens. Must be unique within the volume across all
component types.
Relative path from the volume root to the component’s primary entry file (e.g.,
./skills/summarize-paper/SKILL.md). Must not be absolute, must not contain .. segments, and
must resolve to a regular file.Optional fields per component
One-line description of the component.
External services integrated by this specific component.
Component-specific permission overrides. Values must be narrower than or equal to the parent
volume’s permissions — you cannot escalate permissions at the component level.
Component names must be unique across all component types within a volume. You cannot have a
skill named search and a tool named search in the same volume.[dependencies] table
Declare volume-level dependencies as a TOML table where each key is a volume name and each value is a SemVer constraint string. See Dependencies for the full constraint grammar.
[[external-dependencies]] array
Declare package dependencies outside the Agent Volumes pkg:volume ecosystem as audit metadata. These records are used for review, policy, BOM export, and potential-exposure diagnostics. They are not resolver inputs, lockfile entries, installed package evidence, scanner findings, VEX status, or confirmed vulnerability evidence.
Package URL for an external ecosystem package. It must not use the
volume purl type and must not
include a PURL version component or subpath. Put version intent in constraint.VERS expression for the external package range. This is not the Agent Volumes SemVer dependency
grammar.
Dependency use context. Core values are
runtime, build, development, test, optional,
peer, source, documentation, and other. Extension values use reverse-DNS namespace syntax,
such as org.example:codegen.Optional component scope. When present, the array must be non-empty, duplicate-free, and contain
only component names declared in the same manifest. Omit it for volume-wide external dependency
declarations.
[component-dependencies] table
Declare which components in this volume depend on specific components from other volumes. Each key is the name of a component declared in this manifest’s [[components]] array; each value is an array of component purl strings.
A component-level dependency implies the parent volume dependency. After volume resolution,
tooling verifies that the referenced components exist in the resolved volume version.
[[runtimes]] array
Declare which agent runtimes your volume is compatible with. Each entry names a runtime and provides a compatibility version expression.
Runtime identifier. See Compatibility for the full list
of 18 recognized runtime IDs.
Required advisory version expression for the runtime. This is metadata for discovery and
diagnostics — not a hard dependency constraint. Tooling preserves the expression as authored and
only evaluates it when the runtime’s version scheme is explicitly understood.
[[runtimes]] array entirely, the volume makes no runtime-specific compatibility claim.
[[protocols]] array
Declare protocol compatibility for volumes that export MCP servers or LSP servers.
Protocol identifier. One of:
mcp, lsp.Required protocol version expression. Protocol ecosystems use different version schemes
(date-like, short numeric, SemVer-compatible), so this is advisory metadata. Tooling must not
reject a manifest solely because it cannot evaluate the expression.
[permissions] table
Declare the maximum permissions your volume needs. All components inherit these defaults; individual components may declare narrower (but never broader) permissions.
Local filesystem access. One of:
deny, read, write, read-write.Network access. One of:
deny, read, write, read-write.Browser access. One of:
deny, read, write, read-write.Shell command execution. One of:
deny, allow.[environment] table
Declare execution environment requirements. Omitting any field means no restriction for that dimension.
Required language runtimes. Valid values:
node, bun, deno, python, ruby, go, rust.Target operating systems. Valid values:
linux, macos, windows.Target CPU architectures. Valid values:
x64, arm64, x86.