最近我把手头最乱的一件事收拾明白了——AI编程工具的 Agent 技能管理。这话听起来有点抽象，但当你的电脑里同时装着 Cursor、Claude Code、Codex、Windsurf、Continue，再加上一堆命令行 Agent 的时候，你会发现每家的“技能”（Skill）都有自己的脾气：有的塞在.rules文件里，有的必须叫SKILL.md，有的要放到全局配置目录，有的只能在项目目录里生效。折腾一圈下来，技能没积累多少，心力倒耗了一大半。所以我做了这个跨平台桌面的 Skills Manager，把 54+ AI 编程工具的 Agent 技能统一管起来。这篇文章把整个项目的设计思路、技术选型和踩坑记录都写清楚，给正在折腾 Agent 技能的同行做参考，也让刚入门的同学知道技能（Skill）到底怎么组织、怎么同步、怎么维护。
1. 为什么需要统一 Agent 技能：从一个混乱的桌面说起
1.1 三种工具、三套规则，脑子先乱了
我有段时间的工作流是这样的：主力编辑器 Cursor，日常对话和重构用 Claude Code，跑比较独立的自动化任务用 Codex CLI，偶尔还切到 Gemini CLI。看起来互补性很好，实际上每天光“记录某个技能的写法和路径”就花掉大量精力。比如我给 Cursor 写了一个“SQL 查询优化”的规则，它应该是一个.cursor/rules/sql-optimizer.mdc文件；同样内容要放到 Claude Code，得放到~/.claude/skills/sql-optimizer/SKILL.md；再给 Codex 一份，又要搬到~/.codex/skills/sql-optimizer/。文件内容大同小异，格式却各自为政。
更要命的是版本不一致。我在 Claude Code 里更新了一段“脱敏输出”的要求，Cursor 里还是三个月前的旧版。靠手动复制粘贴维护多份技能，迟早会漏。这里的核心问题不是“有没有一个好的技能提示词”，而是“技能资产没有一个统一的宿主”。一个技能的基本信息，名称、描述、用途、版本、适用工具、资源文件、示例、更新历史，散落在不同工具的配置目录里。你需要的是一个能统一建模、统一编辑、统一分发的东西。
1.2 技能（Skill）到底是什么：从提示词到可复用能力包
很多人会把 Skill 理解成一个“比较长的 system prompt”，其实不太准确。在实际使用中，Skill 是一个可复用的能力包，它至少包含三部分：元数据、指令正文、资源附件。元数据通常是 YAML 格式的 frontmatter，标记技能名称、描述、版本、作者、标签、适用工具；指令正文是一段结构化 Markdown，告诉 Agent 什么场景应该用、怎么用、有哪些约束；资源附件可能是示例代码、参考文档、模板文件、校验脚本，Agent 会按正文指引去读取这些附件来执行任务。
之所以会有这么多不同的“形态”，是因为各家 Agent 的加载机制不同。Cursor 的.mdc规则基于 glob 文件匹配触发，Claude Code 的 Skill 基于目录扫描和描述相关性触发，Codex 也有自己的技能目录约定。但如果我们在统一层面把它们拆成“技能仓库 + 适配器”，就能做到：源头只维护一份标准技能包，不同工具各取所需。这正是 Skills Manager 的核心逻辑。
1.3 54+ 工具怎么数出来的
项目统计支持的 54+ 工具，指的是当前主流的 IDE 插件、CLI Agent、编程框架和云端智能体工具。常见的有 Cursor、Windsurf、Copilot、Claude Code、Codex、Gemini CLI、通义灵码、CodeGeeX、Tabby、Continue、Amazon Q、Devin、CrewAI、LangChain、AutoGPT 等，也包括一些较新的开源 Agent。无论它们是本地运行还是云端执行，统一入口都遵循“技能定义 + 转换器”模型。我不追求每一种都覆盖完整，但提供了通用插件机制，任何人写一个适配器配置文件就能接入新工具。
2. 整体方案与架构设计：桌面中枢能做什么
2.1 项目定位与核心能力
Skills Manager 不是一个聊天客户端，也不是提示词编辑器。它的定位是“跨平台桌面中枢”，管理所有 AI 编程工具的 Agent 技能。具体能力可以归纳为四个模块：统一编辑、格式转换、同步分发、版本回溯。
统一编辑解决“一处修改，多端生效”的问题。你只维护一份标准SKILL.md，界面里选好目标工具，点击同步，后台会自动生成对应格式的文件并放到正确位置。格式转换不是简单改扩展名，每种工具的书写规范、触发规则、目录层级都不同，转换器要能处理这些差异。同步分发支持指定工具、指定项目、全局三种范围，也可以设置自动 watch。版本回溯则依赖技能仓库本身启用 Git，每次修改都能 diff，错误同步后一键复原。
2.2 技术选型：为什么是 Tauri + React + TypeScript
桌面中枢的选型我认真对比过 Electron 和 Tauri，最后用了 Tauri v2 配 React、TypeScript，核心数据管理部分用 Rust。原因有三。第一，这个工具大量操作文件系统，Tauri 的 Rust 后端处理路径枚举、文件 hash、目录监听都比 Node.js 更可靠，尤其是 Windows 下的路径处理和 Linux 下的权限问题。第二，Tauri 打包体积小、内存占用低，作为常驻后台工具很合适，Electron 的几百兆占用对这个场景太重。第三，前端用 React 开发界面效率高，TypeScript 能约束技能 Schema 的字段，降低适配器写错 key 的概率。
跨平台上的血泪经验是：永远不要直接拼路径字符串。项目里全部用 Rust 的PathBuf和前端upath，windows path 与 posix path 的转换由适配器统一处理。Windows 的%USERPROFILE%、Mac 的/Users/xxx、Linux 的/home/xxx，表面上是环境变量差异，实际还牵扯大小写、盘符、权限等问题，后面会单独讲。
2.3 三层架构：技能仓库、适配器层、同步引擎
整体分成三层，职责非常清晰。底层是技能仓库（Skill Registry），负责统一技能包的存储、索引和查询。每个技能是一个目录，内含SKILL.md、assets/、scripts/、meta.yaml。SKILL.md是给人读给 Agent 读的指令，meta.yaml是给程序识别用的结构化信息，assets 放参考文件，scripts 放可执行脚本。
中间层是适配器层（Adapter Layer）。每个工具对应一个适配器，定义四类信息：安装路径解析规则、技能格式生成规则、触发条件映射、冲突处理策略。比如 Cursor 适配器读取项目下.cursor/rules目录，把标准技能生成.mdc文件，frontmatter 里写入 description 和 globs；Claude Code 适配器把标准技能展开到~/.claude/skills/<skill-id>/目录；Codex 适配器则写到~/.codex/skills/<skill-id>/。适配器层不关心技能内容怎么编写，只负责翻译。
最上层是同步引擎（Sync Engine）。它接收 UI 或 CLI 的指令，遍历技能仓库，调用目标适配器，计算文件指纹，只将变化的部分写盘。同步引擎还负责反向读取，也就是把现有工具目录里的旧技能导入到统一仓库，完成从混乱到统一的第一步。
2.4 统一技能包格式：SKILL.md + 资源目录
统一格式是整个项目的地基。我参考了目前较主流的开源 Skill 规范：每个技能目录必须包含SKILL.md，文件头是 YAML frontmatter，正文是 Markdown。固定的约束条件如下：
name：技能唯一标识，英文加中划线，例如sql-query-optimizerdescription：一句话说明技能适用场景，这段会被 Agent 系统读到，决定任务是否需要调用该技能version：语义化版本号，用于同步和 difftools：允许使用的工具列表，留空表示不限制model_safety：可选的模型安全等级，比如禁止某些高危操作tags：分类标签author和license
严格说，技能正文没有固定模板，但我强烈建议统一采用三段式结构：When to Use（触发条件）、How to Use（操作步骤）、Examples & Verification（示例与验证）。这样无论 Agent 怎么解析，关键信息都不会丢。assets 目录放图片、数据文件、模板工程；scripts 目录放 Python、Shell、SQL 脚本，Agent 会把它们当作可执行参考或直接运行。这套格式看起来简单，好处是通用性强，所有适配器都能无损转换。
3. 核心实现：如何把一个技能“分发”到各工具
3.1 技能仓库的数据模型
我在前端和 Rust 后端之间定义了一套核心数据模型，所有页面和适配器都围绕它运行。核心对象是SkillRecord，记录巡检状态、目录路径、元数据缓存和文件清单。元数据不直接解析 Markdown，而是每次改动时编译成 JSON 存到本地 SQLite，这样列表页几千个技能也能秒开。SQLite 里还存了“最后同步时间”和“各工具指纹”，方便 UI 展示每个技能在每个工具下的状态。
另一个关键是标签与搜索索引。技能多了之后，必须能快速定位。我用了 SQLite FTS5 做全文搜索，同时支持按工具、目录、标签、是否启用过滤。搜索是桌面软件最容易被忽略的能力，等技能到几百个以后，没有搜索基本没法用。另外，我建议给每个技能打上“工具无关”或“工具内聚”标签：前者是纯提示词和通用规范，任何工具都能翻译；后者包含特定工具 API、快捷键或插件配置，适配器转换时会做特殊映射。
3.2 适配器的工作方式：从统一包到工具原生格式
适配器是整个项目的翻译官，是最需要耐心写的部分。每个适配器本质上是一个“编译器”，输入统一技能目录，输出目标工具要求的结构。以三个最典型的工具为例。
Cursor 适配器。Cursor 用.cursor/rules/*.mdc文件，文件头部要有 YAML frontmatter，至少包含description和globs。description决定了 Cursor 在什么情况下自动加载规则，globs决定了哪些文件命中规则。转换时，我会把统一技能的description转录到description，把技能正文中的“When to Use”部分提炼为 globs 判断条件；如果技能本身是通用性的，globs 设为空，让 Cursor 按描述自动触发。需要注意，.mdc文件的正文不需要再加标题，直接从---后开始写 Markdown。
Claude Code 适配器。Claude Code 遵循 Anthropic 的 Agent Skills 规范，标准目录是全局的~/.claude/skills/<skill-id>/，里面必须有SKILL.md，且 frontmatter 里的name必须与目录名一致，否则 Claude Code 会忽略该技能。这个适配器最省事，直接把统一包原样拷贝过去，但有一个坑：Claude Code 会读取 SKILL.md 的全文作为技能描述的一部分，如果正文太长，会导致意图识别不准确。所以适配器在转换时要生成一个“精简描述版本”作为 frontmatter 的 description，而把完整做法放到正文。这属于典型的一处统一、多处适配的优化点。
Codex CLI 适配器。Codex 的技能目录目前也接受 SKILL.md 格式，但加载机制更依赖名称和描述匹配。如果技能名包含空格或非 ASCII 字符，Codex 会找不到。适配器会把技能名统一转为小写 kebab-case，同时生成AGENTS.md中需要的引用片段。Codex 适配器还有一个特殊功能：它能从技能目录的scripts/里扫描并生成可执行命令列表，写入技能目录下commands.md，方便 Agent 发现可使用的外部命令。
3.3 跨平台路径与配置目录处理的细节
跨平台桌面软件的 80% 坑都在路径上。第一类坑是“你认为的目录不是用户真实的目录”。比如 Claude Code 的全局目录在 macOS 是~/.claude，在 Linux 可能是$XDG_CONFIG_HOME/claude（如果设置了环境变量），在 Windows 是%USERPROFILE%\.claude。你不能只读home目录拼接，必须优先读工具自己的环境变量和配置文件。为此，每个适配器内置了一个envParse函数，注册多个候选路径，按优先级依次检查，并把检测结果可视化展示在界面里。第二类坑是路径大小写。macOS 默认大小写不敏感，Linux 敏感，同一套代码在两边行为可能完全不同。我的处理方式是统一在导入时强制小写技能 ID，并且保留一份原始名称映射，避免跨平台仓库 clone 后路径失效。第三类坑是权限。给系统级目录写入时，有些平台会触发自保护机制，我会在同步前先“试写一个探针文件”，能写才继续，不能写就提示改用用户目录或项目目录。
3.4 UI 和 CLI 的协作：好看的表和好用的命令行
桌面中枢不是只有界面。我同时提供一个skills-managerCLI，和 GUI 共享同一个 Rust 核心库。GUI 适合浏览、编辑、对比和日常操作；CLI 适合写脚本、批量处理、集成到 CI/CD。两者的数据层完全一致，都连接 SQLite，都调用同一套同步引擎。
CLI 的设计原则是“命令动词优先”：skills-manager list列出全部技能，skills-manager install cursor sql-query-optimizer安装指定技能到 Cursor，skills-manager sync --all全局同步，skills-manager diff cursor查看 Cursor 目录与仓库的差异。这些命令在 GUI 里也有入口，但我还是保留了 CLI，因为很多技能维护场景是批量操作，比如给所有技能打标签、统一补充 license，用 Shell 循环要比点几百次页面舒服得多。
4. 实操指南：装起来，把第一个技能同步到三种工具
4.1 安装与初始化
项目目前支持 macOS、Windows、Linux，安装包分别基于 tauri-bundler 生成。macOS 用 Homebrew：brew install skills-manager；Windows 用 winget 或 portable 包；Linux 提供.deb、.rpm和 AppImage。第一次启动会进入初始化向导，选择你要接入的工具，向导会自动探测工具安装情况并列出检测到的配置目录。这一步很重要，如果探测结果不对，后续同步都会出问题。探测完成后，会在你的用户目录下创建仓库根目录（默认~/.skills-manager/），里面包含registry/、adapters/、config.toml。registry/放统一技能包，adapters/放第三方适配器，config.toml记录工具的路径映射和默认同步策略。
初始化时还有一个功能：导入现有技能。如果你已经在 Cursor、Claude Code 目录下攒了规则，可以选择“反向导入”，适配器会把已有.mdc或 Skill 目录读出来，转成统一格式放进 registry。反向导入不会改原文件，只是建立镜像。我建议每导入一个技能都检查一下它的 frontmatter，因为很多旧规则根本没有 metadata，description 可能写得很差，Agent 加载后容易误触发。
4.2 新增一个技能并同步到三种工具
在界面里，“新增技能”就是一个表单，但要注意的是：技能名称即目录名。我推荐使用domain-action式命名，比如git-commit-message、api-error-handling、sql-index-analyzer，既能一眼看懂，也符合大多数工具的命名约束。填好 name 和 description 后，会生成基础目录和模板文件。然后你只需要编辑SKILL.md正文，写清楚 When to Use、How to Use、Examples。
写完之后，在技能详情页点“同步”，左侧勾选 Cursor、Claude Code、Codex，同步引擎开始工作。界面会显示每个工具的执行结果，比如 “Cursor rules updated”、“Claude Code skill installed”、“Codex skills synchronized”。如果某一个失败，会展示失败原因，常见的是权限不足或目标目录不存在。此时不要大改配置，先检查适配器里的路径是否正确，再确认工具是否真的安装了最新版本。
同步完成后，建议立刻到对应工具里验证一次。怎么验证？在 Cursor 中新建文件写一个相关的坏 SQL，看它是否自动调用你的 SQL 优化规则；在 Claude Code 中直接问“现在给你一个销售数据库，帮我写一条查询”，看它的回复是否受到技能正文的影响；在 Codex CLI 里运行codex --ask后描述一个场景，看它是否列出可用的命令。验证的意义大于同步，因为适配器只能保证文件格式对，不保证触发逻辑符合你预期。
4.3 版本管理、禁用与回滚
技能仓库整体是一个 Git 仓库，Skills Manager 会在每次编辑或同步后自动 commit。版本管理的粒度可以细到单个技能目录：如果某个技能改坏了，你可以只回滚那一个目录。回滚功能在 UI 里是右键菜单“Restore previous version”，在 CLI 里是skills-manager rollback sql-query-optimizer。回滚对象并不是原工具里的文件，而是 registry 里的统一包，回滚后再触发一次同步，原工具目录才会恢复。这里有一个容易踩坑的细节：如果你之前已经手动改过工具目录里的文件，回滚同步时可能会有冲突。我的策略是同步前先做文件 hash 比对，发现不一致会弹窗询问“覆盖还是保留本地修改”。默认为“仓库优先”，但建议你选择“先备份再覆盖”。
禁用技能是另一个高频操作。一个 Agent 工具同时启用太多个技能，会导致系统提示膨胀、意图判断变慢、甚至出现上下文被无关技能挤占。所以每个技能都有启用/禁用状态。禁用不是删除，而是同步时跳过该技能，并在配置中记录为disabled。我在做了大量实验后建议：单个项目同时启用的 Cursor 规则不要超过 20 个，Claude Code 技能不要超过 30 个。超过之后不仅 Agent 响应会变慢，你还很难判断某个行为到底是被哪个技能影响的。
4.4 内置技能模板库与手写 SKILL.md 的注意事项
为了让新手有东西可上手，项目内置了 40+ 个技能模板，按领域分成前端、后端、数据库、DevOps、代码审查、性能优化、安全等。这些模板不是随随便便写的，每条模板都经过实测。比如“数据库慢查询分析”模板，包含三个部分：统一的 query 采集方法、索引评估清单、输出报告格式。模板的价值不只是内容，还在于呈现了“技能包”应该怎么拆结构。
手写技能时最容易翻车的有三个点。第一，description 不要用形容词，要用动词加宾语加场景：“优化 SQL 查询性能，尤其是存在多表 JOIN 和缺失索引时”远比“数据库查询优化助手”有效。第二，正文不要只有概念，要有步骤。Agent 需要的是可执行的动作序列，不是知识百科。第三，不要放无法验证的指令。比如你说“严格遵守公司规范”，Agent 不知道公司规范是什么，应该在 assets 里放一份规范文档，正文里写“读取 assets/company-style.md 并遵守”。基本每一条我试用过后都发现，好的技能描述能显著提高触发准确率。
5. 常见问题与排查技巧实录
5.1 技能没被 Agent 加载怎么办
遇到技能不生效，先不要怀疑适配器，先打开工具的调试日志或排查列表。Cursor 可以通过命令面板运行 “Cursor: Show Active Rules”，查看当前会话真正加载了哪些规则。Claude Code 可以在启动时加--debug，日志里会显示扫描到哪些 skill。Codex 可以用codex --info查看加载的技能列表。如果工具列表里根本没有你的技能，问题多半出在目录位置或命名规则上，对照适配器的检测结果再查一遍。如果工具列表里出现了技能，但 Agent 没有按预期行为响应，则是 description 或 globs 写得不匹配，需要调整描述里的关键词。
5.2 同一个技能在不同工具下表现不一致
这也是常态，因为每种工具的底层模型和上下文策略不同。最简单的例子：Cursor 大概率会遵守.mdc里的“强制性”措辞，但 Claude Code 可能会因其自身的安全指令而拒绝直接执行“你是一个 SQL 专家”这种身份命令。所以适配器在转换时要做“措辞适配”：给 Cursor 的文案可以偏命令式，给 Claude Code 的文案改成“建议在满足以下条件时执行”，给 Codex 的文案强调“这是一个可调用工具”，同时保留步骤细节。表现不一致并不代表同步失败，它只是说明技能内容与 Agent 的原生能力存在叠加。我的经验是，关键操作要在正文里写清楚“边界条件”和“退出条件”，这会大大减少各工具的行为偏差。
5.3 Windows 和 macOS 同步结果不一致的路径坑
最常见的是 Windows 下路径分隔符问题。比如统一仓库里记录了assets/sample.sql，Windows 端如果直接按/拆分，就会在读取附件时找不到文件。正确做法是所有路径在内部统一使用 POSIX 风格存储，在写工具目录时按平台转换。另一个问题是 Windows 的 OneDrive 同步文件夹可能导致~/.claude实际指向云端目录，这是隐蔽问题。我会在初始化时打印实际解析路径，并用一个显眼提示告诉你“当前 Claude 目录位于云同步目录中，建议关闭云的自动下载或改为本地目录”，否则你的技能可能被云端状态覆盖。还有一个 macOS 用户容易遇到的问题：系统升级后~/Library/Application Support下的工具配置会被迁移，导致路径失效，所以适配器的候选路径要多加一层“验证存在性”逻辑，不存在时回到默认路径。
5.4 大仓库查询慢和界面卡顿的处理
技能数量增长后，界面卡顿往往发生在首次扫描目录的时候。原因很简单：在 UI 线程里做了递归枚举和文件读取。我优化方式是所有 IO 走 Rust 异步线程，前端只接收 JSON 结果；文件扫描做了缓存，只会在目录变更时增量刷新；同时把 SKILL.md 的 YAML 解析做成增量解析，只有修改过的文件才重新解析。如果你还是觉得慢，可以打开配置里的 “lazy_load” 选项，这意味着列表页只显示技能名和描述，不加载正文预览，点开详情时才读取全文。这个优化在几千个技能时效果明显。
5.5 问题排查速查表
| 现象 | 优先检查项 | 处理建议 |
|---|---|---|
| 技能在工具列表里看不到 | 适配器输出的目标路径是否与工具实际读取路径一致 | 重新执行路径检测或手动映射 |
| 技能有多个版本混动 | 仓库 Git 状态是否干净 | 提交未提交变更，再做一次同步 |
| 同一条规则有的项目生效有的不生效 | globs 或 description 太宽泛 | 收敛到具体文件名或目录 |
| 技能正文中的附件没被读取 | assets 目录没有随 skill 一起同步 | 检查适配器是否复制 attachments 目录 |
| 修改技能后工具不感知 | 工具需要重启或清缓存 | 重启 Agent 会话或执行 reload 命令 |
| 同步时报权限不足 | 目标目录属于系统保护目录 | 改用用户目录或项目级配置 |
| 导入后其他工具出现异常技能 | 原工具格式与统一 Schema 冲突 | 删除该技能并用模板重建 |
6. 实践扩展：把 Skills Manager 接入团队协作
6.1 用 Git 仓库做团队级技能中心
个人使用只是第一步，我现在已经把这套中枢接到团队协作里。做法是把registry/目录单独抽成一个 Git 仓库，团队成员各自保留 Skills Manager 和本地同步配置，但registry通过 Git 保持一致性。新增或修改技能后，提交 MR 再合并，其他人执行skills-manager sync --all就能拿到最新技能。团队仓库的目录结构要有意识地区分“全员通用技能”和“小组专属技能”，最好在仓库根目录放一个catalog.yaml，描述哪些技能对哪些部门可见。
6.2 技能评审与自动化验证
技能写多了之后，需要像一个代码库一样做 review。我在 CI 里加了几个检查脚本：校验 YAML 格式、检查 frontmatter 必填字段、扫描正文里的失效链接和过时指令。还有一个价值较高的检查是“技能冲突检测”，即通过语义关键词判断两个技能是否存在明显重叠。比如你既有一个sql-query-optimizer又有一个slow-query-analysis，它们大概率会抢占同一类任务，Agent 可能会随机加载其中一个，表现不稳定。这时候我会建议合并或明确分工。自动化验证做起来不难，关键是团队愿意把技能当作正经工程资产维护。
6.3 后续可以怎么扩展
未来的扩展方向很多。一个是加上 Agent 侧评测：在某个工具里跑一组任务，记录启用/禁用某个技能后的成功率、耗时代币，用真实数据指导技能优化。另一个是支持在线技能市场：把技能包打包成.skt文件，上传到公共仓库，别人一键安装。还有一个方向是让技能具备“条件能力”，比如根据项目技术栈自动选择技能版本，同一技能为 Vue 项目和 React 项目分别加载不同资源。这些技术上都可行，但最基础的一步仍然是：先让技能在本地被规范管理起来，否则做得再多都是空中楼阁。
我在实际使用中最大的感受是：AI 编程工具本身的模型能力差距已经越来越小，真正拉开体验差距的，是你能不能把自己的经验沉淀成可复用的技能，并让它在所有工具间保持一致。Skill Manager 帮我解决了这个问题的地基部分，接下来我也会把更多精力放到技能内容本身的打磨上。如果你也在折腾 Agent 技能，建议你先花一下午把自己的规则整理成统一格式，再去挑适配器，相信我，这个时间花得值。
