如果你和我一样桌面上同时躺着好几个AI编程工具——Claude Code、Codex CLI、Cursor再装上一个带了Continue插件的VS Code——那你大概率经历过一种说不出的别扭每个工具都支持Agent技能但技能的写法、目录约定、加载方式全都不一样。遇到同一个任务我得在每个工具里重新调教一遍。这种重复劳动攒到某个临界点就会冒出同一个念头能不能有一个统一的地方把这一堆Agent技能管起来这个念头落地之后就是我在维护的项目Skills Manager。简单来说它是一个跨平台的桌面中枢负责统一管理54 AI编程工具的Agent技能——把散落在各个工具里的提示词、脚本、工作流收拢成标准化技能包再自动分发回你日常使用的那些工具。这篇文章不打算讲标准教程我想把当时怎么踩坑、怎么设计、怎么让它真正用起来的过程写清楚尤其面向那些和我一样在多个Agent工具之间来回切换的开发者。如果你正被每个工具一套技能语法这件事折磨这篇应该能给你一个可以落地的思路。1. 从散装技能到统一中枢我在为多套Agent重复写提示词1.1 桌面上至少有四个Agent我却只能各写各的先说日常状态。我主力使用的AI编程工具有四个Claude Code负责写核心模块Codex CLI做批量代码审查Cursor处理日常重构VS Code里的Continue辅助写测试。听起来很合理对吧实际用起来会发现一个绕不开的问题这四兄弟对技能的定义完全是各说各话。Claude Code用的是.skills目录里面放SKILL.md文件靠自然语言描述让Agent理解技能Codex CLI那一套更偏向用AGENTS.md这种指令文件约束行为Cursor走的是.rules规则文件把技能写成项目级的规则片段Continue则有自己的一套commands命令体系。同一个检查未处理的异常技能在这四个工具里是四份完全不同的文本。我最初还能靠记忆力同步等到技能数量突破20个就彻底失控了。失控的第一个信号是我改了Claude Code版本的技能结果忘了Codex CLI那份还停在旧逻辑。第二天用Codex做代码审查它按老规矩跳过了一个已经被我列入黑名单的错误码害我多花了半小时手工排查。那一刻我突然意识到问题不在于我懒也不在于某款工具做得不好而在于我把技能当成了某个工具的自留地而不是属于自己的资产。1.2 重复劳动的代价不是时间是维护意愿这里我想说一个容易被忽略的点重复维护带来的最大损失其实是维护意愿的持续下降。技能少的时候五份就五份忍一忍还能同步。技能一多每份之间的细小差异会让你产生算了不折腾了的心态。一旦这种心态出现技能就开始失效——不是程序崩溃那种失效而是它慢慢跟不上你真实的工作方式。你明知道某个技能写得不够好但一想到要在四个工具里各改一遍就会拖到下周。拖到下周的结果往往是下周也不改最后这个技能就躺在那里吃灰。我尝试过几个缓解方案用Notion整理一份技能笔记把提示词模板统一存到一个Markdown文件里甚至试过用Git子模块去同步不同工具的配置目录。效果都有但治标不治本。笔记不等于可执行文件模板文件没法被工具自动加载Git子模块解决的是版本同步解决不了格式翻译。我需要的是一个中间层——它既能用一套格式描述技能又能把手里的技能翻译成每个工具认识的方言。1.3 统一之后的工作流长什么样受够了手工同步之后我给自己定了一个目标工作流用一个编辑器写技能一次描述让全局可见所有工具自动拉取最新版本任何修改一处生效。听起来很理想化但实现路径是清晰的。在这个工作流里我不再对着Claude Code写Claude Code版技能、对着Cursor写Cursor版技能而是先写一个中性的技能包再由Skills Manager在需要时分发给具体工具。正确用法是你先定义技能本身然后告诉中枢这个技能要支持哪些工具剩下的事交给适配层。对比一下前后的差别以前是1个技能对应N份配置现在是1个技能包加N个适配器。后者多了一点点前期设计成本但长期维护成本直线下降——这个账怎么算都划算。2. 技能仓库不等于收藏夹桌面中枢的核心设计逻辑2.1 技能包的中性格式换工具不换技能真要动手做统一第一个要解决的问题是用什么格式来描述一个技能市面上已经有一些参考比如Anthropic提到的Agent Skills概念社区里也有不少关于skill教程的讨论。但我的需求更具体这个格式必须足够中性不能被任何单一工具绑架。如果我把格式定成Claude Code的SKILL.md变体那Codex CLI适配起来就会很别扭如果定成Cursor的rules风格那通用性又会受限制。最终我采用了技能包的概念每个技能是一个独立目录包含三部分描述文件、参考脚本、引用资源。描述文件负责告诉Agent这个技能是什么、什么时候用、怎么用参考脚本负责把模糊需求变成可执行逻辑引用资源则放清单、模板、示例这类辅助材料。这个结构与大多数工具的加载机制天然兼容因为所有工具最终都是靠文本与Agent交互——你只要能让技能在恰当的时候以一种它看得懂的方式出现在上下文里它就能工作。这个设计思路可以类比成统一充电口以前每个手机厂商都有自己的充电标准换个设备就要换根线。技能包就是那个Type-C口适配器解决的是协议转换而不是重新发明充电器。2.2 匹配与分发为什么需要一个适配层有了统一的技能包格式紧接着的问题是一个技能要怎么落到具体工具里这里就是Skills Manager的核心了我管它叫适配层。适配层要处理三件事第一识别你当前在哪个工具语境下第二把中性技能包翻译成那个工具能理解的格式第三把翻译结果挂到正确的加载位置。整个过程看起来像是技能分发实际上更像一个格式编译的过程。不同工具的适配逻辑差别确实很大我整理了一张表基本能反映当时的适配情况工具类型代表工具技能挂载方式适配重点CLI编码代理Claude Code / Codex CLI目录扫描 / 指令文件SKILL.md语法、指令覆盖范围IDE智能插件Cursor / Continuerules文件 / commands配置规则优先级、项目级vs全局级原生Agent工具Codex、各类Agent平台平台自带技能格式参数传递方式、上下文截断策略通用Agent框架LangChain / ADK等工具函数注册把技能转为可调用函数描述这个表格看起来简单每一条背后都有不少细节。就拿IDE插件来说Cursor的rules文件和Claude Code的SKILL.md在描述方式上是两套语境你在技能包里写的when_to_use字段落到Cursor里可能要转成globs匹配规则。适配层要做的不是简单把文本粘贴过去而是理解两边语义后做一次翻译。这也是为什么我不建议直接把某个工具的技能目录复制到另一个工具。2.3 它不是什么既不是收藏夹也不是文档库做这个项目的时候我经常被问到这不就是一个技能收藏夹吗还真不是。收藏夹解决的是东西放在哪的问题文档库解决的是东西是什么的问题而Skills Manager解决的是东西怎么跑起来的问题。你在收藏夹里存一篇Claude Code的技能教程下次换到Cursor还是不知道怎么写你在文档库里整理一套完整的技能说明Agent并不会自动读到它。Skill不是知识条目它是代码说明参数三位一体的可执行单元。打个比方收藏夹像一个书架你需要的书都在上面但每本书都得自己翻开看Skills Manager像一个训练有素的助手你告诉它按食材清单做饭它自己就知道先去翻菜谱、再检查冰箱里有什么、最后按步骤执行。所以从第一天起这个项目的边界就定得很清楚技能仓库只对可执行的东西负责那些仅供参考的知识资料不进来。3. 全平台的地基本地数据、CLI与GUI的分工3.1 数据存哪本地优先的取舍一站式技能管理工具最容易踩的坑就是一上来就搞云端账号体系。我见过不少类似项目上来就是注册、登录、云同步三件套。但我们的目标用户是天天跟终端打交道的人他们对本地文件有天然的信任感对云同步反而充满了不确定性。我最终选择了本地优先的方案。技能数据保存在本机的~/.skills-manager/目录下元数据用一个SQLite单文件存储技能包本身则是普通目录和Markdown文件。这样做的理由很实离线可用、响应快、隐私可控、迁移方便——搬家就是拷一个目录的事。同步怎么办我没有自己做云同步而是把这个能力开放给现有的工具链你可以直接用Git仓库同步技能包也可以用一个NAS文件夹定时镜像。本地优先不代表拒绝云而是让云变成一个可插拔的可选层。目录结构很简单一眼能看懂~/.skills-manager/ db/ # SQLite元数据库 skills/ # 技能包目录 code-review/ # 自动导入审查技能 semantic-commit/ # 语义化提交信息技能 dependency-check/ # 依赖更新检查技能 templates/ # 公开的技能模板 logs/ # 执行与审计日志SQLite在这个场景里其实比很多重型数据库都合适。单文件、跨平台、支持全文检索对技能元数据这种量级的数据来说绰绰有余。后期如果技能数量涨到几百个SQLite依然能撑住而且你随时可以把数据导出成JSON、CSV或者直接同步到远程Postgres——它是一个面向未来的起点。3.2 CLI做核心GUI做外壳跨平台桌面应用很多人第一反应就是必须有个漂亮GUI。但实际上对Agent技能管理这个场景来说命令行才是真正的核心。为什么因为技能管理天然要跟自动化结合CI流程里要批量更新技能新机器初始化要一键恢复技能环境这些场景都需要能被脚本调用的接口。所以我把Skills Manager设计成CLI为核心GUI为外壳的结构。核心命令基本就这几条sm list查看所有技能sm add添加技能包sm run手动在某个工具里执行技能sm link把技能关联到指定工具sm sync从Git仓库拉取最新技能。GUI其实是包了一个Tauri壳把命令行的输出可视化方便不熟命令行的队友查看技能状态和审核日志。我刻意让GUI做得薄不承载太多业务逻辑。这是个反直觉的取舍因为很多桌面应用都在努力让GUI变厚。我的理由是GUI一旦承担核心逻辑就意味着所有功能都得等UI完成才能用而且自动化场景会被锁死。CLI先跑通GUI只做展示开发效率和灵活性都最高。3.3 安全边界脚本执行前的授权控制本地优先还有一个绕不开的问题安全。技能本质上是可以在你机器上执行的脚本如果不做权限控制等于把家门钥匙交给了任意提示词。这个风险必须正面处理。我的做法是给每个技能包声明权限级别只读、受限读写、完全执行。只读技能只能访问指定目录里的文件受限读写技能可以修改项目文件但不能触碰系统目录完全执行技能则不做限制但必须经过手动确认。所有执行动作都写入审计日志记录谁在什么时间用了哪个技能、访问了哪些路径。实际使用时默认所有技能都是只读或受限读写完全执行这个权限落地时会让用户再做一次二次确认。刚开始有人嫌这个流程烦但后来一次事故让所有人都闭嘴了团队里有人写了一个自动修复依赖冲突的技能包权限声明的是完全执行结果在未确认状态下直接跑了把环境变量文件改乱了。从那以后没有人再说权限确认是多此一举。本地工具的灵活性是一把双刃剑安全边界永远值得前置。4. 让Agent真正听懂技能SKILL.md规范与加载机制4.1 SKILL.md的字段设计如果只把技能包做成脚本合集那和普通工具库没区别。真正让Agent把技能用起来的是那份SKILL.md描述文件。它的作用不是给人看的README而是Agent在运行时理解技能的关键上下文。每个SKILL.md我强制要求六个字段name是技能的唯一标识description说明技能的大致用途when_to_use是本技能的最佳触发时机params列出需要的输入参数steps是给Agent的分步执行动作resources指向脚本和引用文件。六个字段里最容易被忽略、但实际最影响效果的是when_to_use。因为它直接决定了Agent在多技能混用场景下的选择准确率——你可以在描述里写这个技能只用于处理单元测试覆盖率问题但如果没写清楚模型很可能在代码审查任务里也把这个技能拉出来用。结构上我参考了社区里关于Agent Skill的不少经验帖但做了一点本地化改良增加了一个context字段用来声明该技能对工作目录、项目语言、文件类型的默认假设。这个小字段在后面处理跨工具分发时帮了大忙因为每个工具对上下文的感知能力不一样有的工具本身就带着项目全貌有的工具只能看到当前文件context字段让适配层能提前判断分发策略。4.2 一个可直接抄作业的技能包示例空谈规范太抽象直接给一个我日常在用的技能包做例子语义化提交信息生成。这个技能的作用是扫描当前改动生成符合Conventional Commits规范的提交信息。目录结构长这样~/.skills-manager/skills/semantic-commit/ SKILL.md scripts/scan_diff.py references/commit_rules.mdSKILL.md核心内容示例--- name: semantic-commit description: 生成遵循约定式提交规范的git commit信息 when_to_use: 在用户准备执行git commit之前需要生成提交信息时使用 params: target: 要扫描的目录默认当前项目根目录 steps: - 运行 scripts/scan_diff.py --path {target} - 读取 scan_diff.py 输出的改动摘要 - 参考 references/commit_rules.md 中的提交类型表 - 输出一条符合规范的完整commit信息 resources: - scripts/scan_diff.py - references/commit_rules.md version: 1.2.0我希望读者注意几点when_to_use写的是提交信息生成而不是代码变更分析因为一旦这个技能被选中后面几个步骤全部围绕提交信息展开params只有一个target字段避免给模型太多选择空间resources里的两份文件都是必要的一个负责执行一个负责兜底。这个技能包分发到Claude Code里会被扫描进.skills目录分发到Cursor里会转成rules但核心动作没有变。4.3 参数传入与上下文记忆技能包光有脚本还不够Agent能不能正确拿到运行参数直接影响技能的成功率。我一开始把参数写死在SKILL.md里效果很差因为不同项目的路径结构、语言环境差异太大。后来改为参数化设计每个技能都声明自己需要哪些参数并在执行时把参数嵌入上下文中。参数化本身不复杂复杂的是让Agent知道参数该从哪来。这就涉及到Agent记忆的话题了。技能不是每次执行都是失忆状态它会读工作目录里的项目结构会自动提取一些显式参数还会通过本地记忆文件记住上次相关任务的处理偏好。比如semantic-commit这个技能首次执行时用户指定了type粒度要用中文注释这个偏好会被写回记忆下次执行时Agent会主动参考。这个机制让我对技能的理解往前走了一步技能不只是描述文件和脚本的堆叠它还需要一个轻量的上下文状态。Agent在执行技能前会先做一次状态查询执行完再更新状态。这个状态数据就存在本地SQLite里不依赖任何外部服务效果却非常明显——同一技能的第二、三、四轮执行准确率有明显提升。5. 实测在Windows主机上调度54工具的踩坑记录5.1 哪些类型的技能复用率最高项目跑了一段时间后我统计了所有技能在54工具上的实际调用频率结果有些出乎意料。最容易复用的技能不是那些AI味很浓的魔法操作而是四个实用主义类型技能类型代表场景复用率原因分析代码检查类未处理异常扫描、死代码检测很高任务边界清晰脚本能处理大部分逻辑依赖管理类依赖版本冲突分析、更新建议高规则明确模型只需读清单做判断测试补全类为函数生成测试用例高输入输出明确参数简单提交辅助类生成提交信息、整理变更记录高动作单一技能说明短但有效观察这些高复用技能会发现一个共同特征它们都把一个模糊需求压缩成了明确步骤。比如扫描未处理异常模型不用思考什么叫未处理、什么叫异常脚本已经把答案按行输出来了模型只需要解释和汇总。这其实给技能设计提了一个通用原则尽可能把确定性逻辑下沉到脚本里让模型只做决策性工作。5.2 适配各工具时的实际差异理想很丰满真实环境里的适配远比预想中碎。在Windows主机上做全量适配时我撞上了几个真实存在的坑。第一个坑是路径分隔符。Windows用反斜杠\脚本输出的路径如果是POSIX风格某些工具解析时会直接断掉。排查半天发现是技能里的正则表达式没考虑Windows盘符前缀——C:\src\project会被正则当成C:加一个反斜杠分隔符的组合。修复方法很简单所有路径处理统一走pathlib禁止手写字符串拼接路径。第二个坑是编码。Agent运行时经常要读日志文件但我有一个技能在解析前端构建日志时反复失败原因是那份日志是日文Shift-JIS编码脚本按UTF-8去读全变乱码了。更麻烦的是当时用的模型并不会主动告诉你编码不对它只会基于乱码内容给出错误结论。后来我给所有文件读取逻辑加了编码探测层遇到非UTF-8文件自动转码这个问题才算根治。第三个坑是执行超时。某些工具对子进程的运行时长有隐性限制长一点的脚本会被直接杀掉而错误信息往往是一个很模糊的execution terminated due to error。后来我养成一个习惯所有技能脚本都做分块执行每块输出阶段性结果这样即使超时也已经拿到了有价值的中间状态。5.3 误选、失效与技能漂移比适配更折磨人的是Agent会误选技能。技能库越来越大之后模型经常在错误的任务里调用错误的技能。我遇到过最离谱的一次用户明明在做代码重构Agent却调用了依赖版本检测技能给出的建议完全牛头不对马嘴。问题的根因出在技能描述太泛when_to_use写得不够精准。另外两个高频问题就是技能失效和技能漂移。技能失效往往是因为外部API变化——比如某个依赖工具的CLI版本升级参数变了旧脚本直接报废。技能漂移则更隐蔽技能的作者修了一个边缘问题顺手改了脚本逻辑但没更新SKILL.md的描述于是技能的行为和Agent对它的理解出现了偏差。这三样问题我最终的解决方案是流程化的每次技能更新必须同时更新SKILL.md里的版本号和变更说明每季度做一次全量回归执行把技能库里所有技能在重点工具上跑一遍对误选问题除了加强描述约束还会在技能之间加互斥声明——比如提交信息生成和代码审查不能同时出现在一次任务里。这套流程跑起来之后误选率降了一大截。6. 把技能变成团队资产共享、评审与版本管理6.1 技能共享从个人文件夹到团队仓库自己用得顺之后自然想着把它推广到团队。个人技能库和团队技能库之间最大的差异不是内容而是质量门槛。个人可以容忍一个粗糙的技能包团队不行。一个技能万一在关键任务里给错了参数影响的是整个交付节奏。我们团队的做法是搞一个共享技能仓库走PR流程有人新写一个技能先提PR附上样例输出和测试记录评审人按一份Checklist逐项打分——名字是否清晰、描述是否准确、触发条件是否够窄、示例是否完整、有没有覆盖边界情况。这套流程不是摆设一开始有人嫌麻烦但连续几次因为技能质量差导致线上问题之后大家都默认了规则。现在团队里两百多个技能质量比最开始下降得慢很多。6.2 多Agent协作下的技能编排技能库有了规模之后另一个价值才真正浮现出来多Agent协作。现在的AI编程工具早就不是单打独斗了日常任务往往要多个Agent角色配合。某些技能属于规划类Agent负责拆解任务、生成实现步骤另一些技能属于执行类Agent负责写代码、跑测试、改文件。Skills Manager在其中扮演的是路由层的角色它知道哪个Agent擅长什么也知道哪个技能适合哪个Agent。任务进来之后中枢会做一个初步意图识别把任务拆成若干子步骤每个子步骤挂对应的技能和Agent。这时候单个技能包就不再是孤立的资产而是整个多Agent工作流里的一个齿轮。说实话这个方向目前还在演进中但已经能看到明显的优势单个Agent不需要内置全部能力AI Agent中台化之后每个Agent保持小巧、专注复杂度靠技能编排去承接。这个架构对团队新人也友好上手时只需要读对应技能的SKILL.md而不用先啃整个Agent框架的源码。6.3 沿着这条路线继续改造我的下一步项目走到现在最初的统一管理技能目标已经完成了大半真正的价值反而沉淀在别处一套统一的技能心智模型。以前团队成员对技能的理解千差万别有人理解成提示词模板有人理解成脚本工具现在大家有了共同语言——技能就是描述脚本资源的包有版本、有权限、有触发条件。下一步我想在这个底子上加两个东西。第一个是技能生成器让Agent根据一个实际任务描述自动反写出完整的技能包结构。说白了就是把把经验固化成技能这件需要动脑子的事用模型辅助做掉一半。第二个是技能健康度仪表盘通过记录每个技能的执行成功率、误选率、更新频率给每个技能一个健康分低分的自动进入待评审队列。我更希望让技能库像开源项目一样持续演化而不是建好之后就变成一堆僵尸文件。最后交代一句心里话这个项目算不上什么惊世骇俗的发明它解决的就是一个日常到不能再日常的痛点——我有N个AI编程工具而我实在受不了给它们各写一套技能。如果你也有同感建议别急着再去找第N1个工具先把已有技能统一起来你会有一种终于不用做重复劳动的踏实感。