Use this file to discover all available pages before exploring further.
This guide walks you through creating and publishing your first volume — a versioned package of agent components that any compatible runtime can install. You’ll write a volume.toml manifest, declare components, specify compatibility requirements, and publish using the shelf CLI.
The shelf CLI and the Alexandria bibliotheca are Windlass-maintained reference implementation
projects in development. They are downstream implementation projects, not governance artifacts,
and the canonical standard remains the Agent Volumes v0.1.0-rc.1 specification plus its
companion schemas and conformance fixtures.
1
Create a volume.toml manifest
Every volume starts with a volume.toml file at the root of your project. This file is the authoritative manifest — it declares your package metadata, components, dependencies, and compatibility requirements.Create volume.toml in your project root with the required fields:
volume.toml
[volume]schema = 1name = "my-research-pack"version = "0.1.0"description = "Research assistant with literature analysis tools"license = "Apache-2.0"role = "plugin"[publisher]id = "yourname"
The required fields are:
Field
Description
schema
Always 1 for the current specification version.
name
Your volume’s name. Lowercase letters, digits, and hyphens only. Scopeless (my-pack) or scoped (@org/my-pack) per your bibliotheca’s policy.
An SPDX license expression, e.g. Apache-2.0 or MIT.
role
One of component, plugin, provider, or meta. Use plugin for most volumes that extend a runtime.
The [publisher] table identifies who owns this volume name. For scoped volumes, the id matches your scope.
Add optional metadata fields to improve discoverability in bibliothecas: homepage, repository, documentation, and keywords.
2
Declare your components
Components are the actual agent capabilities your volume exports. Declare each one as an [[components]] entry with a type, a unique name, and an entrypoint path relative to your volume root.Add a skill and a tool to your manifest:
volume.toml
[[components]]type = "skill"name = "summarize-paper"entrypoint = "./skills/summarize-paper/SKILL.md"description = "Summarize academic papers with structured extraction"[[components]]type = "tool"name = "arxiv-search"entrypoint = "./tools/arxiv-search.json"description = "Search arXiv for papers by query, author, or category"
Then create the entrypoint files at the declared paths:
---name: summarize-paperdescription: Summarize academic papers with structured extractionversion: 0.1.0---# Summarize PaperWhen asked to summarize a paper, extract the following sections:- **Title and authors**- **Core contribution** (1-2 sentences)- **Method** (brief)- **Key results** (bullet points)- **Limitations** (if stated)
Each component name must be unique within the volume across all component types. Component names use lowercase letters, digits, and hyphens only; unlike volume names, component names are never scoped.
You can declare all seven component types in a single volume — agent, skill, command, tool, hook, mcp-server, and lsp-server. See Component Types for the entrypoint format and semantics for each type.
3
Add compatibility metadata
Tell runtimes and users what environments your volume supports. Compatibility metadata is optional but strongly recommended for discoverability.
The [[runtimes]] array declares which agent runtimes this volume targets and what version expression it reports for each runtime. If you omit this array entirely, the volume makes no runtime-specific compatibility claim.
The [[protocols]] array declares MCP or LSP version requirements. This is especially important if your volume includes mcp-server or lsp-server components.
Valid values for filesystem, network, and browser are deny, read, write, and read-write. For shell, use deny or allow. Components can only narrow permissions declared at the volume level, not broaden them.
4
Publish using the shelf CLI
Once your manifest and entrypoint files are in place, publish your volume to a bibliotheca using the shelf CLI.
# Authenticate with your bibliothecashelf login
shelf publish reads your volume.toml, validates the manifest and all declared entrypoints, constructs the content integrity digest, and uploads the package to the configured bibliotheca.
Make sure all entrypoint files exist at the paths declared in your volume.toml before publishing. The CLI will reject the upload if any declared entrypoint is missing.
5
Verify content integrity
After publishing, every release is identified by two identities that work together:
Logical identity: pkg:volume/my-research-pack@0.1.0 — the package-facing release identifier you reference in dependencies and tool calls.
Immutable content identity: a sha256:... digest of the normalized file tree — the cryptographic anchor that lets anyone verify they received exactly what was published.
You can verify a local copy of a volume against its published digest:
# Verify the integrity of an installed volumeshelf verify my-research-pack@0.1.0
The verification process reconstructs the normalized file tree digest from your local files and compares it against the digest recorded at publish time. Any modification to any file in the volume — including the manifest — changes the digest and fails verification.
For higher assurance, attach trust artifacts such as CycloneDX BOMs, SLSA provenance, or Sigstore-family signatures
after publishing. See Supply Chain Security for the full trust model.
This volume is identified as pkg:volume/research-agent-pack@1.4.0. Its literature-reviewer agent component is addressable as pkg:volume/research-agent-pack@1.4.0#agent/literature-reviewer.
