Skillbox：为 AI 代理设计的自托管、可版本化技能库

kitze/skillbox

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.

新实例初始为空。不会预置任何个人技能、账户、客户端密钥、服务端点或付费供应商凭据。Skillbox 从不执行上传的技能代码。

Quick start

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

需要 Docker Engine/Desktop 的 Compose v2（容器编排工具）与 Bash（Linux、macOS 或 WSL（Windows Subsystem for Linux，Windows 上的 Linux 子系统））。主机无需安装 Bun/Node。

git clone https://github.com/kitze/skillbox.git
cd skillbox
bash scripts/skillbox.sh setup  # 生成带唯一随机凭据的 .env，权限模式 0600；不会覆盖已有文件。

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.

已经装有 Bun？bun scripts/setup-env.ts 仍然可用。关于 LAN（局域网）端口、可选的自动 HTTPS、预构建镜像、挂载的密钥、备份/恢复与升级，请参阅自托管文档。

Umbrel packaging supports official submissions and community stores; public images and real Umbrel lifecycle verification are release gates, not implied by having package files.

Umbrel（一种家用服务器/NAS 应用商店方案）打包支持官方提交与社区商店；公开发布的镜像与真实的 Umbrel 生命周期验证是发布门槛，并非仅凭打包文件即可满足。

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.

访问 http://127.0.0.1:4791，使用本地 .env 中的 SKILLBOX_ADMIN_TOKEN 登录。安装脚本不会打印该密钥。请妥善保管 .env。对于远程安装，请将 SKILLBOX_ORIGIN 设为自己的 HTTPS 来源（origin），并配置 TLS（传输层安全协议）反向代理；详见部署文档。

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.

创建或导入技能，创建带有必需授权（grants）的配置文件（profile），然后创建客户端连接。客户端密钥仅显示一次，服务器只存储其哈希值。请使用单独的客户端密钥，不要分发所有者密钥。

For local development with your own PostgreSQL 16+ database:对于使用你自己的 PostgreSQL 16+ 数据库进行本地开发：

bun install --frozen-lockfile
# 在受保护的环境中设置 DATABASE_URL、SKILLBOX_ADMIN_TOKEN（至少 32 个随机字符）以及 SKILLBOX_ORIGIN=http://127.0.0.1:4791
bun run build
bun run start

Jev setup

Open Settings → Jev recommendations, select Vercel AI Gateway (default) or TypeSafe AI, and save that provider's API key. Keys are stored separately: selecting TypeSafe never sends your Gateway key to TypeSafe, and switching back retains your saved Gateway 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.

打开 Settings → Jev recommendations，选择 Vercel AI Gateway（默认）或 TypeSafe AI，并保存该供应商的 API 密钥。密钥分开保存：选择 TypeSafe 永远不会把你的 Gateway 密钥发送给 TypeSafe；切回 Gateway 时也会保留已保存的 Gateway 密钥。删除当前所选供应商密钥将使其模型调用失效。Skillbox 不会自动导入环境变量中的密钥，不会从技能库获取凭据，也不会随应用一起分发全局供应商账户。

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.

密钥在服务器端使用 AES-256-GCM（一种带认证加密的对称加密算法）加密后存入 PostgreSQL，加密所需的密钥素材派生自你的 SKILLBOX_ADMIN_TOKEN。设置接口（API）从不返回该密钥，浏览器打包产物中也从不包含它。请妥善保管所有者令牌和数据库备份。更改该令牌会使已存储的集成凭据无法被解密。请在更改前遵循轮换指南。

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.

保存密钥并不验证供应商访问权限，也不购买额度。Jev 会将任务文本和已授权的活跃技能描述发送给所选供应商；其计费与数据处理规则适用于你的账户。若缺少该供应商的保存密钥，或调用失败，推荐会回退到确定性的搜索结果，并附带明确的回退原因与尝试调用的供应商信息。

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. Both use the same bounded catalog and score rubric; TypeSafe's snake-case usage fields are normalized. Provider/key changes invalidate cached and in-flight results. The direct contract follows the TypeSafe OpenAPI schema.

TypeSafe 使用 POST https://api.typesafe.ai/v1/systemone、Bearer 认证以及 model: "jev-latest"，不附带 Gateway 协议头。Gateway 保留其评估模型端点与既有协议头。两者共用同一有界目录和评分规则（rubric）；TypeSafe 的下划线命名（snake_case）使用字段会被规范化。供应商或密钥变更会使缓存及在途中的结果失效。直接调用遵循 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:将 bootstrap/SKILL.md 安装为 agent 的技能库引导文件。使用 Authorization: Bearer <client-key> 配置你自己实例的 /mcp 端点。对于需要 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.

权限模式 0600。默认位置：~/.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.

SKILLBOX_URL 与 SKILLBOX_TOKEN 会覆盖配置文件中的设置。如果没有提供 URL，CLI（命令行工具）只会指向本地 localhost，绝不会连接到别人的服务。请将 cli/skillbox.mjs 与 cli/package.mjs 放在同一目录下。

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

基础 MCP（Model Context Protocol，模型上下文协议）工具：search_skills、recommend_skills、load_skill、read_skill_file、report_skill_use。写入/提案类工具会根据权限显示。推荐结果属于附加信息：未查询的 search_skills 仍然是任务开始时必须执行的清单盘点步骤。在应用所选技能之前，请使用返回的版本（revision）加载它们。

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.

获取（fetch）过程会校验每个路径、文件哈希、大小、可执行标志和包校验和，然后以原子方式写入。它从不运行代码，也不安装依赖。吊销一个密钥会阻止未来的访问，但无法收回已经下载的文件。包（bundle）会把授权展开为去重后的当前叶子（leaf）技能；仅靠引用本身不会授予访问权。

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.

scripts/install-client.py 可以选择性地根据从标准输入（stdin）显式传入的各客户端凭据，为 Codex、Claude 或 Cursor 进行配置，会保留既有设置并生成本地备份。运行任何安装脚本之前，请先审阅其内容。

Recommendation contract

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

MCP：recommend_skills({task, limit?, offset?})。HTTP：POST /api/skill-recommendations，使用相同的 JSON 与认证方式。

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.

会考虑全部已授权、已启用且未归档的叶子目录，不做词法预过滤。上限为 200 个叶子 / 120,000 个序列化字符；更大的目录会显式回退，而不是对隐藏的子集进行排序。

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

结果返回 id、不可变的 referenceId、固定版本 pinned revision、description、相关性（relevance）、method、noMatch、hasMore、nextOffset、cacheHit 与 rubricVersion。

Relevance is an uncalibrated 0–4 rubric score, not probability. Scores ≥3 are returned, descending by score then ID.

相关性是一个未经校准的 0–4 评分规则分数，并非概率。返回分数 ≥3 的结果，按分数降序排列，分数相同时按 ID 排序。

noMatch=true means no evaluated candidate met that threshold.

noMatch=true 表示没有评估过的候选满足该阈值。

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.

缺少密钥、八秒超时、供应商错误、响应格式错误、速率限制或容量限制都会回退使用现有的 PostgreSQL 搜索。回退响应的 method=search，relevance=null，noMatch=null，并附带 fallbackReason；空白的词法结果不会被声称为语义层面的"无匹配"。

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.

进程内本地缓存：任务、已认证的作用域（scope）、目录描述/版本、供应商设置版本以及模型/评分规则版本。最多 128 条，TTL（Time to Live，存活时间）为五分钟。并发评估上限为两个；每作用域每分钟最多 10 个未缓存的请求。不会自动重试。

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, or --provider typesafe with TYPESAFE_API_KEY/JEV_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.

如需可选的、可计费的开发者基准测试，请使用 bun scripts/benchmark-recommendations.ts --live --provider vercel 并提供你自己的 AI_GATEWAY_API_KEY，或使用 --provider typesafe 并提供 TYPESAFE_API_KEY/JEV_KEY。这个独立脚本不会配置应用，也不会保存凭据。供应商未上报的费用显示为"未知"，而不是零。其小型合成样本并非生产环境下的延迟 SLA（Service Level Agreement，服务等级协议）或概率校准标准。

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.

数据库是唯一可信来源（source of truth）；文件夹导出在重新发布之前不会修改数据库。导入过程会保留文件原始字节与未知的前置元数据（frontmatter），跳过运行时产物与符号链接，并对可识别的密钥模式进行隔离。这是一种启发式策略，并非全面的密钥审计。请勿在技能包中放入密码或令牌。

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.

导出内容包含你的技能内容，可能具有私密性。请将导出与备份与公开的应用源代码分开存放。可选的 scripts/export-github.sh 需要显式提供一个专用的私有导出检出目录（checkout），不会自动启用。

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.

隔离测试套件会自行创建与销毁一个不发布端口的 Compose PostgreSQL 实例。测试覆盖授权、版本、API/MCP 行为、CLI、加密设置与推荐；镜像构建过程还会构建前端。切勿在生产环境中运行数据库测试。

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.

请参阅 SECURITY.md、部署说明与发布检查清单。Skillbox 是面向单一所有者的自托管应用，配备有作用域限制的客户端，并非公开的多租户 SaaS（Software as a Service，软件即服务）。无需分析服务、托管账户、预置目录或自动的付费供应商连接。