cc-switch Skills 管理实战：从发现、安装到更新检测与仓库管理

本篇指南基于 cc-switch（跨平台 Claude Code / Codex / OpenCode / OpenClaw / Grok Build / Hermes 一体化桌面助手）官方用户手册的 Skills 章节编写。Skills 是 cc-switch 中管理 AI 工具"可复用能力扩展"的核心功能：你将学会如何在应用内发现、搜索、安装、卸载和更新 Skills，如何自定义 Skill 仓库来源、使用 skills.sh 公共注册表，以及切换 Skills 的源存储位置。结合后端源码（skill.rs、commands/skill.rs），本文还会讲清 SSOT（单一事实源）统一安装架构与 SHA-256 更新检测机制的底层实现。

什么是 Skills，支持哪些应用

Skills 是可复用的能力扩展，为 AI 工具在特定领域提供专门能力。每个 Skill 以一个文件夹形式存在，通常包含：

• Prompt 模板（如 SKILL.md，从源码看展示名称与描述即从 SKILL.md 解析，见 DiscoverableSkill 结构体）
• 工具定义
• 示例代码

Skills 支持以下五个应用：

• Claude Code
• Codex
• Gemini CLI
• OpenCode
• Hermes

当顶部导航栏中选中的应用支持 Skills 时，点击 Skills 按钮即可进入 Skills 页面。

发现 Skills（Discover）

预配置仓库

cc-switch 出厂预配置了以下 GitHub 仓库（源码 SkillStore::default() 中还包含 cexll/myclaude 与 JimLiu/baoyu-skills 两个社区仓库）：

仓库	说明
Anthropic Official	Anthropic 官方提供的 skills
ComposioHQ	社区维护的技能集合
Community Picks	精选高质量技能

搜索与筛选

cc-switch 提供强大的搜索和筛选功能（实现见 SkillsPage.tsx）：

搜索框

• 按技能名称搜索
• 按技能描述搜索
• 按目录名称搜索
• 实时过滤，输入即刷新结果

状态筛选

使用下拉菜单按安装状态过滤：

选项	说明
All	显示所有技能
Installed	只显示已安装技能
Not Installed	只显示未安装技能

组合使用

搜索和筛选可以组合使用：

1. 先选择 "Installed" 筛选
2. 再输入关键词搜索
3. 结果区显示匹配数量

刷新列表

点击 Refresh 按钮会重新扫描各仓库，拉取最新技能列表。从源码看，该操作会触发 discover_available_skills 命令，按数据库中的仓库配置重新拉取发现列表。

安装 Skills

操作步骤

1. 找到要安装的技能卡片
2. 点击 Install 按钮
3. 等待安装完成

安装目录

应用	安装目录
Claude	~/.claude/skills/
Codex	~/.codex/skills/
Gemini	~/.gemini/skills/
OpenCode	~/.config/opencode/skills/
Hermes	~/.hermes/skills/

安装内容与 SSOT 架构

安装过程并非简单地"复制一份到应用目录"。从 v3.10.0 起，cc-switch 采用统一 SSOT（单一事实源）架构（见 skill.rs 服务层头部注释）：

• 技能本体先下载到 SSOT 目录 ~/.cc-switch/skills/；
• 再按你勾选的应用，同步到各应用的技能目录（Claude、Codex、Gemini、OpenCode、Hermes）；
• 数据库（见 database/dao/skills.rs）记录安装记录和每应用的启用状态。

同步方式支持三种策略（SyncMethod 枚举）：

• Auto（默认）：优先 symlink，失败时回退到 copy；
• Symlink：符号链接，节省磁盘空间；
• Copy：文件复制，兼容模式。

因此各应用目录中看到的结构形如：

~/.claude/skills/
└── skill-name/
    ├── README.md
    ├── prompt.md
    └── tools/
        └── ...

前端安装入口为 install_skill_unified 命令：传入技能信息与当前应用，安装完成后默认启用当前应用。

卸载 Skills 与备份恢复

卸载步骤

1. 找到已安装的技能卡片
2. 点击 Uninstall 按钮
3. 确认卸载

卸载的实际效果

卸载由 uninstall_skill_unified 执行，效果包括：

• 自动备份：删除前，技能被备份到 ~/.cc-switch/skill-backups/（备份目录定义见 SkillService 备份目录）；
• 从所有应用目录（Claude、Codex、Gemini、OpenCode、Hermes）移除该技能；
• 从 SSOT 目录（~/.cc-switch/skills/）移除该技能；
• 从数据库中删除该技能记录。

从备份恢复

如果需要恢复之前卸载的技能：

1. 打开 Skills 页面
2. 点击 Restore from Backup 按钮
3. 在列表中选择要恢复的备份（显示技能名与备份日期）
4. 技能被恢复，并对当前应用启用

删除备份

要移除旧的技能备份：

1. 在恢复对话框中找到要删除的备份
2. 点击该备份条目旁的 Delete 按钮
3. 确认删除——此操作不可恢复

仓库管理（Repository Management）

打开仓库管理

点击页面顶部的 Repository Management 按钮打开管理对话框。

添加自定义仓库

1. 点击 Add Repository
2. 填写仓库信息：
   • Owner：GitHub 用户名或组织名
   • Name：仓库名
   • Branch：分支名（默认 main）
   • Subdirectory：包含技能的子目录（可选）
3. 点击 Add

仓库格式

https://github.com/{owner}/{name}/tree/{branch}/{subdirectory}

示例：

Owner: anthropics
Name: claude-skills
Branch: main
Subdirectory: skills

对应数据结构为 SkillRepo：owner、name、branch（默认 "main"）与 enabled 四个字段。

删除仓库

1. 在仓库列表中找到目标仓库
2. 点击 Delete 按钮
3. 确认删除

删除仓库后，其技能不会从列表中消失，只是不能再被更新。

公共注册表搜索（skills.sh）

v3.13.0 集成了 skills.sh 公共注册表搜索，可以直接在 cc-switch 内发现社区技能：

1. 点击 Repository Management 按钮打开对话框
2. 使用对话框内的 skills.sh Search 输入框
3. 输入关键词，结果实时过滤
4. 点击目标技能，即可快速将其加入仓库列表

从前端实现看，skills.sh 搜索结果按 20 条分页累积加载（SkillsPage.tsx 中的 SKILLSSH_PAGE_SIZE）；后端对应 search_skills_sh 命令。v3.13.0 同时修复了 skills.sh 的坏链接与空描述处理，社区技能的元数据显示更可靠。

技能卡片信息

每张技能卡片展示：

信息	说明
Name	技能名称
Description	功能描述
Source	来源仓库
Status	已安装 / 未安装

技能更新：SHA-256 内容哈希检测

从 v3.13.0 开始，Skills 支持自动更新检测与批量更新——不再需要"先卸载再安装"。

更新检测机制

cc-switch 使用 SHA-256 内容哈希比较已安装技能与远程仓库版本：只要远端有任何内容变化，对应的本地技能卡片就会自动出现 "Update available" 指示。

源码实现见 compute_dir_hash：递归遍历目录下所有非隐藏文件，按相对路径字典序排列，将 相对路径\0内容\0 逐文件喂给同一个 SHA-256 hasher，得到整棵目录树的稳定指纹。由于哈希基于内容而非时间戳或版本号，任何文件内容变化都能被捕获。更新检测由 check_skill_updates 命令触发，单个技能更新走 update_skill。

单个更新

对某个有可用更新的技能：

1. 在 Skills 面板中找到带更新指示的技能卡片
2. 点击卡片上的 Update 按钮
3. 等待下载完成——状态自动刷新

全部更新（Update All）

多个技能需要更新时：

1. 点击 Skills 面板顶部的 Update All 按钮（出现时带滑入动画）
2. cc-switch 批量下载所有待更新技能
3. 完成后面板自动刷新，更新指示消失

提示：定期点击 Refresh 按钮触发远程扫描，保持更新检测处于最新状态。

源存储位置切换（Storage Location Switch）

从 v3.13.0 开始，技能的源存储位置可以在两个位置之间切换（对应 SkillStorageLocation 枚举 与 settings.rs 中的 skill_storage_location 设置）：

位置	说明
CC Switch 内置	默认位置 ~/.cc-switch/skills/，由 cc-switch 管理
~/.agents/skills	符合社区 agent 工具规范的共享目录，更适合跨工具协作

如何切换

在 Skills 面板的设置或管理菜单中选择目标存储位置。切换不会丢失技能状态——cc-switch 会将已有技能平滑迁移到新位置。

⚠️ 区分：这里的"Storage Location Switch"管理的是技能的源存储；而 1.5 个性化设置 → Skill Sync Method 控制的是技能分发到各应用目录的方式（symlink 还是 copy）。两者配合工作。

故障排查

技能列表为空

可能原因：

• 网络问题导致无法访问 GitHub
• 仓库配置不正确

解决方案：

• 检查网络连接
• 点击 Refresh 重试
• 核对仓库配置

安装失败

可能原因：

• 网络问题
• 磁盘空间不足
• 权限问题

解决方案：

• 检查网络连接
• 检查磁盘空间
• 检查目录权限

更新按钮不显示

可能原因：

• 远程仓库没有新内容
• cc-switch 尚未完成最近一次扫描

解决方案：

• 点击 Refresh 重新扫描
• 确认仓库配置指向正确的分支与路径

小结

cc-switch 的 Skills 管理围绕"SSOT + 多应用分发"架构展开：技能统一存放在 ~/.cc-switch/skills/（或切换到 ~/.agents/skills），按 Auto/Symlink/Copy 策略同步到 Claude Code、Codex、Gemini CLI、OpenCode、Hermes 五个应用的技能目录，安装记录与各应用启用状态落在本地数据库。v3.13.0 之后，SHA-256 内容哈希驱动的更新检测、批量更新、skills.sh 公共注册表搜索与卸载前自动备份（~/.cc-switch/skill-backups/）共同构成了一套完整的技能生命周期管理。关键实现可进一步参阅 src-tauri/src/services/skill.rs、src-tauri/src/commands/skill.rs、src/components/skills/SkillsPage.tsx 与测试 tests/components/SkillsPageInstall.test.tsx、tests/hooks/useImportSkillsFromApps.test.tsx。