# Skill, command and pack formats

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

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

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

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

```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
```

| 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:

```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": [] }
    }
  ]
}
```

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

## Related

- [Create a skill](/docs/create-a-skill)
- [Host a pack registry](/docs/host-pack-registry)
- [Agents](/docs/agents)
- [Integrations](/docs/integrations)
