#给你的 AI Agent 搭一个技能商店：SkillHub 从零到上线全记录

最近大家都在给 AI Agent 写 skill。写完一个又一个，放在 ~/.agent/skills 目录里，隔壁同事问你要你就打个 zip 发过去。过两周你的 skill 更新了，又得重新发一遍。

我们需要一个"技能商店"。不是 App Store 那种上架审核三个月的，是自己部署、团队内部用的那种。搜一下就有了，传上去就能装。

这就是 SkillHub。

#它到底解决了什么问题

先搞清楚一个概念：skill 是什么？

AI agent 本质上是个对话接口。它能写代码、能分析数据、能做很多事——但得有人教它怎么做。每次对话都手把手教？太浪费上下文了。skill 就是把"怎么教"这个过程封装成一个包：一段 markdown 写的指南，加上必要的脚本和模板，打包放在某个地方，agent 需要的时候自动加载。

就像你不会每次做饭都去菜市场现买锅碗瓢盆——你有一套厨房装备，拿出来就能用。skill 就是 agent 的厨房装备。

SkillHub 解决的是这些装备的统一管理和分发。一个自托管的服务，跑在你自己的服务器上，团队成员搜到 skill 就能装。

#市面上有什么，还缺什么

做之前扫了一圈同类项目。最有代表性的几个：

所以现状是：公共平台有，但看得到摸不着的东西你也不敢放上去（你的部署脚本、内部 API 文档、代码审查规则）。Agent 生态内的方案绑定太紧，换个 agent 就要重新适配。私有部署这一块，基本是空白。

SkillHub 就是来填这个空白的。

#试过的其他方案

在决定写 SkillHub 之前，我试过两条路，各有各的问题。

方案一：Git 仓库管理。 建一个 public Git 仓库，skill 按目录放进去，版本靠 git tag 或 commit hash。开源的 skill 放公开仓库没问题，但内部 skill 就尴尬了——放上去等于公开，不放上去就得另起一个私有仓库，两边维护。

问题是 skill 的消费方不是人，是 agent。agent 需要的是"给定一个 skill 名称，拉下最新版并解压到指定目录"，Git 仓库做这件事很重——它不会只 fetch 一个子目录，你得 clone 整个仓库再筛，带宽浪费且慢。更麻烦的是，你得给每个 agent 配 Git 凭证，凭证管理又是一个坑。如果团队里有非技术背景的人想传 skill，教他怎么 clone、commit、push、打 tag，比教他用浏览器拖拽上传多花二十倍时间。

方案二：FTP / 共享目录。 内网搭个 FTP 或者 Samba，skill 打成 zip 往里扔，agent 从共享路径拉。配起来快，某种意义上比 Git 更适合文件分发。

但这个方案天然没有版本概念。你更新了一个 skill，文件名从 skill-v2.zip 变成 skill-v3.zip，agent 怎么知道该拉哪个？写死文件名？那你每次更新都要改 agent 配置。更别提没有搜索、没有元数据（谁传的、什么时候传的、依赖什么）、没法按标签筛选、没法看排行榜。

两个方案试下来，结论是一致的：它们都能存文件，但都做不到"管理"。管理意味着元数据 + 版本 + 搜索 + 权限 + 分发策略，缺一个就是另一个 FTP。

SkillHub 的设计目标就是把这些"管理"能力装进一个浏览器就能用的服务里。

#核心功能速览

#拖拽上传，自动识别

上传一个 skill 不用敲命令。把文件夹拖进浏览器窗口，SkillHub 自动打包成 zip、自动扫描 SKILL.md 提取名称和描述、自动识别版本号。如果你不填版本，它还会自动给上个版本号 +0.0.1。

这背后是一段手写的 CRC32 和 ZIP 生成代码——因为不想在浏览器端引入额外依赖。压缩包在浏览器里生成好，传到服务端直接存储。

#版本管理，随时回滚

传过的 skill 可以追加新版本。旧版本不删，用户随时切回去。作者觉得某个版本有问题，点一下删掉就行。

这个设计参考了 Docker Hub 的 tag 机制，但更简化——不需要理解 latest 和 alpine 的区别。

#注册审批 + 权限控制

不是谁都能往仓库里传东西。新用户注册后默认是待审批状态，管理员点一下"通过"才能用。认证用的是 JWT + refresh token，BCrypt 加密，前端自动拦截 401 并用 refresh token 续期，对用户透明。

#主题 + 国际化

亮色暗色一键切。中英文界面，默认中文。config.json 里换个 Logo、换个 favicon、换个标题——不用动代码。适合企业内网部署做品牌定制。

#搬运机制

从外网搬运 skill 到内网，上传时填原作者和来源链接，详情页会同时显示"搬运者"和"原作者"，避免拿别人的成果当自己的。

#踩坑：一条 CSS 导致的暗色模式翻车

shadcn/ui 默认的 CSS 变量是用 hsl() 包裹 oklch() 色值的，比如：

.bg-primary {
  background-color: hsl(var(--primary));
}

--primary 的值是 oklch(0.21 0.006 285.885)，浏览器看到的最终表达式是 hsl(oklch(…))。这在标准里不合法。Chrome 对不带透明度的用法还能容错渲染，一旦加上透明度（bg-primary/10）就直接放弃——表现为一片空白。

骨架屏（Skeleton 组件）的默认样式恰好是 bg-primary/10。于是暗色模式下，页面初始加载阶段本该显示的灰色占位块完全不渲染，看起来像白屏。

修起来很简单，就是绕开 CSS 变量别名，直接用十六进制色值。但这提醒我一件事：工具链的默认配置不一定在生产环境能稳稳跑。Tailwind 的 hsl() 包装和新一代 CSS 颜色空间之间有个隐形的坑，掉进去过一次你才会注意到。

#三条命令跑起来

pip install skillhub-selfhost
skillhub-selfhost admin-init
skillhub-selfhost server-start

打开 http://localhost:8000，管理员账号登录，开始上传你的第一个 skill。

要用 PostgreSQL 替代 SQLite？在启动目录下建个 config.json：

{
  "db_url": "postgres://user:pass@localhost:5432/skillhub"
}

不需要装数据库管理工具，不需要配 Nginx 反向代理（当然生产环境建议加一层），前端页面已经打包进 Python 包里了。一条命令就是一个完整的服务。

#它是给谁用的

如果你的团队在用 AI agent，有 3 个以上反复使用的流程——代码审查规则、部署脚本、某个框架的最佳实践——把它们写成 skill，统一放在 SkillHub 上管理。

如果你只有一个人，那可以先不急着搭仓库。但一旦涉及"和别人共享 skill""在多台机器之间同步 skill""想让新人快速上手团队的 AI 工作流"，SkillHub 比 zip 包和 U 盘拷贝要好得多。

源码在 github.com/mikigo/skillhub-selfhost，Apache-2.0 协议。欢迎 Star、提 Issue、交 PR。