CC Switch Skills 技能管理详解：跨应用安装、SSOT 同步、哈希更新检测与仓库管理实战指南

Skills 是 CC Switch 中让 Claude Code、Codex、Gemini CLI、OpenCode、Hermes 等 AI 工具获得特定领域专业能力的可复用扩展机制。本文以 CC Switch 用户手册「3.3 Skills 技能管理」章节为核心，完整覆盖技能发现、搜索过滤、安装、卸载备份、仓库管理、自动更新检测与存储位置切换等全部操作路径，并结合 src-tauri/src/services/skill.rs 与 src-tauri/src/commands/skill.rs 的源码实现，讲清「SSOT（单一事实源）+ 数据库记录 + 应用目录同步」的统一管理架构，读完你可以独立完成从发现技能到多应用分发、从卸载恢复到批量更新的全套操作。

一、Skills 是什么：技能以文件夹形式存在

Skills 是可复用的能力扩展，让 AI 工具获得特定领域的专业能力。每个技能本质上是一个文件夹，通常包含：

• 提示词模板
• 工具定义
• 示例代码

从源码看，CC Switch 对技能元数据的解析以技能目录中的 SKILL.md 为中心：src-tauri/src/services/skill.rs 中定义了 SkillMetadata 结构（name 与 description 两个字段，均为可选），用于从 SKILL.md 解析出技能显示名称与描述。这也是为什么技能卡片能展示名称和描述——它们不是硬编码的，而是安装/发现时从技能文件本身提取的。

支持的应用与安装目录

Skills 功能支持五种应用：

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

当当前应用支持 Skills 时，点击顶部导航栏的 Skills 按钮即可打开技能管理页面。

上表对应的是源码中 SkillService::get_app_skills_dir 的默认路径映射。值得注意的是，从源码结构看，该函数对每个应用都支持目录覆盖：如果用户在 CC Switch 设置中为某应用配置了自定义配置目录（override dir），技能实际会安装到该自定义目录下的 skills/ 子目录，而不是硬编码的主目录路径。此外源码中的映射还覆盖了 Claude Desktop、Grok Build、OpenClaw、Pi 等更多应用类型，说明后端的目录映射比文档列出的五个应用更宽，前端页面则按当前应用是否支持 Skills 来决定展示。

二、发现技能：预配置仓库与搜索过滤

预配置仓库

CC Switch 预配置了以下 GitHub 仓库：

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

文档中的「社区精选」是概略说法，src-tauri/src/services/skill.rs 中 SkillStore 的默认实现给出了精确的四个仓库坐标，每个仓库都带 branch 和启用状态：

Owner	仓库名	分支
anthropics	skills	main
ComposioHQ	awesome-claude-skills	master
cexll	myclaude	master
JimLiu	baoyu-skills	main

仓库列表持久化在数据库中，由 get_skill_repos / save_skill_repo / delete_skill_repo 这组命令读写，这也是「仓库管理」功能的前后端桥梁。

搜索过滤

CC Switch 提供强大的搜索和过滤功能。

搜索框 支持：

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

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

选项	说明
全部	显示所有技能
已安装	仅显示已安装的技能
未安装	仅显示未安装的技能

组合使用：搜索和过滤可以组合——先选择「已安装」过滤，再输入关键词搜索，界面会显示匹配数量。

「已安装」状态的判定来自数据库中的 InstalledSkill 记录（通过 get_installed_skills 命令获取），而非简单检查磁盘目录，因此卸载/启用状态与列表展示始终一致。

刷新列表

点击「刷新」按钮重新扫描仓库，获取最新技能。刷新触发的是 discover_available_skills 命令：后端读取数据库中的全部启用仓库，逐个下载仓库归档并解析其中的技能目录，返回 DiscoverableSkill 列表。每个条目的唯一标识 key 采用 owner/name:directory 格式（见 DiscoverableSkill 结构定义），同时携带 repo_owner、repo_name、repo_branch 与 readme_url 等字段，供安装和「查看文档」使用。

三、安装技能：从下载到三处落位

操作步骤

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

安装位置

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

安装内容与底层流程

安装会将技能文件夹复制到本地：

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

从源码看，SkillService::install 的执行流程是「下载 → 落 SSOT → 写库 → 同步到应用目录」四步：

1. 安全校验：先用 sanitize_skill_source_path 校验源目录是安全的相对路径，安装目录名取路径最后一段，避免在 SSOT 中产生多级目录或路径穿越；
2. 下载仓库归档：调用 download_repo 拉取整个仓库压缩包，外层套了 60 秒超时（超时抛出 DOWNLOAD_TIMEOUT 错误并提示检查网络）；如果配置的分支下载失败，会自动回退分支并记录日志；
3. 写入 SSOT：将解析出的技能源目录复制到 SSOT 目录（默认 ~/.cc-switch/skills/），随后计算 SHA-256 内容哈希 存入 InstalledSkill.content_hash——这个哈希就是后面「更新检测」的本地基线；
4. 写数据库并同步：把 InstalledSkill（含 id、name、description、directory、仓库坐标、apps 启用状态、content_hash 等）写入数据库，再按启用的应用把技能物化到各应用的 skills/ 目录。

源码中对第三方归档还设置了多层安全上限：解压条目数上限 10,000 条、解压后总字节数上限 512 MiB、下载体上限 128 MiB（见 src-tauri/src/services/skill.rs 的常量定义与注释），用于抵御恶意仓库的压缩炸弹。

另外，若目标技能名已被另一个仓库的同名技能占用，安装会报 SKILL_DIRECTORY_CONFLICT 错误并提示先卸载；若是同一仓库重复安装，则直接复用已有安装并刷新当前应用的启用状态（见 reuse_existing_install）。

四、卸载技能与备份恢复

操作步骤

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

卸载效果

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

这与 SkillService::uninstall 的注释流程完全一致：从所有应用目录删除 → 从 SSOT 删除 → 从数据库删除，而备份目录由 get_backup_dir 定位到 ~/.cc-switch/skill-backups/。源码中还有一个 SKILL_BACKUP_RETAIN_COUNT = 20 的常量，意味着备份会保留最近若干份（上限 20），防止备份目录无限膨胀。

从备份恢复

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

1. 打开 Skills 页面
2. 点击 从备份恢复 按钮
3. 从列表中选择要恢复的备份（显示技能名称和备份日期）
4. 技能将被恢复并为当前应用启用

对应的后端命令是 get_skill_backups（列出备份）与 restore_skill_backup（恢复并针对当前应用启用）。

删除备份

如需删除旧的技能备份：

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

对应 delete_skill_backup 命令。

五、仓库管理：接入自己的技能源

打开仓库管理

点击页面顶部的「仓库管理」按钮。

添加自定义仓库

1. 点击「添加仓库」
2. 填写仓库信息：
   • Owner：GitHub 用户名或组织名
   • Name：仓库名称
   • Branch：分支名（默认 main）
   • Subdirectory：技能所在子目录（可选）
3. 点击「添加」

仓库格式

仓库地址由四个字段拼装：

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

示例：

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

添加仓库时会先经过 validate_repo_ref 校验：由于 owner/name/branch 会被拼进归档下载 URL，非法值在入库前即被拒绝，避免脏数据沉淀到仓库表。

删除仓库

1. 在仓库列表中找到要删除的仓库
2. 点击「删除」按钮
3. 确认删除

删除仓库后，该仓库的技能不会从列表中消失，但无法再更新。这符合后端设计：已安装技能记录保存在数据库中（InstalledSkill 自带仓库坐标），仓库列表只驱动「发现/扫描」环节，删除仓库只影响后续扫描来源。

六、技能卡片信息

每个技能卡片显示：

信息	说明
名称	技能名称
描述	功能说明
来源	所属仓库
状态	已安装 / 未安装

这些字段直接映射到后端的 Skill / DiscoverableSkill 结构：name、description（从 SKILL.md 解析）、repo_owner + repo_name（来源）、installed（安装状态），前端组件为 src/components/skills/SkillCard.tsx 与 src/components/skills/UnifiedSkillsPanel.tsx。

七、技能更新：基于 SHA-256 内容哈希的检测机制

v3.13.0 起，Skills 支持自动更新检测和批量更新，不再需要卸载后重新安装。

更新检测原理

CC Switch 基于 SHA-256 内容哈希比较本地已安装的 skill 与远端仓库版本。只要远端有任何文件内容变化，本地对应的 skill 卡片会自动显示「有新版本」标识。

源码层面，安装时已把技能目录的 content_hash 写入数据库（见 安装流程第 914-918 行）；check_skill_updates 命令重新扫描远端仓库、重新计算哈希，返回 SkillUpdateInfo 列表，每个条目包含 current_hash（本地）与 remote_hash（远端），前端据此渲染更新标识。哈希比较的是整个技能目录的内容，因此仓库中任何文件变更（提示词、工具定义、示例代码）都会被捕获。

单项更新

对于有新版本的 skill：

1. 在 Skills 面板找到带更新标识的 skill 卡片
2. 点击卡片上的 更新 按钮
3. 等待下载完成，状态自动刷新

对应 update_skill 命令，更新完成后本地 content_hash 会被刷新。

全部更新

当有多个 skill 需要更新时：

1. 点击 Skills 面板顶部的 全部更新 按钮（出现时带滑入动画）
2. CC Switch 会批量下载所有需要更新的 skill
3. 完成后面板自动刷新，更新标识消失

建议：定期点击「刷新」按钮触发一次远端扫描，确保更新检测结果最新。

八、存储位置切换：SSOT 与社区共享目录

v3.13.0 起，Skills 的源存储位置（SSOT）可以在两个位置之间切换：

位置	说明
CC Switch 内置存储	默认位置 ~/.cc-switch/skills/，由 CC Switch 统一管理
~/.agents/skills	符合社区 agent 工具约定的共享目录，便于与其他工具协同

这与 SkillStorageLocation 枚举 一一对应：CcSwitch（默认）与 Unified（~/.agents/skills/）。get_ssot_dir 会按当前设置返回对应目录并自动创建。

切换方式

在 Skills 面板的设置或管理菜单中选择目标存储位置。切换过程不会丢失 skill 状态——CC Switch 会平滑迁移现有 skill 到新位置。后端由 migrate_skill_storage 命令执行迁移，返回 MigrationResult（含迁移数量、跳过数量与错误列表），保证迁移结果可核查。

区别提示：本节的「存储位置切换」管理的是 skill 的源存储。而 1.5 个性化配置 → Skills 同步方式 管理的是 skill 如何分发到各应用目录（软链接 vs 复制），两者配合使用。

对应源码中的 SyncMethod 枚举：Auto（默认，优先 symlink、失败回退 copy）、Symlink（推荐，节省磁盘空间）、Copy（兼容模式）。也就是说「存在哪」由本节控制，「如何投送到各应用」由同步方式控制。

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

v3.13.0 集成了 skills.sh 公共注册表搜索，让你直接在 CC Switch 内发现社区 skill。

使用步骤

1. 点击「仓库管理」按钮打开对话框
2. 在对话框内使用 skills.sh 搜索 输入框
3. 输入关键词实时筛选结果
4. 点击目标 skill 即可快速添加到你的仓库列表

v3.13.0 还修复了 skills.sh 链接失效和空描述的兼容处理，社区 skill 的元数据显示更稳定。

后端实现见 search_skills_sh 命令与服务层的 SkillService::search_skills_sh：请求 skills.sh 的搜索 API，返回条目包含 name、installs（安装量）、source（来源仓库）与推导出的 readme_url。从源码结构看，其 API 响应字段命名并不统一（searchType 为 camelCase、duration_ms 为 snake_case），因此反序列化采用逐字段 rename 而非全局重命名规则（见 src-tauri/src/services/skill.rs 的注释），这也印证了文档提到的「兼容处理」。

十、常见问题

技能列表为空

可能原因：

• 网络问题，无法访问 GitHub
• 仓库配置错误

解决方法：

• 检查网络连接
• 点击「刷新」重试
• 检查仓库配置

安装失败

可能原因：

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

解决方法：

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

结合源码可以进一步定位：下载超时会给出 DOWNLOAD_TIMEOUT（60 秒）、目录名非法会给出 INVALID_SKILL_DIRECTORY、技能目录在仓库中不存在会给出 SKILL_DIR_NOT_FOUND 等结构化错误码（由 src-tauri/src/error.rs 中的 format_skill_error 生成），前端提示中附带的错误码可以帮助区分是网络、内容还是权限问题。

更新按钮不出现

可能原因：

• 远端仓库没有新内容
• CC Switch 尚未完成最新扫描

解决方法：

• 点击「刷新」重新扫描
• 确认仓库配置指向正确的分支和路径

十一、相关源码与测试位置

若希望继续深入 Skills 功能的实现细节，可以从以下仓库路径入手：

类别	路径	说明
服务层	src-tauri/src/services/skill.rs	安装/卸载/更新/迁移/备份/skills.sh 搜索的核心逻辑（约 6000 行，含大量安全边界与并发锁设计）
命令层	src-tauri/src/commands/skill.rs	前端调用的全部 Tauri 命令入口
前端页面	src/components/skills/SkillsPage.tsx	Skills 页面容器
前端面板	src/components/skills/UnifiedSkillsPanel.tsx、RepoManagerPanel.tsx、SkillCard.tsx	统一技能面板、仓库管理对话框、技能卡片
状态 Hook	src/hooks/useSkills.ts	技能列表状态与批量操作
存储位置设置	src/components/settings/SkillStorageLocationSettings.tsx	SSOT 存储位置切换入口
测试	tests/components/SkillsPageInstall.test.tsx、tests/hooks/useImportSkillsFromApps.test.tsx、tests/hooks/useSkillsBulkToggle.test.tsx	安装、从应用导入、批量启用等行为的测试用例

整体来看，CC Switch 的 Skills 管理采用「一份源（SSOT）+ 一份账（数据库）+ N 份投影（各应用目录）」的架构：安装、更新只触碰 SSOT 与数据库，再按启用状态投影到各应用；卸载、备份、恢复、迁移全部围绕这三层展开，这也是它能同时服务多个 AI 应用而互不冲突的根本原因。