前阵子我把自己常用的AI编程工具从三个换到了七个，结果最头疼的既不是大模型怎么选，也不是上下文窗口够不够，而是每个工具里那套给Agent用的“技能”怎么维护。Cursor有Rules，Claude Code有Skills，Cline有.cline/rules，Aider读CONVENTIONS.md，Windsurf自己一套指令体系，Trae和Codex CLI又是完全不同的一种写法。技能一多，同一个需求我得在五六个地方各改一遍，改完还经常发现某个工具的语法不兼容。折腾了大概两周，最后落地的方案就是用一个叫Skills Manager的本地桌面工具，把所有AI编程工具的Agent技能统一收进一个跨平台中枢里管理。这篇文章就是我的完整落地记录，包括为什么这么设计、目录怎么组织、映射规则怎么配、实际跑起来会遇到哪些坑，给同样被技能配置搞到崩溃的人一个可以直接抄作业的参考。
1. 为什么我会折腾一个“桌面中枢”
1.1 多工具并行时的技能管理困局
先说说痛点。我不是只在一个IDE里干活的人，日常大概是这样的：主力编辑器用Cursor写业务代码，复杂一点的架构设计会切到Claude Code跑完整Agent流程，命令行里还挂着Aider处理一些批量重构，偶尔用Cline跑一下浏览器自动化。这些工具各有各的受众，但都对“给Agent注入自定义行为”这件事有原始需求。比如我想让所有Agent都遵守“修改代码前先写测试”“日志必须包含上下文ID”“不要动公共接口签名”这类团队规范，理论上每个工具都该知道这些规则。
问题就出在“每个工具都有自己的规则体系”这件事上。Cursor用的是.rules文件，Claude Code的技能叫Skills，目录结构是.skills/；Cline要的是.cline/rules；Aider比较粗暴，直接读仓库里的CONVENTIONS.md；Windsurf那边更麻烦，不同版本还分别支持.windsurf/rules和.commands。我最早是复制粘贴，哪个工具缺了就去翻之前的版本，结果每次更新规则都是一场灾难。更崩溃的是，同一份技能描述在不同工具里效果还不一样：有的工具对Markdown里的标题敏感，有的工具要求YAML frontmatter，有的工具只认纯文本。单独看每个工具都挺好，合在一起就成了维护地狱。
1.2 Skills Manager能解决什么问题
Skills Manager这个名字听起来挺普通，但它的定位很明确：做一个本地桌面中枢，把分散在各个AI编程工具配置文件里的技能统一管理起来。它不是你某个Agent技能的编辑器和存储库，还是一个向目标工具“分发”技能的中间层。你在一个界面里写一份技能定义，它可以自动转换成符合各种工具要求的格式，然后写进对应的配置目录或者项目文件里。
我选择桌面端而不是纯命令行或者Web服务，原因很实际：AI编程工具的配置大多在本地，而且经常要跟IDE的实时联动。如果我每次改技能都要跑一段CLI或者开个浏览器页面，效率反而更低。桌面应用可以直接监听文件变化，改了技能自动映射到所有工具，这在“一边开Cursor一边开Claude Code”的场景下尤其顺。跨平台也是刚需，我在Windows台式机和MacBook之间来回切，这个工具要是只支持一个系统，那对我来说就等于没用。Skills Manager内置了54+工具的适配模板，我这里面真正会用到的也就七八个，但多出来的好处是可以随时试用新工具，不需要重新学习一套技能管理方式。
2. 核心设计与功能拆解
2.1 技能仓库：统一格式与元数据
Skills Manager的核心是一个“技能仓库”，不是简单的文件列表，而是一种带元数据的结构化存储。它把每个技能的描述统一成一套Schema，至少包含：技能名称、触发场景、适用范围、具体指令、依赖条件、目标工具白名单。我实际用的格式是YAML+Markdown混合体，YAML部分存元数据，Markdown部分存给Agent看的具体操作指南。这样设计是因为大部分AI编程工具最终读到的都是文本内容，纯JSON虽然机器可读性强，但对人类写长指令并不友好；纯Markdown又缺结构化信息，没法做自动映射。
我常用的一个技能长这样，名字叫“代码审查前自查”：
name: review-self-check description: 在提交代码给AI审查之前，让Agent先执行一轮基础自查 triggers: [pre-review, code-review] instructions: | ## 自查步骤 1. 检查未提交的变更中是否有调试日志残留 2. 确认函数命名与项目规范一致 3. 若修改了公共接口，必须在描述中列出影响面 4. 返回一份自查清单，逐项标注pass/fail targets: - cursor - claude-code - cline - aider - windsurf这份文件在Skills Manager里被当作一个“技能定义”。它本身不在任何工具的配置目录里，只躺在中枢的仓库目录下。当我需要它生效时，中枢会把它转换成对应工具的规则文件，再写到对应位置。这个设计的好处是技能定义只有一份，改的时候不用考虑每个工具的语法差异，坏处是中枢得维护足够多的适配器，否则转换出来的格式不被目标工具识别。
2.2 工具适配层：解释“54+”在哪里
所谓“54+”，指的是Skills Manager内置的工具适配器数量。每个适配器本质上是一段转换脚本，知道目标工具读什么文件、用什么格式、放在哪个目录。比如Cursor的适配器会把YAML里的instructions字段转成Markdown规则，生成.cursor/rules/review-self-check.mdc文件；Claude Code的适配器会生成.claude/skills/review-self-check/SKILL.md，保留frontmatter；Aider适配器则直接把规则追加到CONVENTIONS.md里。
不同适配器差异很大，我举三个典型的：
- Cursor风格：一个
.mdc文件，可以带description和globs，在文件头部用YAML frontmatter声明适用范围。Cursor对规则文件的识别比较宽松，主要是按文件名和内容里的关键词触发。 - Claude Code风格：一个名为
SKILL.md的文件放在.claude/skills/<skill-name>/目录下，文件内容支持标准Markdown，Claude Code会读取frontmatter里的name和description来决定何时调用。 - Aider风格：一个纯文本约定，写在
CONVENTIONS.md里，没有目录结构，没有frontmatter，所有规则平铺。Aider会把整个文件内容拼进系统提示词里，所以不需要触发词，但也不能写太长。
这类适配器只要有一个版本更新导致格式变化，就需要更新一次。我其实不太关心它到底支持了多少个工具，我关心的是它能否在“新增某工具支持”时不需要我手动改一堆文件。Skills Manager的适配层是插件式的，用户也可以自己写一个适配器脚本放进去，这个后面实操部分我再细说。
2.3 桌面端交互：跨平台体验
桌面端UI的主要价值在于“可视化地看出技能状态”。我最早用纯文件管理，最大的问题是不知道某条规则到底有没有被启用。SQLite数据库里记录着每个技能的状态、映射关系、最后修改时间，界面上可以一眼看到：这个技能当前激活了几次、影响哪些工具、哪些目标文件已经过期。
跨平台体验方面，Skills Manager用的是Web技术封装，底层是Electron，数据目录按系统习惯放：Windows在%APPDATA%下，macOS在~/Library/Application Support下，Linux在~/.config下。虽然底层技术一样，但它在三个平台上都做了系统原生菜单和通知。我最常用的是它的“全局快捷键”，按一下就能唤起技能列表，不用切窗口。文件系统监听也做得比较稳，Windows上不会因为文件占用报错，macOS上能正确识别文件变化事件。这些细节看着小，但对一个每天切换多台电脑的人来说，体验差别很大。
3. 实操过程与关键环节
3.1 安装与首次启动
Skills Manager的安装没什么特殊的，去官方发布页下载对应平台的安装包即可。Windows上是.exe，macOS是.dmg，Linux有.AppImage和.tar.gz两种。我建议Linux用户优先用.tar.gz而不是AppImage，因为后者在某些发行版上要另外装FUSE依赖，而这种依赖往往还不一定有。AppImage的好处是免安装，坏处是沙箱环境跟系统的集成度不高，文件监听有时候会失灵。
安装完后第一次启动，它会询问两件事：默认技能存储位置，以及需要启用哪些目标工具。我建议存储位置用默认的~/.skills-manager，不要放在项目仓库里，因为技能仓库里存的是“母版”，不应该跟着某个项目走。目标工具选择可以多选，但第一次别选太多，先挑你平时最常用的两三个，把流程跑通，再逐步增加。选择完毕之后，它会扫描本地已安装的AI编程工具配置文件，生成一个“现状概览”，告诉你哪些工具目录已存在、哪些缺失。这一步的目的是让后续映射不会覆盖已有的文件。
3.2 新建一个技能并映射到三个工具
新建技能的操作很简单：在主界面点“新建技能”，填名称、描述、触发词、指令正文。但真正核心的是“映射”这一步。我拿前面那个review-self-check技能举例，新建完成后，我把它映射到Cursor、Claude Code、Aider三个工具上。
- 映射到Cursor时，Skills Manager问我这个规则是全局生效还是只对某些代码路径生效。我选了全局，它就在
.cursor/rules/下生成了review-self-check.mdc。文件内容会自动带上Cursor要求的frontmatter，比如description字段和globs字段。 - 映射到Claude Code时，它会在
.claude/skills/review-self-check/下创建目录，并生成SKILL.md。我把trigger词填的是pre-review和code-review，它会把这些词写进frontmatter的description里，方便Claude Code自然语言匹配。 - 映射到Aider时，它会把指令正文追加到
CONVENTIONS.md里，并自动在前面补一条“Aider会读取以下约定”的标题。Aider不区分技能名称，它就是全量读取，所以如果多个技能都映射到Aider，这些技能会被合并成一个文件。这点我在映射前没注意，结果同一个文件里出现了两条重复规则，跑起来后Aider把前面那条和后面那条都读进去了，等于我做了一次重复强调。虽然不影响功能，但会浪费token。
映射完成后，Skills Manager会显示一张“目标文件清单”，并标注每个文件是否已写入、是否需要覆盖。它默认不会覆盖已有文件，如果检测到目标文件存在内容更新，会弹窗问你是覆盖、追加、还是忽略。我基本都选“覆盖”，因为技能仓库里的才是最新母版，工具目录里的文件只是衍生物。但如果你手头有直接在工具目录里改过的规则，千万别急着覆盖，先备份一下。
3.3 批量导入与版本回滚
技能一多，你就不想一个个新建了。Skills Manager支持批量导入，可以从一个包含多个.md或.yaml文件的目录批量导入技能定义。导入时它会自动解析文件名作为技能名称，把正文作为指令内容。但这个自动解析有个坑：如果Markdown文件开头有YAML frontmatter，它就会优先读YAML里的name和description；如果没有，它会用文件名当name，描述留空。描述留空的技能在触发能力上会大打折扣，因为很多工具是靠语义描述来判断何时调用技能的。所以批量导入后，我养成了一个习惯：逐个检查新导入技能的“描述”字段，不完整的补上。
版本回滚是我最依赖的功能之一。有一次我把某个技能的指令改错了，映射到Cursor后导致所有代码审查请求都附带了一段无效JSON。我原本以为得靠手工改回去，后来发现Skills Manager会在每次映射前自动备份目标文件，并在“历史记录”里保存每次变更的差异。我可以选择一个技能版本，直接回滚到三小时前那个状态，然后再重新映射所有目标工具。这个功能帮了我大忙，强烈建议所有人都用起来。它本质上就是给配置文件做了一层带界面和语义化的Git，只是你不用去记命令行。
4. 常见问题排查与心得
4.1 技能不生效的排查步骤
先说什么叫“不生效”：技能明明映射成功了，目标工具目录里也有文件，但Agent完全不理会你写的指令。我遇到过好几次，最大的原因其实很简单：目标规则文件里没有写触发条件，或者触发条件跟实际场景对不上。比如Cursor的.mdc文件，如果我没写globs字段，它只在非常有限的情况下被自动调用，大部分时候都静默跳过。又比如Claude Code的Skill，如果description里没有足够明确的适用场景词，Agent就不知道什么时候该用它。
遇到这种问题，我一般按这个顺序排查：
- 打开Skills Manager的技能详情页，确认这个技能的“激活开关”是开着的。是的，它有一个总开关，关着的时候映射文件不会被同步更新，但目标目录里可能还残留着旧文件。
- 检查目标工具的配置目录里，文件内容是否跟技能仓库里的母版一致。不一致就手动“重新同步”一次。
- 打开目标工具自己的调试模式或日志，看看它有没有加载到该文件。Cursor在开发者工具里能看到加载的Rules；Claude Code在启动时会打印加载了哪些Skills；Aider呢，你在对话里问它“你有哪些约定”就能验证。
- 确认触发词没有拼写错误。依赖语义触发的技能，如果描述里全是英文场景词，但你的Agent对话里用的全是中文，那大概率不会触发。我后来把所有中文工具对话时用的技能描述都补了一份中文触发词。
4.2 路径分隔符与跨平台坑
跨平台工具最大的坑就是路径。我一开始在macOS上配好的技能，用Git同步到Windows电脑后，目标文件里全是/Users/xxx/docs这种Unix路径，Windows上的工具读不懂，规则直接失效。Skills Manager在设计上其实做了路径抽象，但我发现它默认只处理它自己能控制的路径，如果技能正文里的Markdown里自己写死了相对路径，它是不会帮你改的。比如我在Windows上定义一个技能，内容是“读取./output/report.md”，这个路径没问题；但如果我写的是“读取/home/user/output/report.md”，Windows上就废了。
解决办法有两个：一是技能正文里尽可能用相对路径，并且统一用./开头，避免绝对路径；二是如果必须用绝对路径，就在技能定义里加一个平台相关字段，类似path-windows: C:\xxx，但这样又破坏了“一份定义到处用”的初衷。我个人建议是：所有能被Agent操作的文件都放在当前工作目录或子目录下，这样跨平台通用性最好。另外Windows上的换行符是\r\n，工具生成的规则文件通常用\n，虽然大部分AI编程工具能兼容，但某些严格解析的格式比如YAML，可能会出现缩进错乱。我一般会在同步前统一把换行符转成LF，后台设置里有这个选项。
4.3 团队协作中的冲突处理
如果团队里多人共用同一个AI编程工具配置目录，版本冲突是无法避免的。尤其是.cursor/rules这种直接放项目根目录的规则，每个人一同步就会覆盖别人的规则。Skills Manager本身不是协同工具，但它的技能仓库可以作为一个中间存储。我们团队的用法是：把技能仓库放到一个共享Git仓库里，每个人在本地用Skills Manager修改自己的技能，然后提交到Git；目标工具目录里的生成文件不提交，只提交技能仓库里的母版文件。
这样做的逻辑是，母版文件是结构化且带元数据的，可读性好，适合做Code Review；而目标工具目录下的文件是产物，谁同步谁生成，不需要进版本库。不过这个方案有个前提：每个人用的目标工具版本得一致。否则同一个母版在A机器上生成的Cursor规则，跟B机器上生成的Cursor规则格式会有细微差异。团队协作时也容易出权限问题，多人同时修改同一个母版文件会导致Git冲突，解决起来比较痛苦。我们的经验是给每个技能文件按“模块”拆分，而不是一个大文件装所有技能。比如前端规则一个文件，后端规则一个文件，数据库规则一个文件，冲突概率就大大降低。
4.4 需要留意的几个细节
第一个细节，技能内容别写太长。虽然Agent能读长文本，但目标文件越长，占的上下文窗口就越大，尤其是Aider这种全量拼接的方案，直接关系到每次请求的token消耗。我一般把单个技能控制在500字以内，如果超过500字就拆成多个技能，按触发场景分开。
第二个细节，不要在技能里放密钥或敏感信息。这个看起来像废话，但真的有人会把API Key直接写进技能里，然后同步到公共仓库。Skills Manager有一个“敏感内容扫描”功能，当检测到形如sk-、password、token的字段时会弹警告。我测试过几次，它对真实密钥的识别率还行，但不是万能，自己还是要保持敏感度。
第三个细节，定期清理不再使用的技能映射。我有时候为了试新工具会临时映射一堆技能，试完之后忘记关，导致每个目标工具目录下积压了十几条无关规则。这些规则不仅浪费Agent的上下文，还会干扰触发逻辑。我现在每个月固定检查一次：看每个工具的“已映射技能列表”，凡是不再需要的直接关掉映射，而不是只删文件。
第四个细节，工具版本升级后要重新同步。Cursor、Claude Code这些工具迭代速度很快，某个大版本更新后，规则文件的解析规则可能变了。如果升级后明显感觉某些技能不再触发，先别怀疑技能内容，大概率是格式变了。此时去Skills Manager的适配器更新列表里看看有没有对应更新，有就点一下升级，然后对目标工具目录重新执行一次“同步”。我最近一次遇到的是Windsurf新版本改成了.windsurf/rules目录结构，旧配置全不认，就是靠这个方式快速修复的。
5. 进阶玩法与扩展思路
5.1 用变量模板让技能变得可复用
如果你需要管理几十个技能，就会发现很多技能的正文里其实只有项目名、代码路径、语言风格不同。Skills Manager支持在技能定义里使用变量，类似{{project_name}}、{{code_path}}这样。映射的时候，它会弹出变量输入框，让你为每次映射填具体值。
举个例子，我有一条技能叫“按模块生成代码”，正文里有{{module_name}}占位。我同时映射到前端项目和后端项目时，各填一次module_name，生成的目标文件内容就不一样。这样我只需要维护一条语法规则，而不需要为每个项目复制一份。变量还有一个好处：可以在团队内共享技能模板，每个人映射时填自己的上下文，省去大量重复修改。
但变量也不是万能的，嵌套目录变量很容易出问题。比如你把{{code_path}}填成apps/backend/src，如果这个路径里含有多层，那么目标工具目录下的引用要写对相对路径才行。我自己踩过一次坑，把{{code_path}}用在了一个需要从项目根目录反向查找的场景，结果生成出来的路径少写了../，Agent找半天文件还是找不到。所以用变量时，最好先在目标工具的配置目录里手动模拟一次路径，验证无误再让技能正式生效。
5.2 自定义适配器：接入一个新工具
虽然内置了54+适配器，但你总会遇到某个新鲜出炉的AI编程工具不在列表里。好在Skills Manager的适配器是开放接口，允许用户写自定义转换脚本。我简单说下流程：在~/.skills-manager/adapters/custom/下建一个目录，里面放一个adapter.js，导出两个函数。parse负责把技能仓库里的母版转成目标工具的规则格式，write负责把结果写到正确路径。就这么简单，没有复杂的SDK，一个JS文件就能跑。
我写过一次适配器，那是一个比较小众的工具，它的规则文件要求是一个JSON数组。我当时的parse就是把母版里的instructions按换行符分割成数组，再把name和description塞进去。整个过程不到一百行代码。当然，自定义适配器只对我本人生效，如果要在团队里分享给别人，可以把适配器文件放到共享Git仓库里，让队友拖到自己本机的适配器目录下。这里提醒一句：适配器文件名跟目标工具标识必须一致，否则映射界面里找不到它。
5.3 从“技能管理”到“工作流资产”
用了一段时间后，我发现Skills Manager真正的价值不是它管理了多少文件，而是把“技能”变成了一种可沉淀的资产。以前我换个新工具，所有经验都得重新配置一遍；现在我可以把整个技能仓库导出成一个压缩包，换台电脑后导入，工具目录里的文件一重新映射就全都有了。这种模式其实可以延伸到更多场景：比如团队的入职培训，给新人发一个技能包，他导入后就能获得一套完整的工作规范；再比如做开源项目的人，把项目特有的提交流程、代码风格、审查要求都写成技能，随仓库一起发布。
我个人的体会是，管理AI编程工具的Agent技能，本质上是在管理“你和AI之间的协作协议”。单个工具里的规则文件只是协议的载体，真正的内容应该是跨工具、跨平台、可迁移的。Skills Manager给了我这层抽象，让我能把精力放在规则本身，而不是每换一个工具就去研究它怎么读这些规则。如果你也像我一样，手里的AI编程工具越来越多，技能规则越来越乱，我建议你试一下这个思路：先别管具体工具怎么配，把一个技能的母版写清楚，然后让它自己去适配所有工具。你会发现，统一带来的便利远远大于最初的迁移成本。最后再分享一个小技巧：技能仓库记得纳入Git管理，每次大规模改版前提交一次，出问题直接回退，比任何备份方案都省心。
