1. 项目概述一个本地化的AI技能管理中心如果你和我一样在日常开发中同时使用多个AI编程助手——比如Cursor、Claude Code、Codex CLI那么你肯定遇到过这个让人头疼的问题每个工具都有自己的一套“技能”Skills系统这些技能文件散落在你电脑的各个角落像~/.cursor/skills、~/.claude/skills这样的目录里。时间一长你根本记不清哪个工具装了哪个技能版本是否同步想禁用或更新一个技能更是无从下手只能手动去翻找和修改文件夹。skill-manager就是为了解决这个痛点而生的。它是一个本地优先的桌面应用核心目标就一个把你所有AI编程助手的技能统一到一个可视化的管理界面里。你可以把它想象成 macOS 上的“系统偏好设置”或者一个本地的“App Store”但专门管AI技能。它目前原生支持 macOS通过 Homebrew 或 npm 一键安装上手非常快。简单来说有了它你不再需要面对一堆散乱的文件夹和配置文件。所有技能的状态已安装、未管理、已启用、已禁用一目了然你可以跨工具批量操作还能从一个内置的“市场”安全地安装新技能。这对于追求效率、讨厌混乱的开发者来说绝对是一个能提升幸福感的工具。2. 核心设计思路与工作原理拆解2.1 问题根源技能管理的“碎片化”困局在深入使用skill-manager之前我们得先搞清楚它要解决的根本问题是什么。目前主流的AI编程助手我称之为“驾驭器”Harness都采用了类似的技能扩展架构每个工具在用户目录下创建一个专属文件夹如~/.cursor/skills用于存放用户安装的第三方技能包。这些技能包通常是一个包含skill.json配置文件和实现代码的目录。这种设计在单一工具下是没问题的。但当你成为多工具用户时麻烦就来了重复安装与空间浪费一个好用的“代码审查”技能你可能在Cursor里装一次在Claude Code里又装一次。磁盘上存了两份一模一样的文件。状态同步地狱你在Cursor里更新了某个技能的版本但Claude Code里的那个旧版本毫不知情。两个工具里的技能行为可能不一致调试起来非常痛苦。管理黑洞你无法快速回答“我的电脑上到底装了多少个技能”、“哪些技能是哪个工具在用的”这类基本问题。管理动作禁用、删除变得高风险因为你不知道动一个文件会影响到哪个工具。skill-manager的设计哲学非常清晰引入一个中心化的“托管仓库”并通过符号链接Symlink来解耦物理存储与逻辑引用。2.2 核心架构托管仓库与符号链接桥接skill-manager在本地创建了一个独立的、统一的技能仓库路径通常是~/Library/Application Support/skill-manager/shared。这个仓库就是所有技能的“唯一真相来源”。它的工作流程可以概括为两个阶段阶段一发现与盘点当你首次启动skill-manager它会自动扫描你系统上已安装的、它支持的AI工具如Cursor、Claude Code等并读取它们各自的技能目录。然后它会进行比对分析将技能分为两类已托管技能已经由skill-manager统一管理的技能存储在它的共享仓库里。未托管技能由各个AI工具自行安装和管理散落在各自目录里的技能。这个阶段只读不写目的是给你一个完整的资产清单。阶段二统一管理这是skill-manager发挥威力的地方。你可以对一个“未托管技能”执行“纳入管理”操作。此时skill-manager会做以下几件事将该技能从原始位置例如~/.cursor/skills/my-skill移动到自己的共享仓库中。在原始位置创建一个符号链接指向共享仓库中的新位置。对于其他也安装了同名技能的AI工具skill-manager会找到它们的技能目录删除旧的实体文件并创建指向同一个共享仓库的符号链接。完成这个操作后物理上这个技能只在skill-manager的共享仓库里存在一份。所有AI工具通过符号链接访问它。你在skill-manager中启用、禁用、更新或删除这个技能所有链接到它的工具都会同步生效。提示符号链接是类Unix系统包括macOS的一个核心特性它像一个“快捷方式”或“指针”。对符号链接的读写操作会直接作用于它指向的真实文件。skill-manager利用这一点实现了“一份存储多处使用”的精妙设计。2.3 安全边界与数据所有权作为一个需要操作你本地文件的工具安全是首要考量。skill-manager采用了“本地优先”原则所有数据都在本地技能文件、配置、缓存都在你的电脑上不依赖云端服务市场浏览除外。明确的权限边界它只会操作你明确指定的、它所支持的AI工具的技能目录。它不会触碰这些目录之外的文件也不会修改工具本身的二进制文件。操作前确认对于“删除技能”、“停止管理”等破坏性操作应用都会有明确的二次确认弹窗防止误操作。这种设计让你在享受便利的同时依然牢牢掌握着数据的最终控制权。3. 详细安装与初始化配置指南3.1 环境准备与安装方式选择skill-manager目前主要面向 macOS 用户。在安装前请确保你的系统已安装较新版本的 Node.js18和 Python3.11不过如果你使用 Homebrew 安装这些依赖大部分会自动处理。你有两种主要的安装方式强烈推荐使用 Homebrew方式一Homebrew 安装推荐Homebrew 是 macOS 上最优秀的包管理器它能更好地处理依赖、更新和卸载。# 1. 添加 mode-io 的软件源Tap brew tap mode-io/tap # 2. 安装 skill-manager brew install skill-manager # 3. 启动应用 skill-manager start执行skill-manager start后应用通常会启动并尝试在默认浏览器中打开本地管理界面通常是http://127.0.0.1:5173。方式二npm 全局安装如果你更熟悉 Node.js 生态也可以选择 npm 安装。npm install -g mode-io/skill-manager skill-manager start重要注意事项安装渠道二选一Homebrew 和 npm 的全局安装是互斥的。如果你之前用 npm 装过想换到 Homebrew必须先执行npm uninstall -g mode-io/skill-manager。反之亦然从 Homebrew 换到 npm 前需要brew uninstall skill-manager。混合安装会导致路径冲突命令无法执行。3.2 首次启动与权限授予首次启动skill-manager时因为它需要扫描你的文件系统以发现AI工具和技能macOS 可能会弹出“文件与文件夹”访问权限的请求。你必须点击“好”或“允许”否则应用将无法读取到任何已安装的技能核心功能也就失效了。这个权限请求是 macOS 沙盒安全机制的一部分skill-manager需要它来访问~/Library、~/.cursor、~/.claude等用户级目录。请放心它只会访问与技能管理相关的路径。3.3 自定义技能目录路径高级绝大多数用户使用默认配置即可。但如果你使用了自定义的AI工具安装路径或者技能目录不在默认位置skill-manager支持通过环境变量进行配置。你可以在启动skill-manager前在终端中设置相应的环境变量。例如如果你把 Claude Code 的技能目录改到了~/Documents/claude_skills可以这样操作export SKILL_MANAGER_CLAUDE_ROOT~/Documents/claude_skills skill-manager start或者为了永久生效可以将export语句添加到你的 shell 配置文件如~/.zshrc或~/.bash_profile中。支持配置的工具和环境变量如下AI 工具 (Harness)环境变量默认技能根目录Codex CLISKILL_MANAGER_CODEX_ROOT~/.agents/skillsClaude CodeSKILL_MANAGER_CLAUDE_ROOT~/.claude/skillsCursorSKILL_MANAGER_CURSOR_ROOT~/.cursor/skillsOpenCodeSKILL_MANAGER_OPENCODE_ROOT~/.config/opencode/skillsOpenClaw(暂不支持配置)~/.openclaw/skills4. 核心功能实操详解4.1 技能总览与状态解读启动skill-manager并打开其 Web 界面后你会首先进入“技能”工作区。这里是你所有技能的指挥中心。界面通常会以列表或卡片形式展示技能每个技能会显示以下关键信息技能名称与图标易于识别的标识。描述该技能的主要功能说明。管理状态已托管该技能已被skill-manager统一管理存储在共享仓库中。图标或标签通常为绿色或带有“Managed”标记。未托管该技能由某个AI工具独立管理skill-manager只能读取其信息。图标或标签通常为灰色或带有“Unmanaged”标记。启用状态针对每个已支持的AI工具显示该技能是启用对勾还是禁用叉号。对于已托管技能你可以直接在这里点击切换。来源显示技能是来自内置市场、GitHub仓库还是本地自定义。实操心得快速梳理资产首次使用时建议你花几分钟仔细浏览这个列表。重点关注“未托管”的技能思考哪些是你常用的、希望统一管理的。你可以利用搜索或过滤功能快速找到特定工具如Cursor下的所有技能做到心中有数。4.2 将未托管技能纳入统一管理这是skill-manager最核心的操作。找到你想统一的“未托管”技能点击它通常会有一个“纳入管理”或类似的按钮。点击后skill-manager会在后台执行我们之前提到的“移动文件创建符号链接”流程。这个过程通常是瞬间完成的。完成后你会发现该技能的状态从“未托管”变为“已托管”。该技能在原始AI工具技能目录中的实体文件夹消失了取而代之的是一个符号链接。你可以在skill-manager中直接控制这个技能对所有AI工具的启用/禁用。注意操作前请理解风险“纳入管理”是一个移动操作不是复制。虽然理论上你可以从skill-manager的共享仓库中找回文件但为了安全起见在进行批量操作前建议对你重要的技能目录进行一次手动备份例如压缩备份~/.cursor/skills文件夹。虽然我用了这么久没出过问题但良好的备份习惯是开发者的必备素养。4.3 多工具启用/禁用精细控制技能被托管后最大的便利就是可以按工具精细控制。在技能详情或列表视图中你可以看到一列代表不同AI工具Cursor, Claude Code等的开关。场景举例你安装了一个“Java Spring Boot代码生成”技能这个技能可能对Cursor和Claude Code很有用但对主要写Python的你用Codex CLI时就是干扰。以前你需要在两个工具的配置里分别找地方禁用或者干脆删除文件。现在你只需要在skill-manager里关闭该技能对Codex CLI的开关即可。Codex CLI将完全“看不到”这个技能而Cursor和Claude Code的使用不受任何影响。这个功能完美解决了技能泛滥导致的“噪音”问题让每个工具的技能列表都保持高度相关和简洁。4.4 从市场发现与安装新技能除了管理现有技能skill-manager还内置了一个“市场”视图。这里聚合了来自skills.sh等来源的社区技能。你可以像浏览应用商店一样浏览、搜索技能。点击一个技能可以查看其详细描述、作者、版本等信息。确认想安装后点击安装按钮skill-manager会自动完成下载、校验并将其放入托管仓库同时为你创建符号链接。安装完成后你可以立刻在“技能”工作区看到它并配置它在哪些工具中启用。市场使用的注意事项网络要求浏览和安装需要网络连接。安全审查虽然市场有审核但安装社区技能仍需保持警惕。建议优先选择星标多、作者信誉好的技能。版本更新市场中的技能更新后你可以在“技能”工作区对已托管的技能执行“从源更新”操作来获取新版本。5. 高级用法与故障排查5.1 技能仓库的物理结构探秘了解skill-manager在后台如何组织文件有助于你在出现问题时进行手动排查或高级操作。所有应用数据都存放在~/Library/Application Support/skill-manager/目录下。~/Library/Application Support/skill-manager/ ├── shared/ # 核心托管技能仓库 │ ├── skill-a/ # 每个托管技能一个独立文件夹 │ │ ├── skill.json # 技能元数据 │ │ ├── main.py # 技能实现代码等 │ │ └── ... │ └── skill-b/ │ └── ... ├── marketplace/ # 市场技能包缓存 │ └── (缓存文件) └── settings.json # 应用配置文件当你执行“纳入管理”时技能文件夹会从~/.cursor/skills/skill-a移动到~/Library/.../shared/skill-a。然后在~/.cursor/skills/下创建一个名为skill-a的符号链接指向上述新位置。你可以使用终端命令验证# 进入Cursor技能目录 cd ~/.cursor/skills # 列出文件并查看详细信息符号链接会显示为 lrwxr-xr-x 并以 - 指向实际路径 ls -la # 如果看到类似这样就是符号链接 # lrwxr-xr-x 1 user staff 65B Apr 10 10:00 skill-a - /Users/user/Library/Application Support/skill-manager/shared/skill-a5.2 常见问题与解决方案问题一启动skill-manager start后浏览器没有自动打开或者打开后无法连接。排查首先检查应用是否真的在运行。在终端执行ps aux | grep skill-manager查看相关进程。解决尝试手动访问默认的前端地址http://127.0.0.1:5173和后端健康检查地址http://127.0.0.1:8000/api/health。如果后端健康检查不通可能是端口冲突或启动失败。可以尝试重启电脑或者用skill-manager start --port 8001指定另一个端口启动后端但注意前端可能仍需配置对应端口。问题二技能列表为空或者检测不到我安装的AI工具。排查确认你是否在首次启动时授予了完整的磁盘访问权限系统设置 - 隐私与安全性 - 文件与文件夹。确认你使用的AI工具是skill-manager官方支持的版本并且已正确安装。检查该AI工具的技能目录是否存在且不为空。例如运行ls -la ~/.cursor/skills查看。解决如果目录存在但skill-manager不识别尝试使用上文提到的环境变量SKILL_MANAGER_XXX_ROOT手动指定路径。问题三执行“纳入管理”或“删除”操作失败。排查这通常是由于文件权限不足或路径被其他进程锁定比如AI工具本身正在读取技能文件。解决关闭所有正在运行的AI编程助手Cursor、Claude Code等。在终端中尝试手动对目标目录执行简单的读写操作如touch test然后rm test看是否有权限错误。如果问题依旧可以尝试以管理员权限运行skill-manager不推荐长期使用或者检查目录的所有者是否正确。问题四市场无法加载提示“Marketplace is temporarily unavailable”。排查这是网络连接问题。可能是你的网络环境无法访问skills.sh或相关的GitHub资源。解决检查你的网络连接是否正常。尝试使用命令行工具curl测试连通性curl -I https://skills.sh。如果网络正常但问题持续可能是skill-manager的本地缓存损坏。可以尝试退出应用然后删除市场缓存目录~/Library/Application Support/skill-manager/marketplace注意这会清空本地缓存重新加载可能较慢再重启应用。5.3 从管理状态回退停止管理如果你后悔将某个技能纳入统一管理skill-manager提供了“停止管理”选项。这个操作会在skill-manager的共享仓库中删除该技能的托管副本。删除所有AI工具技能目录下指向它的符号链接。但请注意它不会将技能文件恢复回各个AI工具的原目录。也就是说这个操作后所有AI工具都将失去这个技能。如果你想恢复需要重新通过各个AI工具的原生方式或skill-manager的市场重新安装。因此“停止管理”是一个需要谨慎使用的破坏性操作通常在你确定不再需要某个技能时使用。6. 开发模式与项目贡献6.1 本地开发环境搭建如果你想深入了解skill-manager的运作机制甚至为其贡献代码可以搭建本地开发环境。项目采用前后端分离架构前端ViteReact/TypeScript后端Python FastAPI并提供了便捷的脚本。# 1. 克隆仓库 git clone https://github.com/mode-io/skill-manager.git cd skill-manager # 2. 运行一键开发环境安装脚本 # 这个脚本会创建Python虚拟环境安装前后端依赖 scripts/install-dev.sh # 3. 启动完整的开发服务器前端后端在一个终端运行 scripts/start-dev.sh运行start-dev.sh后开发服务器会启动并自动打开浏览器。这是最方便的调试方式。如果你需要更传统的、前后端分离的调试例如需要前端热重载可以使用# 终端1启动前端开发服务器 npm run dev # 终端2启动后端开发服务器 npm run dev:backend6.2 核心工作流程与代码导读对于开发者理解以下几个关键流程有助于定位代码技能发现流程后端启动时会读取配置遍历每个支持的Harness的根目录解析每个技能文件夹内的skill.json构建出技能清单。相关代码主要在后端的harness_detector和skill_loader模块。纳入管理流程当用户在前端点击“纳入管理”后端会接收到技能ID和目标Harness列表。核心逻辑在skill_manager服务中移动文件、创建符号链接、更新内部数据库状态。文件操作部分使用了Python的shutil和os模块符号链接使用os.symlink。状态同步前端通过WebSocket或轮询API与后端保持通信实时反映技能状态的变化。状态管理通常集中在React的Context或状态管理库中。6.3 测试与构建项目包含了较为完善的测试套件在提交代码前运行测试是个好习惯。# 运行前端单元测试 npm test # 运行后端测试假设在项目根目录 bash scripts/test_backend.sh # 运行端到端E2E测试需要先启动开发服务器 npx playwright test # 构建生产版本的前端静态文件 npm run build # 构建并打包可分发版本参考项目CI脚本 scripts/ci_validate.sh7. 总结与未来展望使用skill-manager几个月下来它已经成了我开发环境里一个不可或缺的基础设施。最大的感受就是“清爽”和“可控”。我再也不用担心Cursor里禁用的技能在Claude Code里突然跳出来也不用在多个文件夹之间来回切换去手动更新一个公共组件。所有关于AI技能的决策现在都可以在一个地方冷静、清晰地完成。这个项目的设计体现了对开发者工作流的深刻理解。它没有尝试做一个大而全的云端平台而是坚定地选择了“本地优先”这保证了速度、隐私和可靠性。符号链接的方案虽然简单但却是解决这个特定问题最优雅、最Unix哲学的方式。从项目路线图来看skill-manager还在积极发展中。我期待未来能看到更多AI工具的支持比如一些新兴的IDE插件市场功能的进一步丰富如用户评分、技能分类以及或许更强大的技能依赖管理和冲突解决机制。如果你也是一个多AI工具的重度用户正在被散乱的技能文件所困扰我强烈建议你花十分钟试试skill-manager。它的安装和上手成本极低但带来的效率提升和心智负担减轻是立竿见影的。就像整理好了杂乱的书桌你会立刻感到一种秩序带来的愉悦和高效。