skillbox

Self-hosted, versioned skills library for AI agents. MCP, scoped clients, and optional Jev recommendations.

Skillbox

A self-hosted, versioned skills library for AI agents. React, Bun, Hono and PostgreSQL. MIT licensed.

Features

• Markdown/file editor, immutable revisions, conflict detection and restore.

• Profiles with skill/bundle grants and independent create, update, archive and proposal permissions.

• Revocable client keys, usage reporting and owner-reviewed updates.

• HTTP MCP, a Node/Bun stdio bridge and checksum-verified CLI downloads.

• Base MCP Resources, standards-shaped skill manifests and a non-mutating compatibility audit.

• Optional task-aware Jev recommendations using your own OpenRouter, TypeSafe AI or Vercel AI Gateway key.

• Optional Executor integration using your own endpoint and authentication.

• Public GitHub URL imports with commit-pinned previews and revision conflict checks.

• Native folder imports/exports, protected PostgreSQL/config backups and explicit restore tooling.

• Docker-only setup, optional Caddy HTTPS and Umbrel package generation.

A new instance starts empty. No personal skills, accounts, client keys, service endpoints or paid-provider credentials are seeded. Skillbox never executes uploaded skill code.

Related MCP server: Shared Skills Registry MCP

Quick start

Requires Docker Engine/Desktop with Compose v2 and Bash (Linux, macOS or WSL). No host Bun/Node installation needed.

git clone https://github.com/kitze/skillbox.git
cd skillbox
bash scripts/skillbox.sh setup
# Creates .env with unique random credentials, mode 0600; refuses to overwrite.
bash scripts/skillbox.sh start

Already have Bun? bun scripts/setup-env.ts remains available. See self-hosting for LAN ports, optional automatic HTTPS, prebuilt images, mounted secrets, backup/restore and upgrades. Umbrel packaging supports official submissions and community stores; public images and real Umbrel lifecycle verification are release gates, not implied by having package files.

Open http://127.0.0.1:4791. Sign in with SKILLBOX_ADMIN_TOKEN from your local .env. The key is not printed by the setup script. Keep .env private. For a remote installation, set SKILLBOX_ORIGIN to your own HTTPS origin and configure a TLS reverse proxy; see deployment.

Create or import skills, create a profile with the required grants, then create a client connection. Client keys are shown once; only their hashes are stored. Use separate client keys rather than distributing the owner key.

For local development with your own PostgreSQL 16+ database:

bun install --frozen-lockfile
# Set DATABASE_URL, SKILLBOX_ADMIN_TOKEN (at least 32 random characters),
# and SKILLBOX_ORIGIN=http://127.0.0.1:4791 in your protected environment.
bun run build
bun run start

Jev setup

Open Settings → Jev recommendations, select Vercel AI Gateway (default), TypeSafe AI, or OpenRouter, and save that provider's API key. Keys are stored separately: switching providers never sends another provider's key, and switching back retains its saved key. Removing the selected provider's key disables its model calls. Skillbox does not auto-import environment keys, fetch credentials from a skill library, or ship an application-wide provider account.

The key is encrypted server-side in PostgreSQL using AES-256-GCM with key material derived from your SKILLBOX_ADMIN_TOKEN. It is never returned by the settings API or included in browser bundles. Protect the owner token and database backups. Changing that token makes stored integration credentials unreadable. Follow the rotation guidance before changing it.

Saving a key does not validate provider access or buy credits. Jev sends task text and authorized active skill descriptions to the selected provider; its charges and data handling apply to your account. Without that provider's saved key, or on failure, recommendations return deterministic search with an explicit fallback reason and attempted provider.

TypeSafe uses POST https://api.typesafe.ai/v1/systemone, Bearer authentication and model: "jev-latest", without Gateway protocol headers. Gateway keeps its evaluation-model endpoint and existing headers. OpenRouter uses POST https://openrouter.ai/api/alpha/decisions with model: "typesafe/jev-1.13", not the chat-completions endpoint. All three use the same bounded catalog and score rubric. OpenRouter evaluates the complete catalog in batches of at most 32 skills / 24,000 request bytes, with two concurrent batches under the existing eight-second deadline. Any failed batch falls back for the whole request; no partial ranking is returned. Snake-case usage fields are normalized, and OpenRouter's reported usage.cost is aggregated across successful batches. Provider/key changes invalidate cached and in-flight results. The direct contract follows the TypeSafe OpenAPI schema.

Agents and CLI

Install bootstrap/SKILL.md as the agent's skills-library bootstrap. Configure your own instance's /mcp endpoint with Authorization: Bearer <client-key>. For clients needing stdio:

{
  "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"
      }
    }
  }
}

Client config: { "url": "https://skills.example.com", "token": "YOUR_CLIENT_KEY" }, mode 0600. Default location: ~/.config/skillbox/config.json. SKILLBOX_URL / SKILLBOX_TOKEN override config. Without a URL, the CLI targets localhost, never another person's service. Keep cli/skillbox.mjs and cli/package.mjs together.

node cli/skillbox.mjs list
node cli/skillbox.mjs search "database migration"
node cli/skillbox.mjs recommend "Fix choppy scrolling in an Expo app"
node cli/skillbox.mjs load my-skill
node cli/skillbox.mjs manifest my-skill
node cli/skillbox.mjs audit # Owner-only; exits 1 for incompatible packages
node cli/skillbox.mjs fetch my-skill@REVISION
node cli/skillbox.mjs publish ./my-skill my-skill EXPECTED_REVISION

Base MCP tools: search_skills, recommend_skills, load_skill, read_skill_file, report_skill_use. Write/proposal tools appear according to permissions. Recommendations are additive: unqueried search_skills remains the mandatory task-start inventory step. Load selected skills with returned revisions before applying them.

Fetching validates every path, file hash, size, executable flag and package checksum, then writes atomically. It never runs code or installs dependencies. Revoking a key blocks future access but cannot retract already downloaded files. Bundles expand grants into deduplicated current leaf skills; references never grant access by themselves.

scripts/install-client.py optionally configures Codex, Claude or Cursor from explicit per-client credentials on stdin, preserving existing settings and making local backups. Review any installer before running it.

Native MCP Skills

Skillbox serves io.modelcontextprotocol/skills on MCP 2026-07-28 using the stable SDK v2: server/discover, skills/list, skills/get, and verified resources/read, including binary files. Catalogs contain complete manifests for authorized, active, compatible skills; cache hints remain private.

Existing 2025 clients, tools and CLI workflows keep working. The owner-only compatibility audit identifies legacy packages without rewriting them. Reading a resource never activates or executes a skill; native hosts own verification and approval. Optional directory reads are not advertised.

Manually integrates Matt Van Horn's PR #2 with the existing manifest, authorization and validation safeguards. See Skills over MCP for protocol details and verification scope. The hosted roadmap remains future work; this release is single-owner and self-hosted.

Recommendation contract

MCP: recommend_skills({task, limit?, offset?}). HTTP: POST /api/skill-recommendations with the same JSON and authentication.

• Full authorized, enabled, non-archived leaf catalog is considered without lexical prefiltering. Maximum 200 leaves / 120,000 serialized characters; larger catalogs explicitly fall back rather than ranking a hidden subset.

• Results return id, immutable referenceId, pinned revision, description, relevance, method, noMatch, hasMore, nextOffset, cacheHit and rubricVersion.

• Relevance is an uncalibrated 0–4 rubric score, not probability. Scores ≥3 are returned, descending by score then ID. noMatch=true means no evaluated candidate met that threshold.

• Missing key, eight-second deadline, provider errors, malformed responses, rate limits or capacity limits use existing PostgreSQL search. Fallback responses have method=search, relevance=null, noMatch=null, and fallbackReason; empty lexical results are not claimed as a semantic no-match.

• Process-local cache: task, authenticated scope, catalog descriptions/revisions, provider-settings revision and model/rubric version. Maximum 128 entries, five-minute TTL. Two concurrent evaluations; ten uncached requests per scope/minute. No automatic retries.

• Grants, lifecycle and revisions are checked before model calls and re-read afterward, including cache hits. Key replacement/removal resets model/cache state. Stale results are discarded. Tasks and descriptions are evidence, not executable instructions.

For an optional billable developer benchmark, use bun scripts/benchmark-recommendations.ts --live --provider vercel with your own AI_GATEWAY_API_KEY, --provider typesafe with TYPESAFE_API_KEY / JEV_KEY, or --provider openrouter with OPENROUTER_API_KEY. This separate script does not configure the app or save credentials. Missing provider-reported cost is shown as unknown, not zero. Its small synthetic sample is not a production latency SLA or probability calibration.

Import from GitHub

Owners can choose Import from GitHub in the library and paste a public repository, /tree/<ref>/<folder>, or /blob/<ref>/…/SKILL.md URL. Collections prompt for a skill directory. Branches containing slashes resolve longest matching ref first; use a full commit SHA to remove ambiguity.

Preview downloads and validates the package without publishing. Review SKILL.md, files, excluded artifacts and the pinned commit, then explicitly import. Existing skill IDs require an overwrite checkbox and Publish new revision; stale revisions return a conflict rather than overwrite newer edits. Existing bundles, disabled and archived entries cannot be replaced through import.

Publication downloads the previewed commit again, validates Git blob hashes, and records repository, full commit SHA and directory on the immutable revision. Package bytes and executable flags are preserved; no scripts run. Owner-only endpoints: POST /api/imports/github/preview (url, optional repository-relative path) and POST /api/imports/github/publish (url from the preview, id, expectedRevision).

Public repositories only: no GitHub token, private repositories, redirects, symlinks, submodules or Git LFS. Limits: 400 files, 2 MB per file, 8 MB per package, 30-second deadline, two active imports and 12 attempts/minute per instance. Truncated or oversized repository trees fail closed. Runtime artifacts and .env* files are excluded; recognizable embedded secrets block import. Secret detection is heuristic, not a guarantee that imported content is safe.

Data portability

bun scripts/import.ts /path/to/skills
SKILLBOX_EXPORT_DIR=/path/to/empty-export bun scripts/export.ts
bash scripts/backup.sh

The database is the source of truth; folder exports do not change it until republished. Imports preserve file bytes and unknown frontmatter, skip runtime artifacts/symlinks, and quarantine recognizable secret patterns. This is a heuristic, not a comprehensive secret audit. Do not put passwords or tokens in skill packages.

Exports contain your skill content and may be private. Keep exports and backups separate from public application source. An optional scripts/export-github.sh requires an explicit dedicated private export checkout; it is not enabled automatically.

Verification and security

bun run typecheck
bash scripts/test-isolated.sh

The isolated suite creates and removes its own Compose PostgreSQL instance without published ports. It covers authorization, revisions, API/MCP behavior, CLI, encrypted settings and recommendations; image creation also builds the frontend. Never run database tests against production.

See SECURITY.md, deployment notes, and release checklist. Skillbox is a single-owner, self-hosted application with scoped clients—not a public multi-tenant SaaS. No analytics, hosted account, preloaded catalog or automatic paid-provider connection is required.