说起AI编程工具的技能管理我得先交代一下自己过去的混乱状态。Cursor、VS Code Copilot、Codex CLI、Claude Code、Aider、Continue……我电脑上装了一堆Agent相关的编程工具每个工具都有自己的“技能”机制有的叫Rules有的叫Agent Skills有的叫Commands还有的叫AGENTS.md。单个工具用起来都挺好但问题是当你想把一套统一的项目规范、代码审查标准、Git提交信息生成规则喂给所有这些工具时你会发现每家的格式和加载方式完全不一样。Skills Manager这个项目就是冲这个痛点去的。它的定位很明确一个统一管理54 AI编程工具Agent技能的跨平台桌面中枢。简单说你用一套格式写技能它在后台帮你翻译、分发、同步到不同的AI编程工具里。这篇文章我会从架构设计、技能格式、跨平台实现、工具适配层到实际踩坑完整拆一遍这套方案给正在被多工具技能管理折腾的同学一个可参考的落地思路。1. 为什么AI编程工具的技能需要“中央集权”1.1 从提示词碎片到Agent Skill的关键一步先说说“技能”这个概念在AI编程工具里是怎么演变的。最早的时候大家用AI写代码就是直接把一段提示词复制粘贴到对话框里比如“请按下列规范审查我粘贴的代码”。后来发现这些提示词片段反复用就有人把它们存成Markdown文件再后来出现了Rules、Commands这类有固定加载路径的文件机制。到了Agent时代像Claude的Agent Skills、Codex的AGENTS.md这类东西已经不是简单的提示词了而是一个包含说明文件、脚本、参考文档的目录结构Agent会读取它并在特定场景下自动调用。这一步之所以重要是因为AI编程工具正在从“单轮对话”走向“自主执行任务”。技能本质上是把人的经验翻译成Agent能理解和执行的操作手册。比如我写了一个“SQL慢查询分析”技能里面包含了分析步骤、要执行的EXPLAIN语句模板、结果判断逻辑那么Agent在碰到SQL优化任务时不再需要我从零开始喂指令它自己加载技能就能干活。1.2 多工具混用场景下的真实痛点但问题也随之而来。我实际工作里的情况是主编辑器用Cursor或VS Code跑自动化任务用Codex CLI或Aider做多Agent编排又用LangChain或者其他框架。每个工具的技能机制都不一样Cursor支持.cursor/rules里面放的是带alwaysApply或globs标记的规则文件Claude Code支持SKILL.md带frontmatter声明和脚本目录Codex CLI读AGENTS.md作为项目说明书Cline、Continue这类VS Code插件各自又有.clinerules、.continuercache之类的约定。如果我有10个技能要维护就得在5种格式之间来回复制、手工同步。更麻烦的是不同工具加载技能的搜索路径和优先级不一样同一个技能在一个工具里生效在另一个工具里就找不到。我之前试过手工维护两三个工具的规则文件每个文件更新时都要记得改好几处漏改一个就会导致行为不一致。机器上存的规则文件版本比代码仓库还难管理。所以我的结论很直接技能维护必须有一个统一入口。Skills Manager要做的就是这个“中央集权”把分散在各工具、各项目里的技能文件收拢到一个中央仓库里再通过适配层分发到每个目标工具。2. Skills Manager的整体架构一个桌面技能中枢的自我修养2.1 三层结构技能仓库、同步引擎、协议适配层Skills Manager整体分成三层。最底层是技能仓库负责存储所有技能的源文件统一采用SMF格式后面详细讲。中间层是同步引擎负责把仓库里的技能分发到不同目标工具各自的目录里去并且处理文件格式转换、版本比对、增量同步。最上层是协议适配层就是那个连接目标工具的桥。可以把这个结构理解成一个“软件包管理器”的模型。技能仓库相当于软件源同步引擎相当于apt install协议适配层则负责把统一的调用请求转成每个工具能理解的格式。我实际实现的时候这三层是完全解耦的仓库只存标准格式不关心下游是谁同步引擎只管分发不关心技能内容适配层只做协议转换。这种设计的直接好处是新增一个工具支持时不需要改动前两层。你只需要在适配层里加一个新的适配器定义好目标工具的技能目录、文件格式和加载方式同步引擎就能把技能推过去。2.2 为什么选择桌面中枢而不是纯CLI或云端最开始我认真考虑过纯CLI方案把技能仓库做成一个命令行工具用户手动执行sm sync来同步。但实际用下来发现纯CLI有两个明显问题。第一是Agent工具本身的调用链太长。你在Codex CLI里干活肯定是希望技能已经就位而不是先退出终端去执行同步命令再回来。桌面应用可以常驻后台监听文件变化做到“改完技能立刻分发”CLI很难做到实时。第二是可视化管理和调试的需求。技能文件刚做出来经常有格式问题、描述写得不够好、依赖路径写错。在终端里报错信息跳来跳去很痛苦桌面上直接展示解析错误、同步状态和每个技能的启用开关排查效率高得多。那为什么不做成云端服务因为技能文件非常多属于代码库和项目上下文有些甚至是公司内部规范提到云端去处理就有敏感信息暴露的疑虑。而且技能需要在本地文件系统里和Agent工具交互云端方案在网络请求这一层就会引入延迟和不可控因素。桌面端最合适数据在本地能力在线下实时响应。2.3 技术选型与核心模块技术栈上我选了Tauri加Rust加Svelte。选择Tauri而不是Electron的原因很直接内存占用小、安装包体积小、启动快。作为一个需要常驻后台的工具Tauri的进程开销大概只有Electron的三分之一到四分之一这点对开发机来说很重要毕竟开发机器本身就够吃紧了。核心模块分这几块sm-core技能解析、格式转换、版本比较逻辑用纯Rust实现不依赖桌面框架sm-sync同步引擎基于Git仓库做底层的技能分发同时监控本地文件变化sm-bridge适配层负责和具体工具通信sm-appSvelte写的前端界面负责显示技能列表、编辑、启停、同步状态。模块划分的原则是能放进核心的就不要放进界面层所有逻辑尽量跟UI解耦。因为在实际使用中很多时候是sm-bridge在后台被Agent工具调用并不会经过桌面界面。如果逻辑写死在UI里后台调用路径就没法复用。3. 统一技能格式SMF的核心设计思路3.1 一段标准的技能声明长什么样统一格式是整个项目的灵魂。我参考了Claude Agent Skills的标准并结合多工具兼容的实际需要设计了一套叫SMF的技能格式。每个技能是一个目录目录下至少包含一个SKILL.md文件里面用YAML frontmatter声明元信息。以下是一个真实的技能声明示例--- name: review-sql-performance description: 分析SQL执行计划并识别慢查询、索引失效问题。适用于数据库性能排查、SQL优化。 version: 1.2.0 tags: [sql, database, performance] runtime: python3 dependencies: - sqlparse0.4 permissions: - file: read pattern: **/*.sql - network: false --- # SQL性能审查技能 使用本技能时请先读取目标SQL文件执行EXPLAIN ANALYZE并按以下步骤分析...这套格式有几个关键设计description字段必须足够具体是因为Agent在决定要不要调用技能时主要就是靠这个描述做语义匹配写得太模糊或者太宽泛Agent就会在错误的场景下调用。permissions字段用来声明技能的行为边界后面我会讲到安全这一块。3.2 技能目录中的辅助文件一个完整技能不只一个SKILL.md。技能目录里还有scripts/目录放可执行脚本references/目录放参考文档examples/目录放示例代码。同步到不同工具时这些目录结构也要跟着转换。我的建议是脚本尽量不依赖外部安装能用Python标准库就用标准库能用SQLite自带函数就用自带函数。因为很多Agent运行在沙盒环境里未必有权限装第三方依赖。一旦技能脚本要求安装某个包而环境不允许这个技能就废了。3.3 不同工具的技能如何被“翻译”成统一格式这是Skills Manager里最核心的工程量所在。同步引擎内部维护了一组适配规则每个目标工具对应一个“翻译器”。例如当技能要同步到Cursor时同步引擎会读取SMF技能目录提取SKILL.md的正文部分转换成Cursor的rules文件格式并把脚本放在.cursor/commands/目录下。同步到Claude Code时则是直接把技能目录原样拷到~/.claude/skills/目录因为Claude本身就支持带脚本的SKILL.md格式。同步到Codex CLI时则会把SKILL.md的重点内容折叠进AGENTS.md里因为Codex的机制更偏项目说明书。翻译过程不是简单的文本替换。引擎会解析目标工具的加载规则例如有些工具要求文件名以.md结尾、有些要求使用---分隔、有些要求忽略frontmatter。这些细节全是逐坑踩出来的目前项目里已经沉淀了54个工具的适配规则。3.4 版本、依赖与冲突处理技能也有版本依赖问题。比如某个Agent框架昨天更新后不再支持旧格式的技能你同步过去的技能就全部失效了。SMF里用version字段配合同步引擎的版本比较机制可以做到“目标工具能识别什么格式就分发什么版本”。当出现多个技能同名或同描述时冲突处理遵循三个原则显式声明的项目级技能优先于全局技能版本号高的优先于版本号低的同版本情况下最后同步的覆盖最早同步的。我不会做太复杂的自动合并——技能文件是文本和脚本自动合并很容易产生两边都不想要的语义错误不如让用户在界面上手动选定。4. 跨平台桌面端是怎么落地的4.1 存储布局按平台规范来跨平台桌面应用第一个要解决的就是技能文件放在哪里才算“符合规范”。Windows上有%APPDATA%和%USERPROFILE%的分工macOS上传统应用偏好~/Library/Application SupportLinux则通常用~/.config。技能仓库统一放在这些目录下的skills-manager/子目录里即# Windows %APPDATA%\skills-manager\ # macOS ~/Library/Application Support/skills-manager/ # Linux ~/.config/skills-manager/这样设计的好处是各平台的原生文件同步工具比如文件历史版本、Time Machine备份默认会覆盖到这些目录不用额外配置备份策略。而目标工具的技能目录则五花八门。编辑器插件类的多半在项目目录里CLI Agent类的多半在用户主目录下。同步引擎在写目标目录时会先检测目录存在性不存在就创建同时记住原始文件路径防止覆盖用户已有的手工配置文件。4.2 本地存储与Git同步机制存储层我用SQLite存技能索引和同步元数据技能本体则直接以文件形式留在磁盘上。SQLite里记录的是每个技能文件的哈希值、修改时间、同步目标状态、启停状态。只有知道哪个文件需要同步、哪里需要转换才能做到增量分发。同步机制采用Git作为底层传输通道。每个技能仓库都可以关联一个远程Git地址这样可以实现团队级的技能共享。同步过程分成两段本地文件变更检测然后提交到本地Git仓库最后推送到远程另一段是从远程拉取更新应用落盘再分发到各个目标工具。这里有一个很重要的小细节目标工具的技能目录不能直接做成Git仓库否则某个工具在执行代码时把生成的文件写进技能目录Git状态就会变脏触发误报冲突。所以我是把技能仓库和分发目录分开的——仓库是干净的源分发目录是源头加工具格式转换后的产物。4.3 托盘常驻与系统资源占用作为“桌面中枢”常驻后台是必须的。应用启动后缩到系统托盘监听两个变化技能仓库里文件的变动、已打开项目的目录结构变动。底层实现用的是文件系统事件通知比如Windows的ReadDirectoryChangesW和macOS的FSEvents不需要轮询。常驻进程的资源占用要控制得很克制。我做了一个原则没有变化时进程处于阻塞等待状态CPU占用为零只有文件事件触发时才做同步动作。实测下来常驻状态下内存占用约60到80MB对现在的开发机来说基本可以忽略。如果你发现某个版本应用开始“偷跑”CPU多半是文件监听的范围没收敛好误监听了整个用户目录这里值得检查一下。4.4 Windows、macOS、Linux的适配差异平台差异比想象中多说几个典型的。Windows上最大的坑是符号链接。同步引擎默认给技能文件创建“链接”而不是“复制”这样源文件更新后目标目录自动可见。但Windows上创建符号链接需要管理员权限或者开启开发者模式不是默认可用。所以我改成在Windows上默认用复制加校验的方式只有用户手动开启“链接模式”才使用新版本NTFS的符号链接能力。macOS上要注意App Sandbox和文件安全区的限制。如果应用从App Store分发技能仓库目录会被限定在沙盒范围内但开发机上我们通常用非沙盒方式打包或者直接以命令行工具形态配合桌面端使用这样才能自由读写~/.claude/skills这类第三方目录。Linux上主要是各发行版的目录规范不统一有的用~/.config有的坚持XDG标准。目前的做法是优先读XDG_CONFIG_HOME环境变量没有才回退到~/.config。5. 对接54工具的适配层设计5.1 三类接入模式对接了50多个工具之后我发现所有AI编程工具的技能加载机制本质上只有三类。第一类是编辑器插件型典型代表是Cursor、VS Code Copilot、JetBrains AI Assistant。这类工具通常在项目目录下约定一个目录或文件放规则比如.cursor/rules、.github/copilot-instructions.md。适配层只需要做“文件格式”层面的转换。第二类是CLI代理型典型代表是Codex CLI、Claude Code、Aider、Gemini CLI。它们自己管理全局或项目的技能目录有的直接支持SKILL.md有的支持AGENTS.md有的还支持自定义的Commands命令。这类工具适配层除了文件格式转换还可能要做环境变量注入。第三类是Agent编排框架型比如LangChain、CrewAI、Dify、Coze、AutoGen。这类不是直接跑在终端里的而是通过API或配置文件加载工具和技能。适配层需要生成对应框架的tool定义文件或者prompt模板。三类模式的参数对比如下工具类型代表工具技能载体同步方式适配重点编辑器插件Cursor、Copilot、JetBrains项目内规则目录项目级写入目录结构和文件格式CLI代理Codex CLI、Claude Code、Aider全局或项目技能目录全局目录写入文件格式、环境变量编排框架LangChain、CrewAI、Difytool定义 / prompt模板配置文件注入生成对应框架配置5.2 统一调用接口与上下文注入适配层的统一调用接口设计得很简单只有一个入口sm run skill名 --tool 目标工具 --args 参数JSON执行时适配层把SMF技能里的脚本包装成目标工具能调用的形式。例如对CLI代理型工具它会把技能脚本放到正确目录并保证可执行权限对编排框架它会生成对应的函数定义和prompt片段。上下文注入是关键一环。目前的做法是每次同步时生成一个CONTEXT.md里面写明当前环境的信息项目语言、框架版本、已启用的技能列表。这个文件会放在技能目录里Agent工具加载技能时能顺带读到环境上下文减少“拿到技能却不知道在什么项目里用”的尴尬。5.3 新增一个工具适配器的标准步骤新工具接入流程已经标准化了大约30分钟内能完成一个基础适配器。步骤大致是在适配器目录下新建一个实现文件指定工具的技能根目录、文件格式模板、脚本包装方式跑一下针对该工具的同步测试确认技能能正常加载把适配器注册到工具的检测列表里这样应用发现目标工具已安装时会自动提示是否接入。实际接的时候最花时间的不是写适配器而是确认目标工具对“魔法注释”“frontmatter”这类细节的处理方式。有些工具会用严格YAML解析器一个缩进错误就直接跳过整个技能有些工具则宽容到只取描述字段。适配器里必须要针对这种差异做处理没有统一的容错方案。6. 实操从零搭建自己的技能中枢6.1 安装与环境准备开始之前先说明接下来这一节是完整可执行的流程我把日常使用的步骤直接写给你照着做就能跑通一套基础的技能管理环境。下载安装包这一步很常规各平台都有对应的安装包Windows是Setup.exemacOS是.dmgLinux是.AppImage或.deb。安装完首次启动应用会引导你完成三件事选择一个技能仓库根目录、初始化基础技能集、检查本机已安装的AI编程工具。我建议技能仓库目录放在一个单独的磁盘位置不要放在系统目录或项目仓库里。因为技能库里有些内容是通用的有些是项目相关的和项目代码混在一起会让Git提交历史很难看。我自己的布局是~/skill-hub/ ├── common/ # 通用技能 │ └── review-sql-performance/ ├── team-frontend/ # 前端团队规范技能 └── personal/ # 个人偏好技能6.2 创建第一个技能创建技能有两种方式命令行输入或者界面操作。我习惯用命令行因为可以顺便把技能目录用Git管起来。sm skill create code-review-frontend sm skill edit code-review-frontend第一个命令会在仓库里生成技能目录骨架第二个命令打开编辑器编辑SKILL.md。编辑的时候有两个地方值得花时间一是description要写成“当遇到什么情况时使用”的句式。例如“当用户要求审查React组件代码时使用此技能”效果远比泛泛的“代码审查技能”好因为Agent就是靠这段描述判断调用时机。二是技能正文要写步骤序列而不是只写结论。Agent不像人它能记住的上下文有限你越明确地给出“第一步读什么、第二步执行什么、第三步根据什么判断”它执行得就越稳定。6.3 在目标工具中启用技能技能创建好之后在应用界面上你会看到本机检测到的工具列表。以Claude Code为例点击启用后同步引擎会把技能目录写到~/.claude/skills/review-frontend/。为了确认是否真正生效我建议用工具自带的调试方式跑一次。Claude Code里可以直接要求“用review-frontend技能审查某个文件”看它是否自动加载了技能描述和执行脚本Codex CLI里可以查看AGENTS.md里是否出现了技能摘要Cursor里可以打开规则面板确认.cursor/rules文件已经被识别。最稳妥的验证方式故意把技能的description改成一个明显错误的短语同步后看目标工具是否读到了错误描述。能读到说明同步链路通的读不到说明路径或格式还有问题。6.4 通过Git与团队同步技能集团队协作是技能管理价值释放的关键场景。一个前端团队可以把“代码规范”“提交信息模板”“组件设计模式”做成标准技能集统一分发到每个成员的每个AI编程工具里。操作上就是在应用里关联远程仓库sm remote add origin gitgithub.com:your-team/skills.git sm sync --push其他成员在各自机器上执行sm sync --pull技能集自动落位。这里我的经验是团队统一技能集要走分支管理先在一个分支里验证新技能稳定了再合并到主分支直接推送主分支很容易让一整个团队的Agent工具行为突然变化排障成本很高。7. 实战中踩过的坑和建议7.1 技能目录权限与链接问题同步后技能不生效最高频的问题是权限和链接。Linux和macOS下脚本没有可执行权限是最常见的原因。同步引擎在落盘后默认会执行chmod x但有些工具要求技能目录本身也有可读权限否则Agent进程用了不同的系统账号启动就会因为目录权限不足而加载失败。Windows上则是两种场景启用了开发者模式时符号链接可以正常创建没开启时引擎回退到复制模式。如果你发现某个技能更新后目标工具里还是旧内容先确认一下是不是处在“链接模式”下——链接模式下源文件的缓存没刷新会导致看起来像是没更新实际是目标工具缓存了旧文件。7.2 命名空间冲突多个技能同名是另一类高频问题。比如团队技能集里有个commit-helper个人技能库里也有一个两个都会同步到Claude Code的skills目录下时冲突就来了。目前应用的处理原则是“最后同步的生效”但更好的实践是用命名空间前缀区分团队级技能统一叫team-*个人级技能统一叫me-*这样不仅减少覆盖风险Agent在理解描述时也更清楚技能归属。在技能管理的早期就要约定好命名规范因为技能目录在Agent环境里一旦被大量加载重命名涉及所有已配置工具的重新同步成本不小。7.3 沙盒环境下的技能不可用Agent工具大部分都有沙盒机制。Claude的代码执行环境、Codex的容器环境、Cline的模拟终端都会限制技能脚本的网络访问、文件写入范围。我的建议是技能脚本要尽可能做“纯计算”的事情把需要网络的操作比如调用外部API、拉取远程数据交给Agent主进程而不是放在技能脚本里自己执行。换句话说技能脚本的定位是“提供分析和判断的逻辑”而不是“替Agent去做它不能做的事”。复杂技能可以在SKILL.md里明确写明“步骤3调用请求工具获取数据”让Agent用自身能力去执行。7.4 技能安全边界与审查机制技能本质上是代码而且是会自动执行的代码。从Security角度对待新装的技能和对待第三方依赖应该是一个态度。目前应用实现了一套最小权限检查SKILL.md里声明的permissions字段会被校验凡是声明了网络访问或者写权限的技能启用时会弹窗提示。技能的Git历史也会做一轮核查确保没有敏感信息被写进技能文件里。我自己排查过一起事故某个技能脚本里硬编码了一个内部API密钥同步到团队仓库后整个团队的Agent工具都能读到这个密钥。虽然没有造成实际泄露但足以说明技能的安全审查必须前置。我的建议是在团队流程里增加一条硬性规定技能代码必须经过代码评审才能合并到公共仓库和普通项目代码一样对待必要时应检查技能引用的依赖文件是否已经被供应链投毒。最后说一点这几周实践下来最深的体会技能中间层的价值不在于“管理文件”而在于“沉淀一致性”。人肉维护多个工具的技能文件本质上是在用记忆去对抗系统复杂度而这正是项目里应该被自动化取代的部分。Skills Manager现在能统一54个工具的Agent技能分发但真正让它值得长跑下去的是它把“每个工具各自的理解”收敛成了“一套统一的组织知识”而且这个过程是可解释、可回放、可审查的。如果你也在为多工具技能分裂而头疼从这个思路切入做一个统一中枢比给每个工具打补丁要有效得多。