★ FEATURED ARTICLE 近半年我身边几乎所有写代码的人都在折腾AI编程。Cursor、Claude Code、Copilot、Codex CLI、Cline、Windsurf工具一个接一个往外冒每个都有Agent能力每个都能挂技能。听起来很美好但真到用的时候你会发现一个特别具体的痛点在Cursor里调好的一个代码审查技能想拿到Claude Code里用格式不认、路径不对、字段丢失等于重新写一遍。我前前后后试了十几个工具最后决定自己做一个跨平台桌面中枢项目名就叫Skills Manager专门统一管理这54个AI编程工具的Agent技能。这个工具解决的核心问题只有一个你只维护一套技能包按一下按钮它帮你翻译并部署到任意目标工具的技能目录里同时还能做版本管理、回滚和团队共享。这篇文章我从需求拆解讲到架构选型从实操流程讲到踩坑记录把整个项目完整梳理一遍。适合正在用AI编程工具的开发者也适合想在团队里统一管理Agent技能资产的工程负责人。1. 为什么需要统一技能管理中枢1.1 工具爆炸背后的技能碎片化先盘一下现状。当前主流AI编程工具大致分三类第一类是IDE插件比如Cursor、Continue、Cline、GitHub Copilot第二类是命令行工具比如Claude Code、Codex CLI、Aider、Gemini CLI第三类是Workflow型和原生IDE型比如Windsurf、Zed、Trae、PyCharm Assistant、Copilot Workspace。这些工具基本都是Agent架构给它们一个目标它们自己规划、自己调工具、自己改代码。Agent要干活光靠内置能力不够所以各家都支持“技能”来扩展但叫法和格式五花八门。有的叫Skills有的叫Rules有的叫Workflows有的叫Commands存放目录更是完全不同。工具技能载体存放目录示例Claude CodeSkills~/.claude/skills/CursorRules/Agents~/.cursor/rules/Codex CLIAGENTS.md~/.codex/ClineRules/自定义Prompt~/.cline/WindsurfWorkflows/Commands~/.codeium/windsurf/ContinueAgent 自定义命令~/.continue/我实际遇到过给Claude Code写了一个code-review技能把整套SKILL.md做得很漂亮有frontmatter、有脚本、有示例。结果同一天在Cursor里想触发发现Cursor根本不扫这个目录Rules又只支持纯文本和Glob匹配。最后只能在Cursor里重新写一份而两份技能文件一改就容易分叉。这就是碎片化技能散落在不同工具私有目录里格式彼此隔离维护靠人肉同步。工具少的时候还能忍工具上了54个以后根本没法管。1.2 技能不是临时文件而是长期资产很多人觉得“技能”不就是一段提示词嘛写一份放工具里就行了。但你真在项目里用一段时间就会发现两个问题。第一技能会漂移。你今天给Cursor写了一份测试生成技能明天又在Claude Code里改了半版一周后你已经不知道哪个才是最新版。AI输出的质量又直接依赖提示词细节差一两句话生成代码的质量就差一大截。第二技能里装着组织知识。一个调好的“公司内部代码规范审查技能”里面藏着你团队的全部约定命名风格、模块划分、错误处理套路。这是业务资产。资产就该有版本、有作者、有变更记录而不是散落在每个开发者的个人目录里人一离职就跟着丢失。我做Skills Manager的第一动力就是把“技能”从个人文件变成可管理、可追踪、可共享的资产。思路上对标了“标准集装箱”先统一容器规格再用适配器对接不同港口而不是给每个港口做一套专属货形。2. 中枢架构设计统一模型加适配器驱动2.1 为什么桌面中枢比Web和CLI更合理最开始我纠结过形态。Web端方便访问但技能涉及读写本地工具配置目录浏览器沙箱基本做不了就算用本地服务打通还要解决跨域、文件选择器权限、云同步加密的问题成本很高而且很多团队对“技能要上传”这件事非常敏感。CLI端命令确实好用但团队里总有人不喜欢命令行尤其工程效率组里的非技术同学需要可视化界面去浏览、启停、分发技能。桌面中枢是最平衡的形态。它天然本地优先数据全部落在自己机器上不涉及云上传技能包里的脚本不用离开本机企业敏感信息完全可控。其次桌面应用直接读本地文件系统可以操作所有工具的配置目录。最后它能提供GUI浏览技能库、看兼容矩阵、拖拽分发都很直观。2.2 统一技能模型把技能定义成标准数据包既然要做中枢第一步是定一个统一中间格式。我参考社区讨论度很高的Claude Agent Skills思路设计了一套叫统一技能包Unified Skill Package的结构一个技能就是一个标准目录skills/ └── code-review/ ├── SKILL.md ├── metadata.json ├── scripts/ │ ├── review.py │ └── requirements.txt └── examples/ └── sample.pySKILL.md是核心用Markdown编写开头是YAML frontmatter后面是提示词正文--- name: code-review description: 对指定代码文件进行全面审查输出问题清单、风险等级与修改建议 version: 1.2.0 author: devtools-team license: MIT tags: [code-quality, review, team] supported_tools: [claude-code, cursor, codex-cli] --- # 代码审查技能 当用户要求执行代码审查时按以下流程执行 1. 读取目标文件识别语言与框架。 2. 检查命名、结构、错误处理、性能隐患。 3. 输出按严重程度排序的问题清单每个问题给出修改示例。为什么用SKILL.md打底而不是自己发明一套格式因为Claude Code的Skills机制出来后Markdown加frontmatter的结构被社区广泛接受语义清晰绝大多数工具解析起来不费劲。我们的中枢只是在它之上加了一层metadata.json用来管理版本、作者、依赖和兼容信息。meta和提示词正文解耦页面渲染、更新判断、分发决策都读meta。这本质上就是集装箱逻辑SKILL.md是标准箱体metadata.json是箱单。只要箱体规格统一不同目的港54个工具就能用各自的吊机适配器把货卸下来再转换成本地车辆能运的格式。2.3 适配器模式54种格式翻译官统一模型解决了“物”的规格接下来解决“插”的问题。每个工具加载技能的方式都不一样有的扫固定目录有的解析特殊文件名有的要求额外注册。全部写死在主程序里会让模块之间耦合爆炸所以我用了适配器模式。每个工具对应一个适配器都实现同一套接口interface SkillAdapter { readonly toolId: string; readonly toolLabel: string; install(skill: UnifiedSkill, ctx: InstallContext): PromiseInstallResult; uninstall(skill: UnifiedSkill, ctx: InstallContext): Promisevoid; list(skillDir: string): PromiseInstalledSkill[]; validate(skill: UnifiedSkill): PromiseValidateReport; }install负责把统一技能包写入目标工具的技能目录uninstall负责移除list负责回读已安装清单validate负责在安装前做一次预检比如目标工具目录是否存在、格式是否兼容。以Claude Code适配器为例它安装时要做的事很简单在~/.claude/skills/下创建以技能名命名的目录把SKILL.md和scripts拷贝进去。Codex CLI适配器就不一样它需要生成或合并AGENTS.md因为Codex读取的是工作区级的指令文件。Cursor适配器则要把技能转换成Rules格式写到~/.cursor/rules/下并根据技能作用域生成对应的glob匹配前缀。这就是“翻译官”的角色。你没必要让所有工具都原生支持同一个格式适配器把差异全部消化在边界里。用户视角很简单选中一个技能包勾选目标工具点部署。2.4 跨平台技术底座我为什么选Tauri跨平台桌面方案我认真对比过Electron和Tauri。不是Electron不好但选型要契合场景。对比项ElectronTauri安装包体积一般80MB以上10MB左右内存占用高空闲常驻200MB低常见60MB以内后端语言Node.jsRust生态成熟度极成熟较年轻但够用文件系统与进程控制方便但沙箱弱权限模型清晰Rust处理路径、目录操作可靠这个项目要频繁读写各工具配置目录做路径解析、目录遍历、文件哈希比对。这些场景Rust处理起来非常舒服而且Tauri默认配置下每个文件访问都要经过显式IPC安全边界比Electron清晰正好契合“技能包里带着脚本、不能随便执行”的隐私诉求。前端我选了Svelte原因是它打包产物小、运行时轻量桌面应用启动速度更接近原生。整个应用从打开到进入技能库首页基本就是瞬间的事。后来我还用Rust写了一个小的sidecar进程专门负责跑技能里的Python依赖检查避免把环境探测逻辑混进主进程。回顾选型我会给后面想自己做类似工具的同学一个建议如果你的核心操作全是文件、路径、目录优先考虑Rust后端如果你的核心功能偏重聊天式交互、复杂富文本Electron生态会让你少挖很多坑。3. 核心实操技能导入、分发与同步3.1 技能库管理三种导入方式与索引机制进入主界面后左侧是技能库右侧是工具面板。技能库支持三种导入方式。第一本地文件夹导入。选择包含SKILL.md和metadata.json的目录应用会做字段校验、解析meta、抽取描述和标签生成卡片展示。这适合团队内部手工维护的技能目录。第二Git仓库拉取。填一个repo地址指定技能所在路径应用会做浅克隆到本地技能库并定时拉取更新。这是我最推荐的团队方式因为版本历史和review流都跑在Git里。第三市场仓库安装。如果团队从内部制品库发布了技能包用户可以在应用内搜索、一键安装安装时会显示依赖项检查结果。导入后应用会建立索引核心依据是metadata.json里的版本号。每次索引时我会做一次哈希比对计算技能包当前目录的完整哈希跟上次索引比对变了就标记“已修改”提示用户要么另存版本要么重新分发。3.2 分发流程一键部署到目标工具分发是用户最关心的功能。以最典型的场景为例我刚在技能库里编辑完code-review技能现在想把它装到本机的Claude Code和Cursor。操作流程是这样的勾选技能卡片确认版本为1.2.0。在工具面板勾选Claude Code和Cursor。点击部署系统依次执行两个适配器的install。Claude Code适配器计算目标路径~/.claude/skills/code-review/预检目录存在后将SKILL.md和scripts写入。Cursor适配器将提示词转换为Rules格式按技能作用域生成对应glob规则写入~/.cursor/rules/code-review.mdc。系统回读两个工具的list接口确认技能已出现界面显示部署成功。提示这里有个容易踩的坑是软链。软链的意义在于源文件改动后目标工具无需重新部署就能用上。但有些工具在扫描技能目录时会读符号链接的真实路径或者打包时把链接当成普通文件跳过新版本一升级就发现技能丢了。所以我的默认策略是拷贝模式部署时复制一份到目标目录在“开发模式”里才提供软链选项仅供工具测试时使用。卸载是按反向操作做的。先调用适配器的uninstall删除对应目录或文件再回读list确认干净。整个分发动作都有操作日志审计时能看出谁在什么时间把哪个技能装到了哪个工具上。3.3 版本管理与回滚技能更新是高频需求改提示词是常态。我最初做了一版“每次编辑完直接覆盖分发”马上发现问题改错了之后想回到上一版没有备份就找不回来。后面改成了带版本管理的模式。技能库内部保留历史版本目录library/ └── code-review/ ├── 1.1.0/ ├── 1.2.0/ └── current - 1.2.0current是指向版本的软链分发时永远读current。当用户导入新版本或者编辑后另存版本系统会自动把旧版本目录保留下来。回滚操作就是修改current指针再重新分发到目标工具。分发时版本状态我做成三态已部署版本、技能库当前版本、工具端实际版本。界面上如果出现“工具端1.1.0 / 库内1.2.0”就说明工具落后一个版本点击同步更新即可。这个状态机在团队协作里避免了大量混乱。3.4 多技能编排把技能组合成工作流单一技能解决单点问题但真实开发流程往往是组合拳。比如我要对一次提交做完整质量把关至少涉及代码审查、测试用例生成、提交信息规范三个技能。手工逐个触发很麻烦所以我在应用里加了一个编排层。编排配置是一个JSON文件声明技能执行顺序和参数传递{ workflow: pr-quality-check, steps: [ { skill: diff-analyzer, input: $PR_DIFF }, { skill: code-review, input: $STEP1_OUTPUT }, { skill: test-generator, input: $STEP2_CHANGED_FILES } ] }第一层技能的输出作为第二层技能的上下文变量注入。这个设计跟Agent编排框架的思路一致只是我们把编排结果也固化成技能包任何一个工具的Agent都能加载。这部分功能开发量不小但团队里用起来后质量基线一下就统一了。4. 兼容性矩阵与新增工具适配4.1 54工具的兼容性分级策略54个工具听起来很多但一开始就追求全量完美适配是最大的陷阱。我按用户量和适配成本做了三级策略。级别定义工具示例适配器能力A级 完整适配占比最高、用户最常用Claude Code, Cursor, Codex CLI, Cline, Continue, Copilot安装/卸载/回读/校验/转换全支持B级 主要适配有一定用户量、格式较易转换Windsurf, Aider, Zed, Trae, Gemini CLI支持常用技能格式复杂功能降级C级 基础适配长尾或格式特殊其余小众工具支持将技能导出为可手动粘贴的模板分级不是偷懒。适配器需要持续维护工具一升级目录结构可能变字段可能调整不投入测试就会坏。与其每个都半吊子不如把核心工具做到稳定长尾工具提供基础导出能力。每轮发布前我会跑一遍自动化适配器回归测试在隔离的临时目录模拟安装断言目录结构和关键文件存在。4.2 新增一个工具的适配器流程这块我想把完整流程写出来之后大概率会有人要自己接新工具。第一步研究目标工具的技能加载机制。打开工具的配置目录看是扫描固定路径还是读取某个全局文件搜索官方文档或源码仓库里的读取逻辑确认它识别哪些字段。第二步定义格式映射。把统一技能包的SKILL.md、metadata.json映射到目标格式记录字段对应关系尤其注意frontmatter字段名差异、描述字段长度限制、文件命名规则。第三步实现适配器接口。按2.3节的接口实现install、uninstall、list、validate。这一步我习惯先用一个极简测试技能跑通再写完整逻辑。第四步端到端测试。真实创建一个工具实例调用install再在工具里手动触发一次技能确认能正常输出。只验证目录写入成功远远不够工具不加载就是白搭。第五步补进兼容矩阵和回归脚本。在适配器仓库里新增一个子目录补充CI用例标记对应级别。实际接Windsurf的Workflows时我就因为没看字段限制把过长的技能描述直接写入结果工具解析时截断了描述导致Agent无法理解技能用途。后来我在validate里统一加了字段长度检查这类问题才算堵住。4.3 格式转换中丢失细节的排查跨格式转换最容易丢东西。我总结过几个高频损伤点。第一frontmatter字段被丢弃。有些工具只认name和description其它字段在转换时静默忽略。解决方法是适配器里配置字段映射表未知字段做白名单或警告不要直接丢弃。第二相对路径错位。SKILL.md里如果写了“参考scripts/xxx.py”在Claude Code里相对于技能目录解析是没问题的但换到另一个工具这个相对路径可能相对于项目根目录解析指向不存在的地方。处理方式是在适配器转换时把路径重写为绝对路径提示或者在正文里用工具支持的专用变量。第三编码和换行问题。Windows上最容易踩CRLF的坑有些工具对CRLF敏感解析YAML frontmatter时直接报错。统一在写入时转LF并检查UTF-8编码不带BOM。我给应用加了一个“转换预览”界面分发前可以先看适配器将要写出的内容逐字段对比原技能确认没有丢失再确认部署。这个预览功能看起来不起眼但在多工具分发场景下帮了大忙。5. 常见问题排查与务实建议5.1 技能装好了但工具里看不到这是问得最多的问题。按这个顺序排查先确认工具确实扫描了目标目录。有些工具要重启会话或手动刷新技能列表。再确认子目录名和文件名规范。Claude Code要求技能目录名与SKILL.md里的name字段一致Cursor的Rules要带.md或.mdc后缀。接着看权限。macOS上如果目标目录存在SIP保护或Windows上目录只读写入会静默失败。把适配器配置的目录路径在文件管理器里打开确认一次。最后看缓存。很多工具会缓存技能索引装了新技能在列表里不出现时去清一下工具自身的缓存目录。我在应用里加了部署后自检install完成后会调list回读如果目标目录里没有对应文件界面直接提示“安装异常”而不会显示成功。5.2 同一个技能在A工具好用、B工具行为异常这是用户反馈里最迷惑的一类。原因大概率不是格式问题而是变量不同。工具解析提示词的方式不同。有的Agent把整段SKILL.md按系统级指令注入有的只当作参考文本指令约束力差的工具会漏执行关键步骤。上下文长度不同。技能执行时工具塞给模型的上下文长度若不够后半部分技能指令被截断行为自然偏离。这种场景下把技能提示词精简、把关键约束前置到前几行是最快的改法。模型能力差异。同一技能在Claude模型和开源模型上表现差别巨大尤其在指令遵循和复杂工具调用环节。技能够不够稳要看它是否把任务拆成足够小的步骤以及是否在每步给出明确的输出格式。我的建议是写技能时遵循一条原则把最关键的三个约束写在最前面用祈使句避免模糊语气。5.3 团队协作落地建议如果团队要把技能中枢真正跑起来我的建议是三件事。第一技能库进Git。每个人本地都用Git仓库维护技能包metadata.json里的版本号与Git tag绑定。开发、测试、正式三个分支出发分支对应不同稳定性等级正式分支合入前必须跑一遍适配器回归。第二发布走审批。新增或修改技能提交MR至少一人review提示词内容和脚本安全性重点看有没有读取敏感文件、有没有把内部信息外发。批准后由CI自动构建技能包并发布到内部源。第三分发有灰度。先在个人工作工具上跑一周验证稳定后再批量分发到团队。每周看一次各工具的实际触发率和失败率把问题技能下架。5.4 几个我亲手踩过的坑最后分享几个比较有代表性的实操教训希望能帮后来者省点时间。SKILL.md里的frontmatter值如果包含冒号、井号等特殊字符记得加引号。我有一版description里写了“支持GitHub: 生成PR描述”YAML解析直接失败技能在大部分工具里都加载不出来排查了半天才发现是冒号没引起来。后来所有模板生成器里都强制给description加引号处理并加了YAML语法预检才消停。技能脚本不要依赖当前工作目录。我写过一版审查脚本用相对路径读取临时文件在Claude Code执行正常换到Cursor后工作目录不同脚本直接找不到文件。后来一律改成由参数传入绝对路径或由工具输出真实路径后再拼接。Windows路径的反斜杠问题。在SKILL.md正文里写参考文件路径时如果是Windows路径格式Markdown链接和工具解析都会出错。统一用正斜杠适配器在写入各工具格式时再转对应平台风格。还要持续监测工具升级。每次AI编程工具发布新版本我都会先检查它的技能目录规范有没有变化再决定适配器是否要更新。最稳的做法是在工具beta版发布后、正式版推送前先用隔离环境跑一遍回归。我在实际维护这个项目一年后最大的体会是技能的格式问题从来不是最大的问题最大的问题永远是工具升级的兼容性以及团队对技能资产的治理意愿。适配器有厚有薄都没关系只要统一模型稳定、数据能迁移后面所有扩展都建立在正确的地基上。要是你现在手头的AI编程工具越来越多技能越写越散确实值得给自己搭一个这样的中枢哪怕先只管理三个工具后面顺着适配器架构慢慢扩充收益也会越来越明显。
阅读完成 · 觉得有帮助？
