1. 项目概述为什么我会去折腾一个“技能管理器”我先交代一下背景。我日常主力工具是Cursor Claude Code Continue这三个偶尔还要用Windsurf和Zed应付不同项目。过去大半年我一直在做同一件事把同一套编码规范、代码审查规则、重构流程、甚至提示词片段在每一个工具的配置目录里各写一份。Cursor要.rulesClaude Code要SKILL.mdContinue要rules文件Zed有自己的一套agent体系。每次改一条规则我就要在五个工具里分别改一遍改完还要担心哪个工具的语法格式写错了导致规则静默失效。最让我崩溃的一次是我给一个Python项目写了一条“禁止使用全局变量存储配置”的审查规则。在Claude Code里写完整套skill后我忘记同步到Cursor的规则文件里。结果Cursor那边帮我重构代码时直接给另一个模块也安了全局配置对象两边的架构风格马上分叉之后花了一整天才把两边代码重新对齐。所以这个标题里提到的“Skills Manager”其实就是要解决我上面描述的这一类问题统一管理散落在多个AI编程工具里的Agent技能让同一份技能定义能被不同工具识别、加载和执行。所谓“54”指的是这套系统覆盖的工具生态数量——截止到我写这篇文章时市面上叫得出名字的、带Agent能力或自定义技能机制的编程工具我数了一下主流加小众的加起来确实超过54个其中我实际接入和验证过的大概有30来个。这个数量不是营销噱头是我在维护这个管理器时真实跑过的适配列表。这个项目适合谁看如果你手里同时用两个以上AI编程工具而且已经遇到了“同一个项目在不同工具里的表现不一样”“规则改一处要改五处”“某个工具不认我写的规则文件”这类问题那这篇内容值得你完整读一遍。如果你是那种只用一个工具、从没碰过自定义规则的人也可以看因为你迟早会遇到“工具升级后我的规则失效了”这种坑这篇文章里会给到排查思路。2. 核心认知拆解先搞清楚各家工具的“技能”到底是个什么东西要统一管理技能第一步不是急着写代码而是先摸清楚各家AI编程工具的技能机制长什么样。我给一个比较通用的定义Agent技能 一套能被AI工具读取、理解、并在合适场景下自动调用的规则/配置文件集合。但每个工具对它的叫法、目录结构、加载机制、语法格式都不一样这里我梳理一下主流工具的技能形态。2.1 主流AI编程工具的技能机制对比我先用一个表格把我知道的整理出来这个表格是我在实际适配过程中一点点积累的准确性比网上很多流传的版本要高工具名称技能机制名称存放位置配置格式自动加载时机Claude CodeSkills项目根目录 .claude/skills 或全局 ~/.claude/skillsMarkdown YAML frontmatter会话启动时扫描并注入上下文CursorRules项目根目录 .cursor/rules纯Markdown或.mdc文件按glob匹配自动附加到上下文ContinueRules项目根目录 .continuerulesMarkdown文本相似度匹配后加载WindsurfGlobal Rules / Memories全局配置目录 项目.windsurf/rulesMarkdown 特定语法标记会话启动时整体注入ZedAgent Skills项目根目录 .zed/skills 或 .agent/skillsMarkdown JSON frontmatter按需由agent检索加载JetBrains AICustom Prompts工具内配置XML格式的prompt模板手动或按指令触发从这个表能看出来虽然大家都叫“技能”但底层机制差异很大。Claude Code的SKILL.md是带YAML frontmatter的metadata里可以写name、description、allowed-tools这些字段AI会读description来决定什么时候用这个技能。Cursor的.mdc则更接近“规则注入”它支持glob patterns来指定哪些文件的会话中加载对应规则。Continue那个rules文件更特殊它依赖向量相似度匹配也就是说你得把规则写得足够精确AI才可能在对话中主动召唤它。2.2 技能的“原子性”比你想的更重要我在拆解各家机制时发现判断一个技能设计得好不好最核心的标准是它的原子性。什么意思一个技能应该只做一件事并且可以被独立描述、独立测试、独立复用。举个例子我见过很多人把整个项目的架构规范、代码风格、测试要求、部署流程全部写进一个巨大的SKILL.md里动辄七八百行。这样看起来“很全”但实际运行中问题很大AI每次对话都要把这个大文件全量塞进上下文窗口白白浪费token。某个具体任务需要的是“代码审查规则”结果被几千行架构文档稀释了指令权重。你想让另一个工具复用其中“commit message规范”这条技能根本没法单独抽取。我后来每个技能都拆到极小比如下面这样python-review/ # Python代码审查技能 SKILL.md # 主描述文件 hooks/ pre-commit.py # 审查前的自动化检查脚本 examples/ bad.py # 反例 good.py # 正例这也引出了我设计Skills Manager时的一个核心原则统一的是技能的“容器格式”而不是技能的“内容粒度”。每个技能内容依然由你按原子性原则编写管理器只负责保证这些技能在不同工具之间能无损转换和分发。3. 架构设计思路统一格式、场景路由、双向同步现在到了这个项目的核心部分。Skills Manager本质上是一个跨平台的桌面应用它在本地运行负责管理一个统一的技能仓库然后把每个技能分发到各AI工具的对应目录里。整体架构我拆成三层统一格式层、路由分发层、同步调度层。3.1 统一格式层为什么需要一套“中间表示”要让不同工具都能识别同一个技能直接做法是让一个工具去兼容所有工具的格式这显然不现实。反过来想我定义一套通用的中间表示Intermediate Representation所有技能先写成这套格式再由管理器转换成各个工具的实际格式。这套中间格式长这样{ id: python-review, name: Python代码审查, version: 1.2.0, description: 审查Python代码中的全局变量、类型注解缺失和异常吞噬问题, triggers: [*.py, pyproject.toml, requirements.txt], body: skill-content.md, attachments: [hooks/pre-commit.py], targets: { claude-code: { path: .claude/skills/python-review/SKILL.md, transform: claude-v1 }, cursor: { path: .cursor/rules/python-review.mdc, transform: cursor-mdc }, continue: { path: .continuerules, transform: append } } }这个JSON里最关键的是targets字段。它声明了这个技能要分发到哪几个工具、写到什么路径、用什么转换器。我这里强调一点转换器不是简单地把Markdown拷过去。Cursor的.mdc格式对描述和规则正文是有区分要求的Claude Code的SKILL.md则要求frontmatter里必须有name和description且不能乱写allowed-tools的值。这些细节在转换时必须逐项处理。3.2 路由分发层按项目和场景决定技能去哪里技能仓库建好之后下一个问题是怎么决定一个技能该分发到哪些工具。这里面有个很重要的概念我叫它“场景路由”。一个项目通常是按技术栈来区分环境的Python后端项目涉及到的技能和React前端项目涉及到的技能交集很少。如果我把所有技能全部分发给所有工具那技能仓库体积会爆炸AI上下文也会被无效信息塞满。所以我设计了路由策略项目路由基于项目根目录的特征文件比如pyproject.toml、package.json、go.mod自动推断该项目所属的技术栈分类只分发对应类别的技能。路径路由基于技能里配置的triggers字段当某个文件路径匹配时才激活对应的技能。比如只有打开.py文件时才把python-review注入到当前会话。手动路由我也支持手动指定比如团队里只有一个成员需要某个技能那这个技能只分发到他的本地配置里。从实际体验看路由策略是这套管理器最值得花时间调优的部分因为它直接决定了AI工具的性能表现。分类太粗无用技能多分类太细很多技能永远触发不了。我目前采用的是“项目级粗筛 文件级细筛”的二级路由90%以上的场景够用。3.3 同步调度层解决“双向同步”这个魔鬼问题分发之后还有反向的需求——你在某个工具里手动改了技能希望能同步回管理器。这里有个天然的不对称性管理器到工具格式是可控的我可以保证转换后一定能被工具读取。工具到管理器工具各自的配置文件可能被AI或用户修改过、添加过工具特有的语法直接逆向解析容易出错。所以我放弃了“全自动双向同步”这个诱惑而是采用单向主从 冲突预览的机制。管理器作为唯一事实源source of truth对外分发。当你手动改了某个工具的技能文件后管理器会检测到差异弹窗列出“以管理器为准”还是“以该工具为准”让你做一次确认。这个设计牺牲了一点自动化程度但避免了灾难性的覆盖。4. 实操过程从零搭建一个可用的Skills Manager讲完理论直接上实操。我用的技术栈是Tauri 2.0 Rust React TypeScript选了Tauri是因为它打包体积小、内存占用低而且我只需要访问本地文件系统不需要太多系统权限。如果你更熟悉Electron完全可以用它替代架构逻辑是一样的。4.1 技术选型为什么我选了Tauri而不是Electron在桌面端Tauri和Electron是最常见的两个选择。当时我列了一个对比清单维度Tauri 2.0Electron安装包体积约5-10MB约80-150MB内存占用约200-400MB约600MB-1GB开发语言Rust后端 Web前端Node.js Web前端文件系统操作需要Rust侧写入API直接Node.js API跨平台支持Windows/macOS/LinuxWindows/macOS/Linux选Tauri的核心原因其实是跨平台编译的产物一致性。Electron在不同系统上对文件路径的处理有些微差异而我在Rust侧用std::path::PathBuf处理路径可以确保Windows的C:\project\xxx和macOS的/Users/xxx/project在拼接规则时行为完全一致。这对这种以路径操作为核心的工具来说非常关键。4.2 目录结构与核心模块设计项目根目录我按模块拆分不搞单文件堆砌skill-hub/ src/ main.rs # Tauri入口注册命令 commands/ sync.rs # 同步逻辑分发/回采 convert.rs # 格式转换器注册表 router.rs # 场景路由判定 watcher.rs # 文件变更监听 store/ manifest.json # 技能清单元数据 skills/ # 技能源文件中间格式 frontend/ src/ # React界面 targets/ # 各工具的适配器定义 claude-code/ cursor/ continue/ ... config/ settings.json # 用户级配置manifest.json是核心它记录着所有技能的元数据和分发状态。每次启动时管理器会先加载这个文件然后遍历skills/目录读取所有技能再根据配置文件里的路由规则生成分发计划。4.3 关键转换器实现以Claude Code和Cursor为例转换逻辑是这项目里最不好写的部分。我拿两个典型例子说一下。Claude Code的SKILL.md格式要求在文件开头用YAML frontmatter定义name和description--- name: python-review description: 审查Python代码中的全局变量、类型注解缺失和异常吞噬问题。当用户请求代码审查或打开.py文件时使用。 allowed-tools: - Read - Edit - Grep ---这里有个坑description写不好AI永远召唤不出这个技能。Claude Code会基于description的语义相似度来判断是否调用技能。“审查一下这个文件”和“帮我看看这个文件有什么问题”在语义上接近但如果description里只写了“审查”两个字前者可能触发不了后者就更难说。我的中间格式里描述字段写得比较详细转换器拿到description后会自动扩展成Claude Code偏好的“场景 触发条件 执行动作”三段式结构实测触发率比简略描述高很多。Cursor的.mdc格式则完全不同。它对“描述”和“规则正文”做了明确区分描述部分用于告诉模型何时引用规则正文才是真正注入上下文的规则内容--- description: Python代码审查规则全局变量、类型注解、异常吞噬 globs: [*.py, pyproject.toml] --- - 禁止使用全局变量存储配置 - 所有公开函数必须带有类型注解 - 禁止except Exception后静默pass我的转换器会读取中间格式里的triggers字段自动填充为globs。同时中间格式的body部分是规范化的规则列表转换时每行自动加上-前缀防止AI把多行规则当成一段文字导致权重稀释。4.4 具体部署步骤第一次拿到管理器怎么跑起来如果你不想从我这份源码开始而是想直接用类似的机制我建议你按以下流程部署第一步初始化技能仓库建一个skills/目录每个子目录代表一个技能。新建技能时不要直接写配置文件先创建一个SKILL.md草稿用你最习惯的自然语言描述技能目的、触发场景和具体规则。把这个草稿视作“母本”。第二步声明目标工具在每个技能的manifest片段中用targets字段声明要分发到哪些工具。初次配置时先只选两个工具跑通流程别一上来就全平台分发。第三步执行首次同步运行同步命令管理器会读取母本、调用对应转换器、把生成的文件写入工具指定的配置路径。同步完成后重启AI工具在新会话中测试技能是否被正确触发。这一步我建议用小技巧验证在工具里输入“输出当前加载的所有技能名称”如果工具支持可以直接看到技能是否注入。第四步配置自动监听开启watcher监听skills/目录和工具配置目录的变动。以后你改技能母本管理器自动分发你手动改工具配置管理器弹冲突提示让选择是否回采。4.5 一个完整的技能实例Python代码审查技能我手写一个完整的python-review技能配置参考一下中间格式的完整度--- id: python-review name: Python代码审查 version: 1.2.0 description: 审查Python代码中的全局变量、类型注解缺失和异常吞噬。适用于代码审查会话或打开.py文件时。 triggers: - *.py - pyproject.toml - requirements.txt body: | 1. 禁止使用全局变量存储配置或状态所有可变状态必须显式传入函数或封装为类。 2. 所有公开函数和方法必须带有完整类型注解包括参数和返回值。 3. 禁止捕获Exception后静默pass。如果必须吞异常必须写日志说明原因。 4. 优先使用pathlib.Path代替os.path拼接路径。 targets: claude-code: path: .claude/skills/python-review/SKILL.md cursor: path: .cursor/rules/python-review.mdc continue: path: .continuerules append: true分发后Claude Code那边会生成带frontmatter的SKILL.mdCursor那边会生成带globs的.mdcContinue那边则会把规则追加到.continuerules文件末尾。这就是“母本一次多端生效”的完整流程。5. 实操常见问题与排查技巧我跑这个管理器跑了四五个月踩了不少坑下面把这些经验整理成速查表供参考。现象原因解决方案技能文件存在但AI始终不触发description/描述写得过于模糊或触发条件不匹配重启会话精炼描述中的触发场景词检查triggers是否覆盖实际操作路径Cursor规则总是被系统规则截断单文件过大或跨多个会话累积注入拆分为更小的.mdc文件用globs精确控制加载范围Claude Code报“无法解析SKILL.md”frontmatter字段格式错误或存在多余字段检查name和description是否齐全allowed-tools不要写工具不支持的名称同步后工具配置目录出现奇怪权限错误多数是macOS的沙盒机制或Windows文件权限问题检查工具是否有写入目标目录的权限Tauri配置里申请必要的fs权限Continue的rules文件越长匹配越差文本相似度匹配对超长文件效果差尽量每条规则独立成短文文件避免堆成一大坨双向同步时管理器把工具侧手动配置覆盖了冲突处理策略配置为“以管理器为准”建议改为“冲突预览”在每次覆盖前先人工确认5.1 排查“规则没生效”的三个由浅入深的步骤遇到“我明明配置了AI就是不按规则执行”我的排查顺序是先看文件是否真的被加载大部分工具的日志里会打印加载了哪些规则文件。Cursor可以在开发者工具里输入Cursor.rules查当前上下文规则Claude Code可以用/skills命令查看已加载的技能列表。这一步能区分“配置没写好”和“配置写了但没读到”两种不同情况。再看配置文件有没有被转换器正确生成很多用户直接在管理器里改母本然后发现目标工具里的文件是旧版本。原因是watcher没监听目标工具目录管理器不知情。这时候要主动触发一次“强制同步”。最后怀疑触发条件有一种很诡异的情况是技能文件本身没问题但工具的glob匹配规则跟你预期不一致。比如Cursor的glob只匹配文件路径的末尾如果你在triggers里写了src/**/utils/*.py它可能在打开src/app/utils/helper.py时反而匹配不上因为cursor内部会把glob转成正则再匹配。这种问题只能靠打日志或逐个文件测试来定位。5.2 跨平台路径差异性最先踩到的坑这个项目跨平台开发和使用的过程中路径分隔符和路径拼接规则是个很容易被忽略的大坑。我在Windows上开发时遇到过一个现象用path.join(src, skills)拼接的路径在macOS上没问题在Windows上会被自动翻译成src\skills这算正常。但坑在于工具侧的配置期望路径是src/skills这种正斜杠格式如果用反斜杠写进配置文件的path字段工具可能识别不了。解决办法很简单统一所有存进配置文件、manifest、和路由规则里的路径一律用正斜杠/。在代码内部转换时再根据操作系统转换为本地格式。我的转换器里专门写了一个normalize_path函数在任何系统上统一输出Linux风格路径。5.3 关于“54工具”的真实坦白趁这个机会说实话54这个数字指的是清单上列出来的、理论上可以接入的工具数量不是我完整适配过的数量。我完整适配、跑通过自动化测试的大概在三四十个左右。剩下那些要么是相对小众的IDE插件要么是API文档本身不完整适配成本过高。所以我设计时留了个“适配器注册表”每个工具对应一个转换器接入模式是插拔式的。谁要适配一个新的工具只需要写一个targets/工具名/convert.js实现parse和generate两个函数就行。6. 写在最后我对这整套方案的体会技能管理的本质是给AI编程工具建立一套可控的、可迁移的、有版本概念的“长期记忆”。我之前所有的纠结——规则散落、改一处漏一处、工具升级后规则失效——本质是因为长期记忆被锁死在了各个工具各自的实现里。Skills Manager做的事情很简单就是把记忆抽离出来放到一个独立的、中立的层。实际操作中我个人最大的收获不在管理器的代码本身而在于建立了一套强制性的技能设计规范每个技能必须有明确触发场景、必须原子化、必须写清反例。这一点对AI编程工具的提效影响巨大。以前随手写一个规则文件就完事了现在每写一个技能都像在写文档虽然慢但积累起来的效果很值。如果以后要扩展我觉得有两个方向值得尝试一是给同一个技能做A/B版本对比让AI分别用两版技能方案处理同一批任务自动评估哪版产出更好二是做技能依赖解析让一个技能自动引用另一个技能而不必把重复内容拷贝来拷贝去。这两个方向都需要一定的提示工程和评测工程基础但方向上我是比较确定的。最后分享一个小技巧如果你现在不打算写任何代码只是想把多工具的规则管理起来可以先从统一目录结构入手——在你本地建立一个skill-hub/目录把所有规则以Markdown格式集中存放再手动复制到各工具配置目录。这个原始操作虽然费点功夫但只要坚持下来后面迁移到自动化方案会非常平滑因为你的母本就是现成的。