不用猜你现在多半已经在用至少两到三个AI编程工具了Claude Code、Codex CLI、Cursor、Windsurf、Aider、Continue……这些工具各有各的Agent能力各有各的技能格式。最烦的是你在Claude Code里精心调好的一套技能切到Codex里就完全不认。技能明明是一种资产却被绑死在了工具身上。这个项目要解决的正是这个问题把AI编程工具的Agent技能统一收拢起来做成一套跨平台、跨工具的桌面中枢让写一次技能、处处可用成为常态。我做的这套方案叫Skills Manager核心思路是把“技能”从具体AI工具中剥离出来用标准化的目录与描述文件统一承载再通过适配层动态注入到不同工具的Agent运行时里。目前已经适配了54主流AI编程工具与Agent框架覆盖Windows、macOS、Linux三大桌面平台。这套东西不只适合重度AI用户也适合团队里负责沉淀提示词资产、做工具链规范的人。下面我把完整的思路、架构、实操过程和踩坑记录一次讲清楚。1. 技能碎片化为什么需要统一的桌面中枢1.1 现在AI编程生态的真实状态过去一年里AI编程工具的数量增长非常快。每次有新的Agent工具出来大家的第一反应都是去翻它的文档看它支不支持自定义技能、Support目录放在哪、技能文件用什么格式。Claude Code用的是.claude/skills目录加SKILL.mdCodex CLI用的是AGENTS.md加自定义命令Cursor有.cursor/rules与WorkflowWindsurf有rules与commands而像Aider这类纯命令行工具本质上靠--message配合脚本才能实现类似效果。这带来了一个很直接的问题技能资产完全碎片化。团队里如果有人擅长写Claude Code的SKILL.md换到Cursor之后那一整套技能资产就用不上了。更麻烦的是当你同时在用多个工具时要把同一套行业知识、代码规范、操作流程分别维护成好几个版本任何一个更新了其他几个很容易忘掉。等到某一天切工具才发现技能早就不一致了。这个项目的出发点很朴素既然技能本质上是“给模型看的、结构化的操作手册与先验知识”那就把它抽出来跟具体工具解耦。技能只需要维护一份由中枢负责分发。1.2 现有技能体系的三种形态盘点了一圈主流工具之后我发现市面上的技能体系大体分成三种形态这是做统一管理时必须先搞清楚的基本盘。第一种是文件型技能以Claude Code的SKILL.md为代表。一个技能就是一个目录里面有描述文件描述文件里写清楚技能名称、触发条件、说明正文是详细的操作步骤。这种形态最接近“资产化”便于复用但各家定义字段不统一。第二种是规则型技能。Cursor的.cursor/rules、Continue的.rules本质上是给模型提供上下文规则。这类技能通常是若干条文本规则紧凑但缺乏文件结构只能告诉模型“你要注意什么”没法把整个技能的操作流程组织成可引用、可检索的完整资产。第三种是命令型技能比如Windsurf的commands、Codex的配置命令。这类技能把一段指令封装成一个命令优点是调用方便缺点是命令之间没有结构化组织规模稍大之后就很难管理。三种形态其实各有各的使用场景但这也意味着如果一个统一管理中枢要兼容它们就不能只做一种格式。Skills Manager的做法是定一个“中性格式”作为技能母版然后按目标工具的动态能力分别做转换与注入等效替代三种形态。1.3 统一管理的价值点统一技能管理之后最直接的收益是维护成本下降。以前每加一个新工具我都要把最常用的十几个技能重写一遍现在写完母版之后中枢自动生成各工具需要的产物。技能内容更新时所有工具的引用源是同一份不需要到处去改。第二个收益是技能可以跨平台携带。团队里有人用macOS有人用Windows有人用Linux中央技能仓库如果放在公司内网共享盘上三端都可以同步读取而不需要关心某个工具的技能目录写法在哪套操作系统上不同。Windows路径和macOS路径的差别、换行符的差别、权限模型的差别都由中枢的跨平台层转译掉。第三个收益是便于做技能沉淀与评审。当技能以统一格式存在时可以给每个技能附加版本号、作者、使用场景、依赖项这样团队做Code Review或技能评审时就有了清晰对象。更重要的是这种模式不绑定任何一家厂商工具可以随时换技能资产永远跟随自己。这也是我把这个项目定位成“桌面中枢”而不是某一个工具的插件的原因。2. 架构设计与核心思路2.1 整体分层存储、适配、分发、控制Skills Manager的总体设计可以分为四层每一层只做一件事。最底层是技能存储层负责以中性格式保存所有技能往上是适配层负责把中性格式转成目标工具能够识别的内容再往上是用分发层把技能投递到各个工具的技能目录里最顶层是控制层也就是桌面端界面和命令行工具负责管理整个生命周期。存储层用了一个skills/根目录下面每个技能一个子目录子目录名就是技能ID比如code-review、commit-message、docker-debug。每个技能目录里有标准化的SKILL.md和可选资源文件。这套结构既是人可读的也是机器可解析的。适配层是工作量最大的部分。每个AI工具对应一个适配器适配器定义了该工具的技能目录位置、支持的格式、清单文件写法。适配器做的事情其实不复杂读取中性的技能描述与正文经过一定的字段映射和格式归一化写到目标工具指定位置。但恰恰是这层把“一套技能到处能用”从口号变成了现实。分发层负责同步。它不搞复杂的云端服务就是通过一套增量复制机制把技能产物推到各工具的技能目录。局域网里可以用同步盘目录也可以用Git远程仓库。分发层会记录每个工具已接收的技能版本避免每次都全量复制。控制层是用户直接面对的。桌面管理器提供技能列表、预览编辑、一键安装到目标工具、版本对比这些功能。同时提供CLI方便在终端里快速操作比如skills status查看所有技能的安装情况skills install codex把当前技能集安装到Codex。2.2 为什么选择“本地优先桌面中枢”而不是云端服务做架构选型时我其实认真考虑过要不要做成SaaS服务。但最终选了“本地优先桌面中枢”的路线原因有三条。第一条是技能数据敏感。技能里往往包含公司的代码规范、内部系统的操作流程、私有API的使用说明这些东西送进第三方云端服务安全上很难交代。本地优先意味着技能资产默认只存在于自己的机器和团队可控的存储里不上传任何外部服务。第二条是离线可用。写代码场景经常出现在内网环境、虚拟机里、甚至出差飞机上。如果中枢依赖公网服务一旦断网就什么都做不了。桌面中枢以本地目录为准配合Git远程仓库或内网共享盘在没有公网的情况下依然完整可用。第三条是零运维成本。一个云端服务要做账号体系、鉴权、数据库、配额管理这些都会成为额外负担。桌面中枢把这些全部省掉了配置一次长期使用。分发层用文件级同步不依赖任何基础设施最多需要挂一个远程仓库地址。这些原因综合下来“本地优先”几乎是唯一的正确答案。说白了这个工具不是做一个多租户平台而是做一个个人和团队都够用的技能底座。架构上的克制反而让它在真实使用中更稳定。2.3 54工具是怎么做到“一套技能接口”的很多人会问54工具的适配怎么可能做得完每个工具的技能机制都不一样。这里的关键是不需要为每个工具做完整深度的双向同步只需要抓准每一类工具的共同特征做“部分兼容 行为降级”。我先把工具按Agent运行时形态归成大类。第一类是文件目录型工具会读取某个固定目录下的技能文件这类覆盖率最大统一按SKILL.md写入即可。第二类是规则注入型工具通过规则文件获得上下文这类需要把技能的描述与触发条件转成规则文本。第三类是对话指令型没有明确的技能目录只能通过系统指令或会话前缀注入这类就退化为把技能内容整理成可直接粘贴的指令块。每一类适配器都遵循同一个接口契约read_source()读取技能母版transform()做格式转换write_target()写入目标位置。真正需要每家深度定制的部分很少绝大多数工具都能归属到这三大类里。即使某款新工具出来只要判断它属于哪一类适配器代码几乎可以现成复用。目前适配的54工具名单里覆盖了市面上主流的AI编码IDE、终端Agent、开源框架和企业内部分发系统已经足够日常使用。3. 核心实操从零搭一套技能仓库3.1 SKILL.md标准格式怎么定母版的格式是整套体系的基石不能随便定必须兼顾解析器的简单性和人类的可读性。我最终采用的是YAML Frontmatter加Markdown正文的结构这也是很多主流工具已经接受的结构范式学习成本低。每个SKILL.md的开头是一段YAML元信息里面我固定维护这些字段--- name: code-review description: 基于团队规范进行代码审查发现逻辑缺陷、安全隐患与可维护性问题 version: 1.2.0 author: team-core tags: - review - quality - security triggers: - 请审查代码 - code review - review this PR dependencies: - git ---name对应技能目录名必须保持唯一且用短横线命名description是给Agent判断“什么时候该调用这个技能”用的写得越具体越好要包含动作对象和场景version用于版本追踪适配层会在目标目录里记录这个版本号triggers是可选字段某些支持技能自动触发的工具可以直接用。dependencies标明技能运行依赖的外部命令分发时会做环境检查。正文部分我坚持用“原则在前步骤在后示例收尾”的写法。先写这个技能的适用边界和基本原则让模型理解背后的逻辑再写标准操作步骤尽量用检查清单式列表最后给一两个完整示例作为few-shot参考。这样写出来的技能在不同工具里被调用时的表现差异是最小的。3.2 一个技能目录的完整结构技能目录不只是放一个SKILL.md就行。我经过实际使用后建议一个正式技能至少包含三类内容描述文件、参考文档、模板与脚本。拿一个“docker-debug”技能举例完整的目录长这样skills/ └── docker-debug/ ├── SKILL.md ├── references/ │ ├── container-log-analysis.md │ └── common-exit-codes.md ├── templates/ │ ├── docker-inspect-report.md │ └── healthcheck-debug.md └── scripts/ ├── collect_container_metrics.sh └── parse_logs.pyreferences里存放辅助文档正文通过相对路径链接引用它们。templates提供输出模板当技能要求模型产出结构化报告时这份模板能显著提升输出一致性。scripts放的是真正可执行的辅助脚本模型在步骤中调用这些脚本收集数据比让它自己凭空编命令可靠得多。这套结构不是凭空想出来的它是模仿人类工程师工作台的设计技能不只是“一段提示词”而是一个微型工作包里面装好了干活需要的资料和工具。写进SKILL.md正文的步骤只负责串起这些资源。这样的技能才是真正可复用的而不是换个工具就失效的“咒语”。3.3 注册与分发让每个Agent读到技能写完技能母版后第一件事是注册。注册的意思是在skills.json清单文件里登记技能的基本信息和目标安装范围中枢只管理登记过的技能。注册之后就是分发。我在实际项目里最常用的是命令行动作一条命令就能把技能集推送到指定工具。比如要把所有技能推送到Claude Code和Codex可以这样做skills install claude-code skills install codex每条install命令在内部做三件事读取清单、转换格式、增量写入目标工具技能目录。Claude Code会被写入到.claude/skills/{skill-name}/SKILL.mdCodex则根据适配器配置把技能转成对应命令集。命令结束后终端会打印每个技能的写入状态和版本号一目了然。如果你用的是IDE类工具桌面管理器里也提供了可视化操作。技能列表左侧展示所有已注册技能右侧展示选中技能在哪些工具上已安装、哪些还没装。单击安装按钮适配器立即执行转换写入。整个过程不需要重启工具因为多数工具会在新会话启动时扫描目录下次新建会话就能读到。3.4 桌面管理器的日常使用桌面管理器不是个摆设它的价值在于把那些在命令行里容易看不清的东西可视化。我日常最常用的是三个界面。第一个是技能总览页。所有技能按名称、版本、状态、适配范围排列。这里最重要的信息是“技能漂移”某技能在Claude Code上是1.2.0在其他工具上还是1.0.0总览页会把这版差异高亮出来提醒我执行一次统一更新。第二个是技能编辑页。左侧是技能目录树右侧是SKILL.md在线编辑器。编辑器内置了Frontmatter校验字段不合法时直接标红。写完保存后管理器会询问是否需要推送到各工具一步到位。这是最省心的流程改完即生效。第三个是环境检查页。Skills Manager会把当前操作系统的Shell环境、各工具CLI路径、版本号、技能目录权限全部检查一遍。遇到某个工具版本过旧、目录不存在或不可写这里都会直接给出处理建议。对于团队里不熟悉命令行的成员来说这个页面能节省大量排查时间。4. 常见问题与排查技巧实录4.1 技能加载不上先查这三处使用过程中最常遇到的问题就是技能在工具里不生效。按照我排障的经验绝大多数情况下问题出在三个地方目录位置不对文件名不对描述文件字段不完整。先说目录位置。不同工具读取技能目录的机制不一样有的读项目级目录有的读用户级目录有的两级都读但优先级不同。适配器虽然会自动写入但如果你手动拷贝技能很可能放错了层级。比如Claude Code在项目级和用户级都支持skills目录项目级优先如果你希望技能全局可用应该放在用户级目录放在项目级的话只有进到那个项目才能触发。再说文件名。很多工具对技能描述文件的文件名有硬性要求大小写都不能错。你写了个skill.md工具就是认不出必须是SKILL.md。Windows上由于文件系统默认不区分大小写这种问题在Windows上未必暴露但一换到macOS或Linux就立刻失效。所以技能文件名一定要严格按规范来。最后是描述文件字段。有些工具不识别triggers字段有些工具要求description必须出现在正文前等等。如果你发现某个工具里技能没有被自动触发先检查适配器输出的转换结果看看字段映射是否正常。排障时建议直接打开工具生成的技能清单逐行对照母版通常一眼就能发现哪个环节丢字段了。4.2 跨平台路径与权限的坑跨平台是个说起来简单、做起来全是坑的事情。第一坑是路径分隔符。如果你在技能正文里写了硬编码路径比如/home/user/project或C:\work\project那这套技能在别的平台上基本就没法用了。解决方案是正文里一律使用语义化占位符例如{{PROJECT_ROOT}}、{{HOME_DIR}}分发前由适配器替换成当前平台的真实路径。第二坑是换行符。Windows上文件默认CRLFLinux和macOS默认LF。有些AI工具的解析器对结尾的\r很敏感会导致Frontmatter解析异常。技巧是在适配器层增加“换行符规范化”统一把技能内容输出为LF避免跨平台复制技能时出现莫名其妙的解析错误。第三坑是权限问题。写入其他应用配置文件目录时可能遇到权限拒绝。比如在macOS上写入~/.claude/skills一般没问题但有些工具的目录在系统保护区域或者团队统一安装时目录所有者不是当前用户。遇到这种情况不要把目录权限直接放宽到777更合理的做法是配置一个可写的技能存储路径让工具指向那个路径。4.3 同名技能冲突与版本管理当技能数量多起来后同名冲突几乎不可避免。不同作者或不同项目可能各自定义了一个code-review技能分发到同一个工具目录时互相覆盖这是最让人头疼的问题之一。我的对策是在技能ID上做命名空间。内部技能统一用team-slash-{skill-name}这种前缀划分归属例如team-code-review和personal-code-review可以并存。当然如果你某个工具本身就只支持单一技能目录那这种情况下还是要做取舍技能管理器的策略是“后安装的优先级高”但同时会在变更前把旧版本备份到backups/目录。版本管理也是日常必需。我要求每个技能在迭代时更新version字段同时建议在技能正文末尾保留两三条CHANGELOG说明这个版本改了什么。同步时适配器比对版本号只有高于目标版本才覆盖。这套机制让回滚变得非常方便发现新版本技能反而导致Agent行为异常直接安装回旧版本即可。4.4 适配器行为差异怎么处理同一个技能在不同工具里表现不同这是多Agent工作流里必然遇到的现象。原因在于各家底层模型和调度逻辑不同同样一段说明Claude Code可能严格执行每一步Codex可能更倾向于理解意图后自由发挥。处理这个问题我通常在技能正文里做两处设计。第一处是在技能开头增加“执行模式”声明比如明确规定“该技能要求逐项执行步骤禁止跳过任何检查项”。这种声明对遵循度高的模型管用至少能减少自由发挥的空间。第二处是提供同一技能的多版本描述适配器可以根据目标工具的特性选择更长或更短的描述注入。如果某个工具的表现始终无法对齐我会单独为那个工具建一个覆盖规则在它的适配器配置里指定一个替代技能目录。这套覆盖机制虽然工作量多了一点但换来的是每个工具都尽量按照最适合它的方式去执行同一套技能资产而不是削足适履。5. 多工具同步与团队协作的进阶用法5.1 用Git远程仓库当分发通道因为整个技能仓库本身就是普通文件目录所以用Git做分发通道是最自然的事。团队内部建一个skills-central仓库技能管理器支持直接关联仓库地址每次执行skills push或skills pull时自动完成提交、推送或拉取合并。这套流程有几个需要注意的点。一是仓库里不要提交工具生成的临时产物只提交中性格式的技能母版适配产物每台机器本地生成。这样仓库始终干净也避免平台差异文件污染。二是建议给技能目录配置.gitignore把backups/和临时缓存目录忽略掉防止仓库体积膨胀。三是提交信息要规范我习惯在提交信息里附带技能版本号比如docs: update code-review to 1.3.0这样用git log就能直接看到技能的演进历史。拉取远端更新后只需要执行一条全量同步命令所有本地工具的技能就全部对齐了。这比团队里谁更新了技能后到处喊一声要靠谱得多。5.2 面向团队协作的角色权限建议如果会有一组人同时用这个中枢直接放开写权限会乱。实际操作中我见到的比较稳定的协作模式是仓库管理员负责技能审核与合并所有成员的写入先走PR或集中提交适配器和目录结构只由管理员调整。当然小团队里不用搞得像开源社区那么正式。就算只有两三个人我也建议至少固定一条规矩修改已有技能之前先看它的author和version确认自己理解现有内容再动笔。这条规矩在至少三次场景里避免了我们把组长精心调整过的技能覆盖成新手的简化版。如果团队分散在不同地区还建议在技能描述里显式标明适用于哪个项目、哪个业务域。否则一个通用的“数据库性能排查”技能在你这边假设的是PostgreSQL在别人那边可能用的是Oracle直接用就会产生误导。技能也分上下文不是所有技能都适合所有人。经过这一路搭建和迭代我现在已经习惯把所有Agent技能当作一种长期资产来维护。Skills Manager真正解决的不只是格式转换问题它让我在切换工具、升级工具、换电脑时不再有“知识也跟着丢”的恐慌。如果你也在同时用好几个AI编程工具我的建议是先不要贪多挑三五个真正常用的技能用中性格式沉淀下来让中枢管起来。你会发现技能本身的价值比任何单一工具都更持久。