日常工作知识库

Appearance

knowledge-base skill 多工具分发与一键安装工作流 ​

归类：开发工具 / AI 技能分发 / 自动化 发生时间：2026-03-27 状态：✅ 已落地基础实现

一、问题现象 / 背景 ​

当一个技能需要同时服务多个支持 skills 的 IDE 和 AI 工具时，最容易遇到三个问题：

  1. 技能源文件在多个目录各改各的，逐渐失去一致性
  2. 本地明明更新了 skill，但其他工具目录里的副本还是旧版本
  3. 想做成“一键安装”时，不清楚应该从哪个目录同步、如何扩展新工具、以及后续怎么演进到 npx 或自动化工作流

knowledge-base 仓库本身就踩过这个坑，因此更适合把这套分发流程沉淀成可复用方法。

二、排查过程 ​

1. 先确定唯一事实来源 ​

最重要的一步，是先明确 skill 只能有一个可编辑源目录：

text
skills/knowledge-base/

其他工具目录下的 skill 都应该视为“可覆盖副本”，而不是新的编辑入口。

2. 再把分发过程脚本化 ​

如果只靠人工复制目录，很快就会出现：

  • Codex 已更新，但 Gemini / OpenClaw / Cursor 还是旧副本
  • 新增文件同步过去了，删除的陈旧文件却残留
  • 每次都要手动判断本机哪些工具安装了 skills 功能

所以更稳妥的做法是把同步做成脚本，并用 rsync --delete 处理陈旧文件。

三、根本原因 / 设计思路 ​

这类问题的根因，不是“忘了同步”，而是“缺少一个明确的 skill 分发边界”。

一个更稳的设计通常包含三层：

  1. 仓库内单一源
    • 只改 skills/knowledge-base/
  2. 本机一键同步
    • 自动探测默认技能目录
    • 支持自定义扩展目录
  3. 未来一键安装入口
    • bootstrap 脚本
    • 进一步演进到 curl | bash 或 npx

四、解决方案 / 推荐做法 ​

1. 当前一键同步命令 ​

bash
npm run skill:install

当前默认会探测并同步到这些目录：

  • ~/.codex/skills/knowledge-base
  • ~/.gemini/antigravity/skills/knowledge-base
  • ~/.openclaw/skills/knowledge-base
  • ~/.cursor/skills-cursor/knowledge-base

2. 查看或定向同步 ​

bash
# 查看目标目录
npm run skill:install:list-targets

# 预演
npm run skill:install:dry-run

# 只同步指定工具
bash ./scripts/install-knowledge-base-skill.sh --target codex,openclaw

3. 扩展其他支持 skills 的工具目录 ​

推荐不要把个人本机路径直接写进公共脚本，而是通过本地配置扩展：

text
continue|Continue|/Users/you/.continue/skills/knowledge-base
roo|Roo Code|/Users/you/.roo/skills/knowledge-base

然后执行：

bash
bash ./scripts/install-knowledge-base-skill.sh --extra-target-file ./skill-targets.conf

也可以用环境变量做临时扩展：

bash
export KNOWLEDGE_BASE_SKILL_EXTRA_TARGETS="continue|Continue|$HOME/.continue/skills/knowledge-base"
npm run skill:install

4. 一键 bootstrap ​

如果目标机器还没有本地工作区，可以先走 bootstrap：

bash
npm run skill:bootstrap

它会自动：

  1. 克隆或更新仓库
  2. 回到指定分支
  3. 调用仓库里的安装脚本把最新 skill 分发到本机工具目录

五、未来如何扩展到 npx 或自动化工作流 ​

1. curl | bash ​

适合需要极简安装入口的场景。思路是把 bootstrap 脚本暴露为一个可直接下载执行的入口。

2. npx ​

如果希望支持：

bash
npx knowledge-base-skill-install

建议拆出一个独立 npm 包，仅负责：

  • 下载或更新 knowledge-base 仓库
  • 调用安装脚本
  • 转发 --target、--extra-target-file 等参数

3. 自动化同步 ​

如果希望 skill 改完后自动刷新各工具目录，可以增加：

  • 文件监听：fswatch、watchexec
  • 定时任务：cron、launchd
  • IDE / AI 工具内的本地自动化任务

六、注意事项 ​

  1. 不要把目标工具目录当成 skill 源目录直接修改。
  2. 自定义路径尽量放在本地配置文件或环境变量中，避免把个人路径提交到公共仓库。
  3. skill:install 只能同步本机副本，不负责远端发布；如果 skill 源本身有变更，仍需正常提交仓库。
  4. Cursor 一类工具的 skills 目录可能属于兼容方案，正式能力边界应以该工具的当前官方机制为准。