Formats

Reference

Skill, 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.

Text
---
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.
FieldRule
nameRequired. 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
descriptionWhat the skill does and when to use it, at most 1024 characters
allowed-toolsOptional, 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
BodyBecomes 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:

TypeFilesWhat the agent does with it
ReferenceText documents: markdown, text, JSON, YAML, CSV, XML, HTML, SQL and similarReads it as text with read_skill_reference
AssetTemplates, 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.

Text
preview-manifest/
  SKILL.md
  references/
    authoring-rules.md

A 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.md in any spelling (a folder holding an exact SKILL.md is 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.

BehaviorDetail
ApprovalEvery 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
ArgumentsPlain tokens only: no pipes, redirects, quotes or chained commands
Files copiedThe 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 runsIn 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.

PlaceholderFilled 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.

Text
Compute the sum and average of these two numbers and write the result.

First number: {{first}}
Second number: {{second}}

Invoked as:

Text
/sum first=10 second=20

Quoted 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.

Text
tech-writer/
  pack.json
  skills/
    tech-writing/
      SKILL.md
FieldTypeRequiredMeaning
keystringYesThe 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
versionstringNoThe pack's version, such as 1.0.0. Defaults to 1.0.0
name, descriptionobjectNoText by language code: { "en": "...", "tr": "..." }
categorystringNoSuch as roles, teams or connections
tagsarrayNoSearch tags
iconKeystringNoThe pack's icon, such as github or file-text
producesarrayNoWhat the pack produces, such as docs-page or mcp-server
examplePromptsarrayNoPrompts shown on the pack card, each a language map
requires.permissionsarrayNoPermissions the installing admin needs, such as Volobox.Skills.ManageOrganization
requires.inputsarrayNoWhat the admin supplies at install: { key, kind, label, help, required }. kind is secret for a token, chosen from a secret scope
itemsarrayNoThe pack's contents: { id, type, path } for a skill, { id, type, spec } for everything else
Item typeHolds
skillpath: the skill's folder in the zip, such as skills/tech-writing
agentspec: handle, displayName, autoIncludeSystemSkills, charterInstructions, skillRefs (ids of skill items)
commandspec: handle, displayName, description, iconKey, promptTemplate, availableOnAllAgents, usableInCoding, parameters ({ name, type, required, defaultValue, description }), skillPolicies ({ skillRef, policy }, such as AlwaysEnable)
mcpServerspec: handle, displayName, description, endpoint, transport, authMode, secretFrom (the requires.inputs key holding its token), isReadOnly

The GitHub connection pack that ships with Volobox:

JSON
{
  "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:

JSON
{
  "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.json at the base URL, the catalog of its packs;
  • the zip bundles, at paths relative to the registry's base URL.

index.json

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": [] }
    }
  ]
}
FieldTypeRequiredMeaning
schemaVersionnumberYes1. Any other value refuses the whole index
generatedAtstringNoWhen the index was written, as an ISO 8601 timestamp
packsarrayNoOne entry per pack. An index without it lists no packs
packs[].keystringYesThe pack's key, namespace/name
packs[].versionstringYesThe pack's version
packs[].bundle.pathstringYesThe zip's path relative to the base URL
packs[].bundle.sha256stringYesThe zip's SHA-256, 64 hexadecimal characters
packs[].bundle.sizeBytesnumberYesThe zip's size in bytes
packs[].manifestobjectNoThe 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:

RuleDetail
Bundle pathsMust stay on the registry's origin
IntegrityAfter download, the zip's SHA-256 must match the index
Matching manifestThe zip's pack.json key and version must match the index entry
Reserved key prefixesAn index may not claim volobox/... or workspace/... keys; such entries are ignored
AuthenticationAn optional API key, sent as both X-Api-Key and Authorization: Bearer
Catalog nameThe registry's short name becomes registry:{name} in the Library
Trust levelEffect
Untrusted, TrustedPacks install as ordinary workspace content; bundled scripts still ask for approval
VerifiedSkills install as verified, the same privilege first-party packs have. Use it only for a registry you fully control