Skills Hub 详细部署教程

Skills Hub 是一款跨平台的桌面应用程序，用于集中管理 AI Agent Skills，并能将它们一键同步到多种 AI 编码工具（如 Cursor、Claude Code、Codex 等）的全局或项目级技能目录中。其核心理念是 “一次安装，随处同步”，极大地简化了技能管理流程。

本教程将指导你完成从下载安装到配置使用的全过程。

一、安装前准备

在开始安装前，请根据你的使用场景确认以下条件：

1. 系统要求

组件 版本/要求
操作系统 macOS (已验证), Windows, Linux (预期支持)
Node.js 18+ (推荐 20+)
Rust 稳定版工具链 (仅从源码构建时需要)
包管理器 npm, Homebrew (macOS/Linux) 或 Scoop (Windows)

2. Tauri 系统依赖（仅从源码构建）

Tauri 应用需要特定平台依赖，请参考 Tauri 官方文档 进行安装。

二、安装方式

方式一：使用 Homebrew (macOS/Linux)

这是最便捷的安装方式，适合 macOS 和 Linux 用户。

安装 CLI 工具：

1
2
brew tap PotatoDog1669/skillshub
brew install skills-hub

验证安装：skills-hub --version

安装桌面应用 (macOS)：

1
2
brew tap PotatoDog1669/skillshub
brew install --cask skills-hub

方式二：使用 npm

适合 Node.js 开发者，或在无法使用 Homebrew 的环境下安装。

全局安装 CLI：

1
2
3
npm install -g skills-hub-cli
# 或者使用特定包
npm install -g @potatodog1669/skills-hub

这种方式提供 skills-hub 命令，用于管理技能 。

临时使用 (不全局安装)：

1
npx @potatodog1669/skills-hub --help

方式三：使用 Scoop (Windows)

适合 Windows 用户，提供便捷的命令行安装体验。

1
scoop install llmfit

注：此命令来自另一个项目 llmfit，仅作示例。对于 Skills Hub，请关注其官方发布的 Windows 安装包或使用 npm 方式。

方式四：下载预编译二进制文件 (所有平台)

直接下载图形化桌面应用：

  1. 访问项目的 GitHub Releases 页面 。
  2. 根据你的操作系统下载对应的安装包：
    • macOS: skills-hub_X.Y.Z_macos_aarch64.dmg (Apple Silicon) 或 ...x64.dmg (Intel) 。
    • Windows: .msi 或 .exe 安装程序 。
    • Linux: .deb 或 .AppImage 包 。
  3. 双击下载的文件，按提示完成安装。

三、从源码构建 (开发者选项)

如果你希望体验最新特性或进行二次开发，可以自行构建。

1. 克隆仓库并安装依赖

1
2
3
git clone https://github.com/PotatoDog1669/skills-hub.git
cd skills-hub
npm ci

2. 启动开发版本

1
npm run tauri:dev

3. 构建生产版本

根据目标平台执行对应的构建命令 ：

1
2
3
4
5
6
7
8
# macOS (通用 DMG)
npm run tauri:build:mac:universal:dmg

# Windows (MSI 安装程序)
npm run tauri:build:win:msi

# Linux (Debian 包)
npm run tauri:build:linux:deb

构建产物将输出到 src-tauri/target/release/bundle/ 目录下 。

四、基本使用与配置

1. 初始设置

  • 启动桌面应用，首次打开会提示设置中央仓库路径（默认为 ~/.skillshub），所有技能将统一存储在此。
  • 在 设置 (Settings) 中，你可以配置：
    • 语言 (Language)：界面语言（中文/英文）。
    • GitHub Token：用于访问私有仓库或提高 API 速率限制。
    • 网络代理 (Proxy)：如果网络环境特殊，可配置代理 。

2. 管理工具 (Tools)

在 管理中心 (Management Center) 的 “工具” 选项卡中，你会看到 Skills Hub 内置支持的 47 种 AI 工具列表。例如：

  • Cursor: ~/.cursor/skills (全局) 和 项目/.agents/skills (项目)
  • Claude Code: ~/.claude/skills (全局) 和 项目/.claude/skills (项目)
  • Codex: ~/.codex/skills (全局) 和 项目/.agents/skills (项目)

对于你电脑上已安装并检测到的工具，可以直接在此界面启用或禁用同步目标。

3. 添加与管理技能 (My Skills)

这是核心工作流，有以下几种方式添加技能：

  • 通过 “探索 (Explore)” 安装：在 “探索” 页面，你可以浏览精选技能或在线搜索。点击 “安装” 后，可为该技能指定标签、安装范围（全局/项目）和目标工具。
  • 手动添加：支持从本地文件夹或 Git 仓库 URL 添加技能。在安装前，同样可以配置标签、范围和目标工具。
  • 批量管理：在 “我的技能 (My Skills)” 页面，你可以通过卡片或列表视图，对已安装的技能进行批量启用/禁用、删除、更新标签或更改同步目标。

4. 同步机制

Skills Hub 默认优先使用符号链接 (symlink/junction) 方式进行同步，以实现”一处存储，多处引用”。当目标工具不支持符号链接时（如 Cursor），系统会自动回退到复制模式 。所有同步操作都基于统一的中央仓库，确保一致性。

五、高级功能

1. 自动更新

在 “更新” 部分，你可以注册系统级定时任务，即使应用未开启，也能按计划自动更新 Git 和本地来源的技能，并同步到已配置的工具。

2. 技能发现与导入

当 Skills Hub 在你的工具目录（如 .cursor/skills）中发现可导入的技能时，会在界面顶部显示 “发现 (Discovery)” 横幅。点击可查看并一键将这些技能纳入中央仓库统一管理 。

3. 命令行界面 (CLI)

对于习惯命令行的用户，Skills Hub 也提供了强大的 CLI：

1
2
3
4
5
6
7
8
9
10
11
# 列出已安装的技能（项目级）
skills-hub list

# 从 Git 仓库添加技能
skills-hub add https://github.com/user/repo --skill skill-name

# 同步所有已启用的技能
skills-hub sync --all

# 同步到特定工具
skills-hub sync --target claude

更多 CLI 命令（如 remove, import, provider 等）可通过 skills-hub --help 查看 。

六、常见问题

1. macOS 提示 “无法验证开发者” (Gatekeeper)

解决方法：在终端执行以下命令移除隔离属性：

1
xattr -cr "/Applications/Skills Hub.app"

2. 为什么同步有时是复制而非符号链接？

原因：目标工具不支持符号链接（如 Cursor），或当前系统（尤其 Windows）的权限限制。
结果：系统会自动降级为复制模式，保证功能正常 。

3. 技能已禁用，但文件还在吗？

是的。禁用技能仅移除了工具目录下的同步副本，中央仓库 (~/.skillshub) 中的技能源文件和配置会保留，方便以后重新启用 。

4. 如何自定义工具目录？

在 管理中心 > 工具 中，你可以添加 “自定义工具”，并手动指定其技能目录路径。这适用于 Skills Hub 内置列表未覆盖的工具 。

通过上述步骤，你应该能成功部署并开始使用 Skills Hub 来统一管理你的 AI 技能资产了。对于更详细的开发文档或贡献指南，可以查阅项目根目录下的 CONTRIBUTING.md 文件。