Self-Host Skillbox: Build a Versioned Skills Library for AI Agents

What is Skillbox?

Skillbox is an MIT-licensed, self-hosted skills library for AI agents. It gives you a central place to create, import, version, distribute, and audit reusable skill packages. The application is built with React, Bun, Hono, and PostgreSQL.

A new installation is deliberately empty. It does not include personal skills, user accounts, client keys, external service endpoints, or paid AI provider credentials. Skillbox distributes skill content but never executes uploaded skill code.

Key features

• Versioned editing: Edit Markdown and supporting files with immutable revisions, conflict detection, and restoration.
• Scoped access: Create profiles with skill or bundle grants and separate create, update, archive, and proposal permissions.
• Revocable clients: Issue individual client keys, review usage, and revoke future access when necessary.
• MCP and CLI access: Use HTTP MCP directly, connect through a Node or Bun stdio bridge, or download packages with checksum verification.
• MCP resources: Expose authorized, compatible skills through base MCP resource listing and reading.
• Optional recommendations: Use Jev with your own Vercel AI Gateway or TypeSafe AI key.
• Data portability: Import and export native folders, create protected backups, and restore data explicitly.
• Self-hosted deployment: Run with Docker Compose, optionally place Caddy in front for HTTPS, or prepare an Umbrel package.

Skillbox is designed as a single-owner, self-hosted application with scoped clients. It is not a public multi-tenant SaaS platform.

Prerequisites

The recommended installation requires Docker Engine or Docker Desktop with Compose v2, plus Bash on Linux, macOS, or WSL. You do not need to install Bun or Node.js on the host for the Docker-based setup.

Install and start Skillbox

1. Clone the repository and enter its directory:

   git clone https://github.com/kitze/skillbox.git
   cd skillbox

2. Generate the local environment file:

   bash scripts/skillbox.sh setup

   This creates .env with unique random credentials, sets its mode to 0600, and refuses to overwrite an existing file.

3. Start the Docker services:

   bash scripts/skillbox.sh start

4. Open http://127.0.0.1:4791 in your browser.

5. Read SKILLBOX_ADMIN_TOKEN from your local .env file and use it to sign in. The setup script intentionally does not print this token.

Keep .env private. The owner token controls administrative access and is also involved in protecting stored integration credentials.

Remote deployment

For a remote installation, set SKILLBOX_ORIGIN to the deployment's HTTPS origin and configure a TLS reverse proxy. Do not expose a production instance over unencrypted HTTP. Consult the repository's deployment notes for the supported deployment details.

Local development without the Docker-only application setup

If you already have Bun and a PostgreSQL 16 or newer database, install dependencies and start the application directly:

bun install --frozen-lockfile
# Set DATABASE_URL
# Set SKILLBOX_ADMIN_TOKEN to at least 32 random characters
# Set SKILLBOX_ORIGIN=http://127.0.0.1:4791
bun run build
bun run start

Store all three required values in a protected environment rather than committing them to source control.

Create skills and scoped clients

After signing in, create a skill in the editor or import an existing skill package. Skill revisions are immutable, so clients can load or fetch a specific revision instead of relying on changing content.

Next, create a profile and grant it access to the required skills or bundles. Assign create, update, archive, and proposal permissions independently according to the client's purpose. Finally, create a client connection using that profile.

Client keys are displayed only once, and Skillbox stores only their hashes. Save each key immediately in a protected client configuration. Use a separate key for each client instead of distributing the owner token.

Configure the CLI

The CLI reads a JSON configuration containing the Skillbox URL and client key. Its default path is ~/.config/skillbox/config.json.

{
  "url": "https://skills.example.com",
  "token": "YOUR_CLIENT_KEY"
}

Set the file mode to 0600. The environment variables SKILLBOX_URL and SKILLBOX_TOKEN override values from the configuration file. If no URL is configured, the CLI safely targets localhost rather than another person's service.

Keep cli/skillbox.mjs and cli/package.mjs together. You can then explore and retrieve authorized skills:

node cli/skillbox.mjs list
node cli/skillbox.mjs search "database migration"
node cli/skillbox.mjs load my-skill
node cli/skillbox.mjs manifest my-skill
node cli/skillbox.mjs fetch my-skill@REVISION

The fetch operation validates paths, file hashes, sizes, executable flags, and the package checksum before writing files atomically. It does not execute code or install dependencies.

Publish an updated skill

Publish a local folder by supplying the skill ID and the revision you expect to update:

node cli/skillbox.mjs publish ./my-skill my-skill EXPECTED_REVISION

The expected revision supports conflict detection. Publishing also depends on the permissions granted to the client profile.

Audit compatibility

An owner can run the non-mutating compatibility audit:

node cli/skillbox.mjs audit

The command exits with status 1 when it finds incompatible packages. It prepares you to assess MCP Skills compatibility without rewriting existing packages.

Connect an AI agent through MCP

Install bootstrap/SKILL.md as the agent's skills-library bootstrap. Clients that support HTTP MCP can connect to your instance's /mcp endpoint and send the client key as a bearer token:

Authorization: Bearer YOUR_CLIENT_KEY

For an MCP client that requires stdio, configure the included bridge:

{
  "mcpServers": {
    "skillbox": {
      "command": "node",
      "args": [
        "/absolute/path/to/skillbox/cli/skillbox.mjs",
        "mcp"
      ],
      "env": {
        "SKILLBOX_URL": "https://skills.example.com",
        "SKILLBOX_CONFIG": "/absolute/path/to/protected-client-config.json"
      }
    }
  }
}

Base MCP tools include search_skills, recommend_skills, load_skill, read_skill_file, and report_skill_use. Write and proposal tools are exposed only when the client's profile grants the corresponding permissions.

Skillbox also exposes authorized compatible skills through base MCP resources/list and resources/read. Supporting binary and large files can be accessed as resources, but reading a resource does not activate or execute a skill.

Full io.modelcontextprotocol/skills support is not yet advertised. The current implementation provides readiness features through the base MCP protocol while native discovery and negotiation still depend on an SDK and protocol upgrade.

Use search and recommendations correctly

At the start of a task, agents should still call search_skills to inventory relevant authorized skills. Recommendations are additive and do not replace this search step. Before applying a selected skill, load it using the immutable revision returned by Skillbox.

Without an external recommendation provider, you can search from the CLI:

node cli/skillbox.mjs search "database migration"

To request task-aware recommendations:

node cli/skillbox.mjs recommend "Fix choppy scrolling in an Expo app"

The equivalent MCP operation is recommend_skills({task, limit?, offset?}). HTTP clients can send the same authenticated JSON body to POST /api/skill-recommendations.

Configure optional Jev recommendations

1. Open Settings → Jev recommendations.

2. Select Vercel AI Gateway, which is the default, or TypeSafe AI.

3. Enter and save your own API key for the selected provider.

Provider keys are stored separately. Selecting TypeSafe does not send a saved Gateway key to TypeSafe, and switching providers retains the previously saved key. Removing the selected provider's key disables model calls for that provider.

The key is encrypted in PostgreSQL with AES-256-GCM using key material derived from SKILLBOX_ADMIN_TOKEN. It is not returned by the settings API or included in browser bundles. Changing the owner token without following the documented rotation process makes stored integration credentials unreadable.

Saving a key does not verify provider access or purchase credits. Jev sends the task text and descriptions of authorized active skills to the selected provider, so that provider's billing and data-handling terms apply.

Understand recommendation results and fallbacks

Jev evaluates the full authorized, enabled, non-archived leaf catalog, up to 200 leaves or 120,000 serialized characters. Larger catalogs explicitly fall back instead of ranking an undisclosed subset.

• Relevance is an uncalibrated score from 0 to 4, not a probability.
• Results scoring at least 3 are returned in descending score order and then by ID.
• noMatch=true means no evaluated candidate reached the threshold.
• A missing key, provider error, malformed response, rate limit, capacity limit, or eight-second deadline triggers PostgreSQL search fallback.
• Fallback results use method=search, relevance=null, and a fallbackReason.

The process-local cache holds at most 128 entries for five minutes. Skillbox allows two concurrent evaluations and ten uncached requests per scope per minute, with no automatic retries. Permission grants, lifecycle state, and revisions are checked before and after model calls, including cache hits.

Import, export, and back up data

If Bun is available, import a folder of skills with:

bun scripts/import.ts /path/to/skills

Imports preserve file bytes and unknown frontmatter, skip symlinks and runtime artifacts, and quarantine recognizable secret patterns. This detection is heuristic, so it is not a substitute for a complete secret audit. Never place passwords or tokens in skill packages.

Export skill content into an empty destination:

SKILLBOX_EXPORT_DIR=/path/to/empty-export bun scripts/export.ts

The PostgreSQL database remains the source of truth. Editing an exported folder does not change the database until the content is published again.

Create a protected backup with:

bash scripts/backup.sh

Exports and backups may contain private skill content. Keep them separate from public application source. The optional GitHub export script requires an explicitly configured, dedicated private export checkout and is not enabled automatically.

Advanced operational tips

Use one client key per integration

Separate keys make revocation and usage reporting more useful. Revoking a key blocks future requests, but it cannot retract files that a client has already downloaded.

Prefer narrowly scoped profiles

Grant each agent only the skills and actions it needs. Bundles expand into deduplicated current leaf skills, while references alone do not grant access.

Protect the owner token and backups

The owner token provides administrative access and derives encryption material for saved integration credentials. Protect it along with the database and configuration backups, and follow the documented rotation procedure before replacing it.

Treat skills as content, not trusted programs

Skillbox validates and distributes package files without executing them. Continue reviewing downloaded instructions and code before using them in an agent workflow.

Benchmark recommendations cautiously

Developers can run the optional billable benchmark using their own provider key:

bun scripts/benchmark-recommendations.ts --live --provider vercel
bun scripts/benchmark-recommendations.ts --live --provider typesafe

Use AI_GATEWAY_API_KEY for Vercel or TYPESAFE_API_KEY or JEV_KEY for TypeSafe. This script does not configure the application or save credentials. Its synthetic sample is not a production latency guarantee or probability calibration.

Verify a deployment or contribution

Run type checking and the isolated test suite before deploying changes:

bun run typecheck
bash scripts/test-isolated.sh

The isolated suite creates and removes its own Docker Compose PostgreSQL instance without publishing database ports. It covers authorization, revisions, API and MCP behavior, the CLI, encrypted settings, and recommendations. Never point database tests at production.

Conclusion

Skillbox provides a controlled, self-hosted workflow for managing reusable AI-agent skills. Start with the Docker setup, create versioned skills, assign narrowly scoped profiles, and connect each agent with its own client key. You can then add MCP access, optional Jev recommendations, portability workflows, and backups while retaining ownership of your catalog and credentials.