Formats
ReferenceSkill, command and pack formats
The SKILL.md format and skill bundles, slash command templates, the pack.json manifest of a library pack, and what a remote pack registry serves.
This page is the file format of three things you can bring into Volobox: a skill (a SKILL.md and the files it bundles), a slash command template, and a library pack (pack.json with its skills), plus what a remote pack registry serves.
SKILL.md
A skill is an agentskills.io SKILL.md document: YAML frontmatter, then a markdown body.
---
name: tech-writing
description: Creates and updates clear Volobox Docs pages from product changes. Use when documenting features, writing help pages, or refreshing outdated docs.
allowed-tools: list_spaces search_pages read_page create_page update_page create_folder
---
Turn product reality into docs people can follow.
## When activated
1. Search for an existing page before creating a new one.
2. Prefer short sections: Purpose, Steps, If → then, Related.
3. Never invent UI labels or permissions. Verify with tools or say what is unknown.| Field | Rule |
|---|---|
name | Required. The skill's slug: lowercase letters, digits and hyphens, at most 64 characters. Importing a file whose name already exists offers to overwrite that skill |
description | What the skill does and when to use it, at most 1024 characters |
allowed-tools | Optional, advisory. Volobox maps the built-in tool keys it knows and shows unknown ones as warnings in the import preview. It grants nothing: the people who configure the skill decide its tools |
| Body | Becomes the skill's instructions (size limited). Keep long procedures in reference files, which load only when the agent opens them |
An imported skill is unverified, is not attached to any agent, and its allowed-tools is only a suggestion.
Bundled files
A skill can carry files beside SKILL.md. Each keeps its path relative to SKILL.md, in any folder (references/api/errors.md) or at the top level (REFERENCE.md, validate.cjs). The type is worked out from the file's place and extension:
| Type | Files | What the agent does with it |
|---|---|---|
| Reference | Text documents: markdown, text, JSON, YAML, CSV, XML, HTML, SQL and similar | Reads it as text with read_skill_reference |
| Asset | Templates, images, binaries, and anything under assets/ | Lists and downloads it; never reads it as text |
| Script | .sh, .bash, .py, .js, .mjs, .cjs, .ts, .rb outside references/ and assets/ | Reads it, and runs it in a sandbox with run_skill_script (.ts is not runnable) |
When a skill with files is active, the agent sees the file list in its instructions and calls list_skill_files and read_skill_reference, so a long reference costs nothing until it is opened.
preview-manifest/
SKILL.md
references/
authoring-rules.mdA file is skipped, with its reason shown in the import preview and the result, when:
- it is an executable file type (
.exe,.dll,.com,.bat,.cmd,.msi,.ps1,.scr,.jar,.so,.dylib,.apk,.vbs); - its path has characters other than letters, digits,
.,-and_, has spaces or.., has a name starting with-or ending with., or is too deep or too long; - it is named
SKILL.mdin any spelling (a folder holding an exactSKILL.mdis a skill of its own); - it is damaged, too large, or named like text but holds binary data.
Hidden files and folders (.github, .gitignore) and tooling junk (__MACOSX, .git, node_modules, .DS_Store, Thumbs.db) are left out without being listed. A whole skill is refused when it has too many files, its files are too large in total (both within per-skill limits), or two files have the same path (a file and a folder of the same name count as the same path).
Scripts
A skill's scripts run only when the skill grants a sandbox profile (its Sandbox tab). The agent then gets a run_skill_script tool, naming the skill and the script.
| Behavior | Detail |
|---|---|
| Approval | Every run raises an approval card with the exact command line, arguments included |
| Interpreters | .sh and .bash with bash, .py with python3, .js, .mjs and .cjs with node, .rb with ruby |
| Arguments | Plain tokens only: no pipes, redirects, quotes or chained commands |
| Files copied | The script and the files in its own folder and below it, at the same relative paths. A top-level script gets the whole skill |
| Unattended runs | In a scheduled or event-triggered workflow run, scripts run only when an administrator trusted the exact skill revision (Unattended automation > Trust for automations > Trust this revision) or the skill is platform-verified. Changing the skill's content revokes the trust |
A zip with several skills
A bundle is a .zip. Every folder in it that holds a file named exactly SKILL.md is one skill, so a zip downloaded from a skills repository imports as it is; the preview lists each skill with a checkbox. Files that belong to no skill are not imported. Only a zip with no SKILL.md at all accepts skill.md, at the shallowest depth where one occurs. A zip with neither is rejected.
Export (.zip) on a skill writes the same layout: SKILL.md plus every bundled file at its path.
Slash command templates
A slash command expands into a full prompt before the message reaches the model. It shapes the prompt and grants no tools.
| Placeholder | Filled with |
|---|---|
{{args}} | The free text after the handle and any key=value pairs |
{{param_name}} | The value of the named input param_name |
Each named input has a Label, a Name (lowercase snake_case starting with a letter, such as repo_name), a Description, a Type (a Volobox item, a person or agent, or Free text, Number, Date, Date & time, Yes/No, Choice) and a Behavior: required, or optional with a default. A required input cannot also have a default. Declaring an input is not enough: the template must contain {{name}}, or the value is never substituted.
Compute the sum and average of these two numbers and write the result.
First number: {{first}}
Second number: {{second}}Invoked as:
/sum first=10 second=20Quoted values carry spaces (topic="sprint planning"). A missing required value opens a dialog before the message is sent, and defaults are filled in before the model sees the turn.
pack.json
A library pack bundles agents, skills, commands and connections. Its zip holds pack.json at the top and each skill's folder at the path its item names.
tech-writer/
pack.json
skills/
tech-writing/
SKILL.md| Field | Type | Required | Meaning |
|---|---|---|---|
key | string | Yes | The pack's key, namespace/name, such as volobox/github-connection. Installations are tracked by it. A zip whose pack.json has no key is refused |
version | string | No | The pack's version, such as 1.0.0. Defaults to 1.0.0 |
name, description | object | No | Text by language code: { "en": "...", "tr": "..." } |
category | string | No | Such as roles, teams or connections |
tags | array | No | Search tags |
iconKey | string | No | The pack's icon, such as github or file-text |
produces | array | No | What the pack produces, such as docs-page or mcp-server |
examplePrompts | array | No | Prompts shown on the pack card, each a language map |
requires.permissions | array | No | Permissions the installing admin needs, such as Volobox.Skills.ManageOrganization |
requires.inputs | array | No | What the admin supplies at install: { key, kind, label, help, required }. kind is secret for a token, chosen from a secret scope |
items | array | No | The pack's contents: { id, type, path } for a skill, { id, type, spec } for everything else |
Item type | Holds |
|---|---|
skill | path: the skill's folder in the zip, such as skills/tech-writing |
agent | spec: handle, displayName, autoIncludeSystemSkills, charterInstructions, skillRefs (ids of skill items) |
command | spec: handle, displayName, description, iconKey, promptTemplate, availableOnAllAgents, usableInCoding, parameters ({ name, type, required, defaultValue, description }), skillPolicies ({ skillRef, policy }, such as AlwaysEnable) |
mcpServer | spec: handle, displayName, description, endpoint, transport, authMode, secretFrom (the requires.inputs key holding its token), isReadOnly |
The GitHub connection pack that ships with Volobox:
{
"key": "volobox/github-connection",
"version": "1.0.0",
"name": { "en": "GitHub connection", "tr": "GitHub bağlantısı" },
"description": {
"en": "Connects Volobox agents to GitHub via a remote MCP server using a personal access token.",
"tr": "Volobox ajanlarını kişisel erişim jetonu ile uzak bir MCP sunucusu üzerinden GitHub'a bağlar."
},
"category": "connections",
"tags": ["github", "mcp", "code"],
"iconKey": "github",
"produces": ["mcp-server"],
"examplePrompts": [
{ "en": "List open pull requests in our linked repos.", "tr": "Bağlı depolardaki açık pull request'leri listele." }
],
"requires": {
"permissions": ["Volobox.Agents.McpServers.Create"],
"inputs": [
{
"key": "githubToken",
"kind": "secret",
"label": { "en": "GitHub personal access token", "tr": "GitHub kişisel erişim jetonu" },
"help": {
"en": "A classic or fine-grained PAT with repo read access. Stored encrypted; never returned to the UI.",
"tr": "Repo okuma yetkili classic veya fine-grained PAT. Şifreli saklanır; arayüze geri dönmez."
},
"required": true
}
]
},
"items": [
{
"id": "mcp-github",
"type": "mcpServer",
"spec": {
"handle": "github",
"displayName": "GitHub",
"description": "GitHub remote MCP (PAT bearer).",
"endpoint": "https://api.githubcopilot.com/mcp/",
"transport": "StreamableHttp",
"authMode": "BearerToken",
"secretFrom": "githubToken",
"isReadOnly": true
}
}
]
}A command item from the Release Manager pack:
{
"id": "command-release-notes",
"type": "command",
"spec": {
"handle": "release-notes",
"displayName": "Release notes",
"description": "Draft release notes from the work completed in a given period.",
"iconKey": "rocket",
"promptTemplate": "Draft release notes for the work completed since {{since}}. Group the changes by area, call out breaking changes first, and link the related pull requests. Save the result as a Docs page draft.",
"availableOnAllAgents": true,
"usableInCoding": false,
"parameters": [
{ "name": "since", "required": false, "defaultValue": "the last release", "description": "Start of the period to cover, e.g. a date or a release tag." }
],
"skillPolicies": [{ "skillRef": "skill-release-playbook", "policy": "AlwaysEnable" }]
}
}Note
A pack never carries a token. A connection contributes its address, transport and auth mode; its token is a secret-scope reference the installing admin selects. A pack published from a workspace can include only workspace-wide skills and commands and shared agents.
Remote pack registry
A remote registry is an HTTPS origin that serves:
index.jsonat the base URL, the catalog of its packs;- the zip bundles, at paths relative to the registry's base URL.
index.json
{
"schemaVersion": 1,
"generatedAt": "2026-11-14T09:00:00Z",
"packs": [
{
"key": "acme/release-pack",
"version": "1.0.0",
"bundle": {
"path": "packs/acme/release-pack/1.0.0.zip",
"sha256": "<64 lowercase hex characters>",
"sizeBytes": 18432
},
"manifest": { "key": "acme/release-pack", "version": "1.0.0", "name": { "en": "Release pack" }, "items": [] }
}
]
}| Field | Type | Required | Meaning |
|---|---|---|---|
schemaVersion | number | Yes | 1. Any other value refuses the whole index |
generatedAt | string | No | When the index was written, as an ISO 8601 timestamp |
packs | array | No | One entry per pack. An index without it lists no packs |
packs[].key | string | Yes | The pack's key, namespace/name |
packs[].version | string | Yes | The pack's version |
packs[].bundle.path | string | Yes | The zip's path relative to the base URL |
packs[].bundle.sha256 | string | Yes | The zip's SHA-256, 64 hexadecimal characters |
packs[].bundle.sizeBytes | number | Yes | The zip's size in bytes |
packs[].manifest | object | No | The zip's full pack.json, inlined so the Library can list the pack without downloading the zip. Without it the Library has only the entry's key and version to show |
An entry is dropped, and the rest of the index still loads, when its key starts with volobox/ or workspace/, its bundle path is an absolute URL or contains .., its sha256 is not 64 hexadecimal characters, its sizeBytes is 0 or less (or over the per-pack limit), or its manifest.key differs from its key. A pack published from a workspace has a workspace/ key, so give it a key in your own namespace before you serve it.
Rules Volobox applies:
| Rule | Detail |
|---|---|
| Bundle paths | Must stay on the registry's origin |
| Integrity | After download, the zip's SHA-256 must match the index |
| Matching manifest | The zip's pack.json key and version must match the index entry |
| Reserved key prefixes | An index may not claim volobox/... or workspace/... keys; such entries are ignored |
| Authentication | An optional API key, sent as both X-Api-Key and Authorization: Bearer |
| Catalog name | The registry's short name becomes registry:{name} in the Library |
| Trust level | Effect |
|---|---|
| Untrusted, Trusted | Packs install as ordinary workspace content; bundled scripts still ask for approval |
| Verified | Skills install as verified, the same privilege first-party packs have. Use it only for a registry you fully control |