Skillbox：给自己的 AI 智能体搭一个版本化技能库，整套跑在你家

用 Claude Code、Codex、Cursor 这类编程智能体的人，迟早都会遇到同一个问题：那些真正好用的提示词、流程、规范，散落在几十个项目的 AGENTS.md、.cursor/rules、~/.claude 目录里。改了一版不知道上一版是什么样，给同事分享只能靠复制粘贴，团队里每个人手里的”技能”版本各不相同。

Skillbox 想解决的就是这件事。它把一个自托管、带版本控制的技能库塞进你自己的 Docker 里，让 AI 智能体通过 MCP 协议来检索、推荐、加载技能——而不是把一堆 Markdown 文件散在各个仓库里。

项目地址：github.com/kitze/skillbox
官方许可：MIT
技术栈：React + Bun + Hono + PostgreSQL
当前热度：160+ Stars（2026-09-17 建仓，两天内涨起来的新项目）
作者：独立开发者 Kitze

一个”自己的技能库”长什么样

Skillbox 的核心数据模型很干净：技能（skill）是一组文件，每次发布产生一个不可变修订（immutable revision）。这个设计贯穿了后面几乎所有功能。

技能内容通过一个 Markdown/文件编辑器维护，发布后生成不可变修订，支持冲突检测和回滚。也就是说，你不必担心”谁在什么时候把哪条规则改掉了”——历史版本永远查得到，也永远恢复得回来。

配套的还有配置文件（profile）机制：一个 profile 持有若干技能或技能包的授权，并可以独立配置创建、更新、归档、提案这四种权限。给团队里的前端同学一个 profile，给运维同学另一个 profile，各自的技能可见范围完全不同。

客户端密钥：只显示一次，只存哈希

给 AI 客户端接入的部分，Skillbox 用了可撤销的客户端密钥：

密钥创建后只显示一次，服务端只存哈希
支持用量上报
支持”由所有者审核的更新”流程

README 里明确建议：不要分发 owner key，而是给每个客户端单独签发密钥。撤销一个密钥会立刻阻断后续访问，但已经下载到本地的文件是收不回来的——作者把这条边界写得很直白，没有含糊其辞。

MCP 支持：HTTP 直连 + stdio 桥接

接入智能体有两条路：

一是HTTP MCP，把客户端指向你自己的 /mcp 端点，带上 Authorization: Bearer 。

二是给需要 stdio 的客户端准备的 Node/Bun 桥接。配置大致长这样：

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

基础 MCP 工具集包括：search_skills、recommend_skills、load_skill、read_skill_file、report_skill_use。写操作和提案类工具会根据权限动态出现。

这里有个设计细节值得注意：推荐（recommend）是附加能力，不是替代品。Skillbox 明确要求 search_skills 仍然作为任务开始时的强制清单步骤——也就是说，智能体不能”以为”推荐结果就是全部，该做的全量检索还得做。

可选推荐：用你自己的模型 Key

recommend_skills 是可选的。作者没有内置任何模型账号，也没有”全站共享”的凭证。你要在设置里自己选一家：

Vercel AI Gateway（默认）
TypeSafe AI（走 https://api.typesafe.ai/v1/systemone，Bearer 认证，模型写死 jev-latest）

两家的密钥分开存储：选 TypeSafe 不会把你的 Gateway key 发出去，切回来原 Key 还在。密钥在服务端用 AES-256-GCM 加密存在 PostgreSQL 里，密钥材料从 SKILLBOX_ADMIN_TOKEN 派生，永远不会通过设置接口返回，也不会打进浏览器 bundle。

换掉 owner token，已存的集成凭证就会变成不可读——这是一个必须知道的副作用，作者建议改之前先看轮换说明。

推荐接口的契约也写得很克制：

全量授权、启用、未归档的技能都会被考虑，不做词法预过滤（上限 200 个技能 / 120,000 字符，超了会显式回退，而不是偷偷只排一个子集）
相关性是一个未校准的 0–4 分档分数，不是概率
只返回 ≥3 分的结果，按分数降序
缺 Key、8 秒超时、Provider 报错、限流、容量不足——统统走回退：退到 PostgreSQL 全文检索，并带上 fallbackReason，且明确不声称空结果是”语义无匹配”

这种”把不确定性写在接口里”的做法，比很多号称 AI 检索的工具要诚实得多。

自托管：Docker-only，一条命令起

git clone https://github.com/kitze/skillbox.git
cd skillbox
bash scripts/skillbox.sh setup
bash scripts/skillbox.sh start

前提是 Docker Engine/Desktop + Compose v2 + Bash（Linux、macOS 或 WSL），镜像里不需要装 Bun/Node。

setup 会生成唯一的随机凭证写进 .env（权限 0600），不打印任何值，也不会覆盖已有的环境文件。起来后打开 http://127.0.0.1:4791，用 .env 里的 SKILLBOX_ADMIN_TOKEN 登录。

默认只绑定回环地址。想开在局域网里：

bash scripts/skillbox.sh setup --origin http://server.local:8499 --bind 0.0.0.0 --port 8499

注意这一点：HTTP 明文会暴露客户端凭证和内容，不可信网络下必须上 HTTPS 或者 SSH 隧道。CLI 默认会拒绝非本地的 HTTP 连接，要放开得显式设置 SKILLBOX_ALLOW_INSECURE_HTTP=1。想自动签证书也可以，加个 SKILLBOX_DOMAIN 然后起 Caddy 覆盖文件即可，但这是可选项，不是默认行为。

一个空实例，什么都不预置

这一条是我最欣赏的地方：全新实例是空的。没有预置技能、没有账号、没有客户端密钥、没有服务端端点、没有付费 Provider 凭证。

没有分析统计，没有托管账号，没有预加载的技能目录，也不需要自动连接任何付费服务。整个应用是”单所有者 + 自托管”的形态，作者自己强调过：这不是一个面向公网的 SaaS。

数据可迁移，但别把导出当公开文件

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

数据库才是唯一事实来源——文件夹导出不会反向改库，除非你重新发布。导入会保留文件字节和未知的 frontmatter，跳过运行时产物和符号链接，并对可识别的密钥模式做隔离。

作者特意提醒：这只是启发式检查，不是全面的密钥审计。导出内容是你的技能正文，很可能包含私有信息，得和公开源码分开存放。

关于 MCP Skills 标准：提前铺路，但不吹

Skillbox 已经在做官方 io.modelcontextprotocol/skills 扩展的兼容：通过基础 MCP 的 resources/list 和 resources/read 暴露已授权的技能，资源 URI 形如 skill://skillbox///SKILL.md，附带完整的文件清单、字节大小和 sha256 摘要。

但作者写得很清楚：完整的 skills 扩展支持”暂未声明”，因为当前 SDK/基础协议还需要原生发现与协商的升级。同时明确这是”标准兼容”，不是与 MCP 项目的隶属或背书关系。

还有一个容易误解的点：读取资源不等于激活、批准、安装或执行技能。资源读取就是读字节，仅此而已。

配套的 audit 是只读兼容性审计，检查的是名称/描述规则、YAML 解析、路径安全、文件完整性这些——不检查恶意指令，也不检查密钥安全。通过审计不等于这个技能可信、已被批准、已被执行或者符合规范。