前阵子我把电脑里的 AI 编程工具做了一次大扫除装了卸、卸了装最后稳定保留下来的就有十来个Cursor、Trae、Claude Code、Codex、Continue再加上几个我自己在玩的 Agent 框架和终端工具。每个工具都能跑 Agent每个 Agent 都需要“技能”但这些技能全散落得到处都是有的躺在项目目录的 SKILL.md 里有的挂在全局配置的 AGENTS.md 下有的干脆就是一堆舍不得删的 prompt 片段。工具越多这些技能就越没法管同一个技能换到另一个工具里表现经常完全不一样。后来我专门花了两周时间把 54 个常见 AI 编程工具里 Agent 会用到的技能统一整理了一遍做了一个跨平台的桌面中枢来统一管理也就是标题里说的 Skills Manager。这套方案的核心思路很简单技能只维护一份放在一个桌面应用里统一编辑、统一索引、统一导出让不同工具各取所需。这篇文章会把设计思路、实现方式、还有我踩过的坑完整讲一遍如果你想给手头的 Agent 工作流做一次彻底治理可以照着这套思路来。1. 先搞清楚Agent 技能到底卡在哪一环1.1 技能不是“一段提示词”是一套可执行的知识包很多朋友对 Agent 技能的理解还停留在“一段写得不错的 prompt”其实不完全对。以 Claude Code 里的 Skill 为例一个规范的技能通常是一个目录里面包含 SKILL.md 文件、参考资料、脚本模板、示例代码它有自己的名称、描述、触发场景甚至可以通过 frontmatter 声明使用条件。Agent 在运行时会根据用户需求和上下文决定要不要加载这个技能加载之后再去读具体的步骤说明。这种设计比“把 2000 字提示词塞进 system prompt”要科学得多因为它把知识从上下文中剥离出来按需加载。比如一个“生成 Git 提交信息”的技能只有在用户说“帮我起个 commit message”时才会被触发平时完全不会占用模型上下文。真正的问题出在这 54 个工具对技能的读取方式各不相同。Claude Code 认的是项目里的 .claude/skills 目录Cursor 和 Trae 更习惯加载 .rules 文件Codex 有自己的 AGENTS.md 规则还有一些框架要求技能以特定 JSON 配置注册。同样是“技能”落点完全不同。1.2 跨工具调用的反差感一个技能五套写法我做过一个很无聊但很有代表性的实验把同一个“写周报”技能分别配置到五个工具里。结果光是标题格式就出现了五种解析结果有的工具要求 frontmatter 里的 name 字段必须用英文有的工具支持中文名还有的工具根本不识别 description它只看文件内容的第一段话。为了这几个工具的兼容性我不得不在每个工具里复制一份适合它的技能版本日常维护量直接乘五。这就是核心痛点技能没有统一的标准各工具的读取路径、元数据字段、加载优先级、上下文注入方式都不一样。如果只在某一个工具里配好换工具就失效如果每个工具都配一遍更新一次技能就得改十几个文件。Skills Manager 要解决的正是让“技能本身”和“工具的读取习惯”解耦。我维护的是技能的原始内容到了要部署给某个工具时再由中枢根据适配规则生成对应结构的文件。2. 设计思路给 54 个工具做减法2.1 为什么不做成一个“技能库”而是做成“中枢”刚开始我差点走偏直接搞了一个巨大的技能仓库把 54 个工具的技能全塞进去。结果是仓库越来越大但真正有用的技能可能只占十分之一剩下都是重复内容和版本碎片。再往深了想问题的本质不是“没有地方存放技能”而是“技能无法被有效路由到各个工具”。所以我把方案改成了两层底层是一个纯净的技能内容目录顶层是一个带界面的桌面中枢负责索引、编辑、版本管理和导出。这个结构很像一套“总装线”原始技能就像零件中枢把它们组装成不同工具能识别的成品。你可以在中枢里写一份标准 SKILL.md然后一键生成适合 Cursor 的 .rules 文件、适合 Claude Code 的技能目录、适合 Codex 的 AGENTS.md 片段。这样既保证了内容单源又能兼顾各个工具的差异。2.2 元数据规范技能能不能被自动识别全看这几个字段为了让技能能够被跨工具复用我给自己定了一套最小元数据规范每个技能目录的 SKILL.md 开头都包含这些字段字段必填作用说明name是技能唯一标识建议用英文短横线命名description是一句话描述Agent 根据它判断何时触发version是语义化版本号方便中枢做更新比对tags否分类标签比如 git、test、frontendwhen_to_use否更详细的触发场景辅助 Agent 做路由判断dependencies否运行该技能需要的外部工具或文件description 字段尤其关键。Agent 判断“要不要用这个技能”时主要靠的是描述与当前任务的语义匹配。如果描述写得含糊技能就会“找不到”如果描述里塞了大量关键词Agent 又会过度触发。我后来总结的经验是描述控制在 40 到 80 个字写清楚“解决什么问题、在什么情况下使用”而不是写“这是一个关于某某的工具”。2.3 桌面壳层选型跨平台不能只考虑“能跑”既然叫跨平台桌面中枢技术选型就得认真考虑。我一开始想过纯 Python 加 web UI但打包分发给不同系统的用户太折腾也考虑过 Rust 做后端加 Tauri性能是好但迭代速度慢。最后我选了 Electron 本地 SQLite 的方案Electron 负责跨平台界面和文件系统读写SQLite 负责技能索引和版本元数据核心路由逻辑全部放在本地进程里。这里有个容易被忽略的点AI 编程工具的技能文件通常存放在用户目录或者项目目录下中枢必须有权限去读写这些位置。命令行工具做这件事很方便但图形界面应用就需要处理系统权限、路径转译、文件监听等问题。我实测下来用 Node 的 fs.watch 监听技能目录变化非常消耗性能后来改成“手动刷新 启动时全量扫描 目录变更后 debounce 2 秒再扫描”体验立刻顺滑了很多。3. 实操过程从单个技能到全端同步3.1 技能仓库的结构设计实际动手时我先建立了一个标准技能仓库目录结构长这样skills-manager/ ├── skills/ │ ├── conventional-commit/ │ │ ├── SKILL.md │ │ ├── templates/ │ │ │ └── commit-template.txt │ │ └── scripts/ │ │ └── validate.py │ └── weekly-report/ │ ├── SKILL.md │ └── framework/ ├── adapters/ │ ├── claude-code.js │ ├── cursor.js │ ├── trae.js │ ├── codex.js │ └── generic-rules.js ├── config.yaml └── index.sqlite每个技能一个目录SKILL.md 是入口辅助资源放在子目录中。adapters 目录里放的是各工具特定的“转换器”它们读标准技能输出对应工具需要的文件。config.yaml 记录默认开启哪些技能、哪些工具需要排除、哪些目录是只读的。索引放在 SQLite 里方便快速搜索和查看版本变更。3.2 写一个最小可用的 SKILL.md拿一个非常简单的“生成 Conventional Commit”技能举例SKILL.md 的内容大概是这样的--- name: conventional-commit description: 根据当前 git diff 生成符合 Conventional Commits 规范的提交信息。当用户需要在终端执行 git commit 时使用。 version: 1.2.0 tags: [git, workflow] when_to_use: 用户准备提交代码且没有明确指定提交信息时。 --- # Conventional Commit 生成 1. 先运行 git diff --cached 查看暂存区的变更内容。 2. 分析变更涉及的类型feat、fix、docs、style、refactor、test、chore。 3. 提交信息格式type(scope): subject 4. 如果变更较大生成完成后询问用户是否需要在 subject 后补充 body。你可能会问就这么点内容Agent 自己就能写为什么还要做成技能原因是做成技能后这套流程可以被多个工具共同引用而且可以在 SKILL.md 的同级目录放一个 templates/commit-template.txt让 Agent 严格按照模板填充避免每次输出的格式飘忽不定。这类文件放在技能目录里比塞进 prompt 更好维护。3.3 中枢怎么把技能“注入”到不同工具这是整个项目中最麻烦的部分没有捷径只能一个个适配。我整理了一个映射表标明每个工具读取技能的位置和格式工具技能存放位置格式要求Claude Code.claude/skills/name/SKILL.mdMarkdown frontmatterCursor.cursor/rules/*.mdcMarkdown支持 glob 匹配Trae.trae/rules/*.md类似 Cursor 的规则文件CodexAGENTS.md可以直接用 include 引用Continue~/.continue/config.yaml以 command 形式注册中枢要做的事情是读取技能库索引按目标工具的适配器生成文件再复制到对应的路径。为了一次找一个技能而不是把 54 个技能全部复制过去我加了一个“按项目路由”的功能检测当前项目类型只把相关技能部署到对应目录。比如前端项目只部署 frontend 和 commit 相关技能Python 项目只部署 pytest、lint 相关技能这样不会把无关技能塞满全局。4. 常见问题与排查实录4.1 技能安装后 Agent 完全不吃这一套这是几乎每个朋友第一次集成时都会遇到的坑。多数情况下不是技能文件本身写错了而是放在了错误的目录。Cursor 识别 .cursor/rules 里的 .mdc 文件需要文件名带编号比如01-conventional-commit.mdc否则排序不稳定规则可能被其他全局规则覆盖。Claude Code 则要求目录名必须和 SKILL.md 里的 name 完全一致大小写也不能错否则扫描不到。我试过最诡异的一个问题是某个技能文件用 VS Code 打开正常但 Claude Code 就是加载不了后来发现是文件编码问题Windows 下保存成了 UTF-8 with BOMAgent 解析 frontmatter 时读到一个不可见字符直接跳过。解决方案也很简单中枢在导出时统一转成无 BOM 的 UTF-8并且每次启动时扫描一遍库内文件的编码格式。4.2 Agent 总是该触发时不触发技能不触发多半是 description 写得不够具体或者触发逻辑和实际命令不匹配。举个例子把 description 写成“处理 Git 操作”看起来没错但 Agent 在遇到“git push 失败”和“帮我撤销提交”时都可能不知道该不该调它。更好的做法是写清楚边界“仅用于生成提交信息不需要处理分支合并或远程推送。”另外很多工具对技能描述做语义检索时会给全局规则更高权重如果你的 AGENTS.md 或 .cursor/rules 里本身写了太多公共规则技能描述再长也容易被淹没。我后来把公共规则压缩到最小化把大段指导文本都挪进技能内部只留一个“遇到什么场景去读哪个技能”的索引触发率明显提升。4.3 技能内容太长每次对话都被截断有的技能不小心写得像一本书光是执行步骤就有几百行。这类技能一旦被加载会挤占模型的上下文窗口导致后续真实代码分析的容量严重缩水。我的经验是SKILL.md 本身只保留执行流程和关键规则尽量控制在 60 行以内更大的内容放到参考资料目录中由 Agent 按需读取。比如技能需要详细分析代码仓库的结构不要在 SKILL.md 里堆一堆目录说明而是放一个reference/architecture.md文件并在 SKILL.md 里写“先读取 reference/architecture.md 获取项目架构信息”。这样 Agent 只在真正需要时才去读那个文件不要把所有东西一次性塞进上下文。这个习惯养成了之后我的 Agent 会话长度明显更健康出错的次数也少了。4.4 多个工具同步时互相覆盖配置这个坑是最容易被忽视的Cursor 和 Trae 共用同一个项目时会同时读取规则目录如果你在中枢里分别导出规则到两个目录有些工具会把全局规则和项目规则合并给出一个超出预期的优先级顺序。我在做多工具同步时遇到过两次配置被覆盖的情况后来养成了一个习惯每次导出前先备份当前目录并且在中枢里记录“上次导出快照”有变更时提示用户确认。同步的本质问题是双向的如果你在工具里手动改了一些内容中枢下一次导出可能把它覆盖掉。所以我在设计上强制报废了“自动覆盖”改成“导出到新建目录后对比差异确认后再替换”宁可通过多一步确认也不要做不可恢复的写入。5. 一些补充建议和我的实际感受这套技能中枢方案落地以后我最大的感受不是“技能多了”而是“脑子轻松了”。以前我始终担心某个工具里配置过期、某些技能版本不一致现在只要在桌面中枢里维护一份标准技能源所有工具的配置都能快速对齐。它不会让某个单工具的 Agent 表现猛然变强但会让多工具协作的体验平滑得多。如果你也想复制这套玩法我有几个很实际的建议第一步先盘点自己经常用的工具和技能不要一上来就追求 54 个工具全适配。先覆盖日常使用最多的三五个把技能的通用格式跑通再慢慢加适配器。技能目录里只保存真正结构化、值得复用的内容一次性 prompt 就别放进来了否则索引会越来越脏。建议把技能库本身纳入 Git 管理每次修改都有版本记录配合中枢里的版本号可以快速回退到任意历史版本。给每个技能的 description 留出刻意收窄的边界而不是写一句包罗万象的万能描述这会直接影响 Agent 的调用准确性。最后再分享一个小技巧如果你也经常在终端工具和桌面工具之间切换可以给中枢加一个“终端导出模式”把常用技能按工具要求直接生成到剪贴板或者临时目录这样不需要打开界面也能完成配置。我后来大部分操作都是在这个模式里完成的省掉了不少来回点击的时间。技能管理这件事本质上不是把文件归类整理这么简单它是在给 Agent 世界建立一套“统一的语言”。工具会更新规则会变化但只要你的技能源保持干净和结构清晰任何新工具出现时都能快速接入。希望这篇复盘能给你一些启发也期待看到你更顺手的 Agent 工作流配置。