SkillHub

把散落在不同 AI Agent 目录里的 Skills，集中到本地一处管理、体检和启用。

English

SkillHub 盘点这台电脑上的全部 Skill，显示每个 Agent 能读到哪些，帮你补中文介绍和分类，并且只执行你明确点下或输入的写操作。唯一真身放在 ~/.agents/skills。Web 面板只允许绑定本机回环地址。

怎么装、怎么用

需要 Node.js 20 或更新版本。

第一步，装上

npm install --global @wsiwsii/skillhub

第二步，把它注册成一个 Skill。 这一步最容易漏，但正是它让你能在 agent 里直接开口使唤它。

mkdir -p ~/.agents/skills ~/.claude/skills
ln -s "$(skillhub skill-path)" ~/.agents/skills/skillhub
ln -s ../../.agents/skills/skillhub ~/.claude/skills/skillhub

skillhub skill-path 会把包的真实位置打印出来，所以不用去猜 npm 装到哪了。

Codex 原生就读 ~/.agents/skills，第一条链接它就够了；第二条是给 Claude Code 的。要给 Gemini、Cursor 或 Hermes 也装上，就单独链这一个：

skillhub link skillhub gemini

（skillhub sync 是全库同步，会把你所有 Skill 链给所有在用的 Agent。它自有用处，但不是装这一个 Skill 该用的命令。）

以后不想要了，把这两条链接删掉就行，别的什么都不动。

Windows 在 PowerShell 里用等价写法，路径同样由命令打印：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills", "$env:USERPROFILE\.claude\skills"
New-Item -ItemType Junction -Path "$env:USERPROFILE\.agents\skills\skillhub" -Target (skillhub skill-path)
New-Item -ItemType Junction -Path "$env:USERPROFILE\.claude\skills\skillhub" -Target "$env:USERPROFILE\.agents\skills\skillhub"

第三步，开一个新会话，直接说话

| Agent | 怎么触发 | |---|---| | Claude Code | /skillhub，或者直接说你想干什么 | | Codex | $skillhub | | Gemini / Cursor / Hermes | 链接建好后同样是 /skillhub |

已经开着的会话看不到新装的 Skill，要重开一个。

你可以让它做什么

| 你说这句 | 它就去做 | |---|---| | 看看我装了哪些技能 | 列出全部 Skill、来源、分类，以及哪些 agent 能读到 | | 我的技能太乱了 | 先讲清楚现状，再问你想从哪儿开始收拾 | | 帮我补中文介绍 | 找出没有中文说明的，一个个补上 | | 把没分类的归归类 | 规则没归进去的那些，交给它按内容归 | | 我不用 Cursor | 把 Cursor 从看板和同步计划里去掉，已经建好的链接原样留着 | | 把这些同步给 Codex | 先把要建哪些链接列给你看，你点头才动手 | | 打开面板 | 起本地网页 http://127.0.0.1:7777 | | 给我的技能做个体检 | 查坏损、密钥泄露、失效路径这类问题 | | 撤销刚才那步 | 回滚上一次写操作 |

以上没有一项会改动 Skill 里的内容。会写的只有链接和 SkillHub 自己的配置，而且每一次都能撤销。

不用 agent 也能用

面板和命令行本身就能独立工作：

skillhub open      # 打开本地面板（前台运行，Ctrl-C 停止）
skillhub scan      # 看装了什么
skillhub pending   # 看还有哪些缺中文介绍或没分类
skillhub doctor    # 出一份体检报告

会改东西的命令：

skillhub link <名字> <agent>     # 让某个 agent 能读某个 Skill
skillhub unlink <名字> <agent>   # 取消
skillhub describe <名字> "..."   # 写中文介绍
skillhub categorize <名字> "..." # 归类
skillhub note <名字> "..."       # 写私人备注
skillhub update <名字>           # 对该 Skill 执行 git pull --ff-only
skillhub remove <名字> --yes     # 移进 ~/.agents/_trash/
skillhub trash                   # 看回收站
skillhub trash restore <条目>    # 还原一条
skillhub backups                 # 看备份会话
skillhub undo                    # 撤销上一次

上面每条命令都会先记一次备份，skillhub undo 能退回去。注意：30 分钟内连续执行的 describe／categorize／note 会合并成同一个备份会话，undo 一次就是整批一起退， 所以它会先报数量并要求你加 --yes。

scan、pending、doctor 和不带参数的 sync 不碰任何 Skill，但也不是纯只读：它们会 在缺失时创建 ~/.agents/skills/ 和 ~/.skillhub/、刷新本地清单缓存，并且每天向 npm 查一次有没有新版 SkillHub。

从源码运行

git clone https://github.com/Vieeeeeee/skillhub.git
cd skillhub
npm ci
./bin/skillhub open

源码版注册成 Skill，把仓库里的 skill/ 目录链过去：

ln -s "$PWD/skill" ~/.agents/skills/skillhub

npm 版升级用 npm install --global @wsiwsii/skillhub@latest；源码版用 git pull --ff-only && npm ci && npm test。

功能明细

| 能力 | 实际结果 | |---|---| | 统一清单 | 展示 Skill、来源、分类、Agent 可见状态和结构信息。只存在于某个 Agent 自己目录里的 Skill 也在列表里，标成「仅 」——它不归 SkillHub 管，所以只读，触发词也只显示那个 Agent 的。 | | 中文介绍与分类 | 规则先把大头粗分一遍；pending 列出还没补的，describe 和 categorize 把剩下的写回去。两者只写 SkillHub 自己的配置，不碰 Skill 内容。 | | Agent 启用 | 为需要链接的 Agent 创建或移除链接，不会把真实目录当链接删除。 | | 在用的 Agent | 没在用的 Agent 可以隐藏，不再出现在看板和同步计划里。隐藏不会删除已有链接，目录不存在的 Agent 默认就不显示。 | | 同步计划 | 先展示完整计划；sync --apply 只补缺失链接，--fix-broken 只移除损坏链接。 | | 健康体检 | 查找 frontmatter 缺失、坏链接、个人绝对路径、文件过大和疑似密钥特征，统一管理的 Skill 和仍留在各 Agent 目录里的 Skill 都会检查。全程只读。每条结果标明你能不能处理：来自随上游更新的 Skill 的结果只作参考，因为本地改动会被下次升级覆盖（doctor --all 可一并列出）。扫描属于启发式检查。 | | Git 更新 | 对单个 Git Skill 或每个唯一 bundle 执行快进更新，部分失败会逐项显示。 | | 卸载与恢复 | 真实 Skill 移到 ~/.agents/_trash/，链接型 Skill 只移除链接。 | | 本地面板 | 通过带会话令牌的本机 API，提供清单和明确的单项操作。 |

目录怎么分工

~/.agents/skills/                     Skill 唯一真身或指向 bundle 的链接
~/.agents/_repos/                     统一管理的多 Skill 仓库
~/.agents/_trash/                     本地回收站，不会自动清空（里面是真实 Skill 数据）
~/.skillhub/registry.json             自动生成的清单缓存
~/.skillhub/overrides.json            你写的中文介绍、分类和 Agent 选择
~/.skillhub/backups/                  支持回滚操作的 manifest，只保留最近 100 次
~/.skillhub/cache/                    版本检查和 GitHub 热榜的缓存，删了会重新抓
~/.skillhub/session                   面板令牌，POSIX 下权限为 0600

~/.claude/skills/<name>               指向唯一真身
~/.gemini/config/skills/<name>         指向唯一真身
~/.hermes/skills/claude-skills/<name> 指向唯一真身
~/.cursor/skills/<name>                实验性适配

想把这些数据放到别处，或者试用时不碰现有配置，用环境变量：

| 变量 | 作用 | |---|---| | SKILL_HUB_HOME | 换一个家目录。上面所有路径都跟着走，试用和多套配置靠它 | | SKILL_HUB_PORT | 面板默认端口，等同 --port | | SKILL_HUB_HOST | 面板绑定地址，只接受回环地址 | | SKILL_HUB_NO_OPEN | 设成任意值就不自动打开浏览器 |

overrides.json 存的是你手写的东西，SkillHub 自己不会覆盖。除了中文介绍、分类和 Agent 选择，它还认这几个字段，目前只能手写：

| 字段 | 作用 | |---|---| | acceptedAliases | {"目录名": "frontmatter 里的 name"}，接受两者不一致，消除对应的体检告警 | | agentSpecificSkills | {"名字": {"claude": ".claude/skills/名字", "codex": ".codex/skills/名字"}}，声明这个 Skill 在两端就是刻意的两个版本，同步不再想统一它们 | | managedSkillContainers | 目录名数组。里面的 Skill 由别的工具自管，不当成未纳管的孤儿 | | localCanonical | 名字数组。标记本地这份是权威版，面板显示 ⭐ |

rules/ 目录下的三个配置在进程启动时读一次，改完要重启面板才生效。

Agent 路径来自 rules/agents.json。Codex 当前配置采用原生扫描，不额外复制文件。需要链接的 Agent 在 macOS/Linux 使用相对软链接，在 Windows 使用目录 Junction。

权限和副作用

执行写命令前先看这张表：

| 操作 | 会读取 | 会写入 | 回滚边界 | |---|---|---|---| | scan、list、doctor | Skill 与 Agent 目录 | ~/.skillhub/ 下的缓存和状态 | 不改 Skill 内容。 | | open | 同一批本地数据 | 会话令牌、清单与缓存 | 面板里的写入仍需明确点击按钮。 | | link、unlink | 唯一真身和 Agent 路径 | Agent 链接、本地选择与 manifest | 有记录的链接操作可尝试 Undo。 | | describe、categorize | 唯一真身中的 Skill 条目 | ~/.skillhub/overrides.json 里的中文介绍与分类 | 有记录，Undo 可回滚。不碰 Skill 内容。 | | agents <名字> on\|off | Agent 配置 | ~/.skillhub/overrides.json 里的 Agent 可见性 | 有记录。已有链接一律不删，重新启用即恢复原样。 | | sync --apply | 现场重新生成的同步计划 | 只补全缺失链接 | 有记录的链接操作可尝试 Undo。 | | sync --fix-broken | 现场重新生成的同步计划 | 只移除损坏链接 | 有记录的链接操作可尝试 Undo。 | | update / “更新全部” | 已有 Git 仓库 | 执行 git pull --ff-only | SkillHub Undo 不负责恢复，请使用 Git 或常规备份。 | | 从 Git 添加 | GitHub 公开仓库 | 先克隆到隔离目录，通过检查后移入唯一真身 | 克隆成功不代表仓库可信，启用前仍需人工阅读。 | | 卸载 | Agent 链接和唯一真身 | 解除链接或把数据移入 _trash | 从回收站恢复，或使用符合条件的 manifest。 |

skillhub undo 会尽力反向执行最新一份符合条件的 manifest。它会拒绝覆盖后来出现的新路径，失败的会话会保留，方便修正问题后重试。如果在文件变化与写入操作记录之间的极短时间内断电或进程崩溃，可能留下未记录的变化；写操作被中断后，请重新检查同步计划和各 Agent 目录。它无法替代 Time Machine、文件系统快照或 Git 历史。

第三方 Skill 风险

Skill 本质上是 Agent 会读取的指令内容，也可能引用以当前用户权限运行的脚本和工具。Star 数、熟悉的作者名字、SkillHub 没报错，都不能证明它可信。

启用外部 Skill 前建议逐项检查：

1. 阅读根目录 SKILL.md，继续检查它要求 Agent 执行的脚本和引用文件。
2. 核对仓库作者、近期提交、许可证，以及意外出现的二进制或生成文件。
3. 清理凭据、个人目录和只适用于作者电脑的配置。
4. 先用低权限、非重要数据测试，再放进正式项目。

Git 安装目前只接收 GitHub 仓库根地址和 HTTPS 协议。SkillHub 会先隔离克隆，要求根目录存在普通文件 SKILL.md，并含 name 与 description；同时关闭交互式凭据和 LFS smudge，并限制仓库体积。缺少根入口的多 Skill 仓库会被拒绝。这些措施用于减少误操作，不等同于恶意代码分析或沙箱。

会访问哪些网络

SkillHub 不包含遥测。以下动作会主动联网：

| 触发时机 | 目标 | 用途 | |---|---|---| | 多数交互式 CLI 命令执行后、面板启动时 | api.github.com | 查询本项目最新 GitHub Release，缓存 24 小时。 | | 面板加载热门榜单 | api.github.com | 搜索公开 Skill 仓库，缓存一周。 | | 从 Git 添加 | github.com | 克隆用户选中的公开仓库。 | | 更新 Skill | 现有 Git remote | 执行仅快进的 pull。 |

断网或 GitHub 限流时，会显示错误或读取已有缓存，本地清单仍可使用。面板只接受 127.0.0.1、localhost、::1；绑定 0.0.0.0 或局域网地址会直接拒绝。浏览器写请求需要完全同源、JSON Content-Type 和有效会话令牌。

命令速查

skillhub [命令] [参数]

open, start        启动本地面板
scan, list         生成并输出本地清单
pending            列出还缺中文介绍或还没归类的 Skill
describe <名字> <文本>   写入 Skill 的中文介绍
categorize <名字> <分类> 设置 Skill 的分类
note <名字> <文本>       写入个人备注
remove <名字> --yes      卸载 Skill（移入回收站，可恢复）
trash [restore <条目>]   查看回收站，或从中恢复一项
agents [名字 on|off]     查看在用哪些 Agent，或开关某一个
sync               查看当前同步计划
link <名字> <agent>   为链接型 Agent 启用 Skill
unlink <名字> <agent> 为链接型 Agent 禁用 Skill
update <名字>      快进更新一个 Git Skill 或 bundle
doctor             执行 Tier A/B/C 体检规则
undo               重试回滚最新一份符合条件的备份 manifest
backups            列出备份 manifest
skill-path         打印本包的 skill/ 目录位置
version            打印当前版本号
check-update       检查 SkillHub 是否有新版本

--json             输出 JSON。写操作（describe / categorize / note / link / unlink /
                   update / remove / trash restore / agents on|off）会返回结果和备份
                   会话号；scan / pending / doctor / sync / backups / trash 返回数据
--apply            配合 sync：只补全缺失链接
--fix-broken       配合 sync：只移除损坏链接
--all              配合 doctor：把随上游更新的 Skill 的结果也列出来
--port <number>    面板端口，默认 7777
--no-open          启动后不自动打开浏览器

支持状态

| 范围 | 状态 | 说明 | |---|---|---| | Node.js | 支持 20+ | CI 矩阵为 Node 20、22、24，三个系统各跑一遍，共 9 个 job。24 是发版流水线实际执行测试的版本。 | | macOS | 本机已验证 | 源码测试和本地打包安装后的面板启动测试已通过。 | | Linux | CI 已验证 | 2026-08-27 的 GitHub Actions 在 Node.js 20/22/24 下通过；使用前仍需核对本机 Agent 路径。 | | Windows | CI 已验证 | 2026-08-27 的 GitHub Actions 在 Node.js 20/22/24 下通过。Junction 行为仍受本机文件系统策略和权限影响，建议先看 sync，再决定是否 --apply。多条命令同时跑时这里仍可能写清单失败——Windows 不允许 rename 到一个被别的进程打开着的文件。 | | Claude、Gemini、Hermes | 链接适配 | 路径可在 rules/agents.json 调整。 | | Codex | 原生适配 | 直接读配置里的共享 Skills 目录，不需要软链。它同时也扫自己的 ~/.codex/skills（Codex 自带的 Skill Creator 默认装在那儿），只存在于那里的 Skill 会在同步计划里报出来。请按本机 Codex 版本复核。 | | Cursor | 实验性 | 用于验证配置驱动的 Agent 扩展，目前不宣称完整适配。 |

常见问题

| 现象 | 原因和解法 | |---|---| | skillhub: command not found | 没装或不在 PATH 上。装一次，再用 skillhub --version 确认。 | | 提示 SkillHub is already running | 不是错误。面板本来就开着，它会把那个页面带到前台。想再起一个用 --port 7788。 | | 面板打不开 | 跑 skillhub open --no-open 看终端报错，再访问 http://127.0.0.1:7777。 | | 某个 Skill 没出现 | 跑 skillhub scan --json，确认它的目录里有根级 SKILL.md。 | | 改了分类或中文介绍但列表没变 | 面板缓存了清单，点「重新扫描」，或跑一次 skillhub scan。 | | Skill 在 agent 里触发不了 | agent 是会话启动时加载技能列表的，开一个新会话。 | | 链接看起来不对 | 跑不带写参数的 skillhub sync，逐条看计划再决定。 | | Undo 报失败 | 逐条读返回的日志。失败的 manifest 会保留可重试，且不会覆盖后来出现的新路径。 | | Git 更新失败 | 本地改动、认证、远端或非快进历史的问题，直接用 Git 解决。SkillHub 有意只用 --ff-only。 | | 热榜或版本检查失败 | GitHub 离线或触发限流。本地清单功能不受影响。 | | 想关掉面板 | 回到启动它的终端按 Ctrl-C。终端已经关了，先用 lsof -nP -iTCP:7777 -sTCP:LISTEN 查出监听方，再 kill 那一个 PID。只按端口匹配会把「正连着这个端口的进程」一起命中，机器上跑着本地代理时那可能是大半个桌面。Windows 用 netstat -ano \| findstr :7777 找到 PID 再 taskkill /PID <pid> /F。 | | 回收站占地方 | 里面是真实 Skill 数据，SkillHub 不会自动清。确认不要了就自己删 ~/.agents/_trash/ 下对应的目录。 |

开发与验证

npm ci
npm test
npm audit --omit=dev --audit-level=high
npm run pack:check

npm run pack:check 会预览 npm 包的准确内容，不会发布。测试、CI 配置和内部计划不会进入 npm 包。执行 npm publish 时，prepublishOnly 还会自动运行测试、生产依赖审计和包内容检查。行为改动请补回归测试，路径、同源校验和回滚护栏不得弱化。

发版由标签驱动。改 package.json 版本号、写好 CHANGELOG，推一个 v<版本号> 标签，再对着这个标签触发发布流程：gh workflow run "Publish to npm" --ref v<版本号>。流程会拒绝名字不等于 v 加 package.json 版本号的 ref；它用的 npm environment 还设了人工审批，没人批准之前不会有任何东西进入 registry。

私密报告安全问题

请勿在公开 Issue 披露漏洞。使用 GitHub Security Advisories，填写受影响版本、复现步骤和影响，去掉真实凭据与个人路径。更多说明见 SECURITY.md。

许可证

MIT