# 3.3 Skills 技能管理

## 功能说明

Skills 是可复用的能力扩展，让 AI 工具获得特定领域的专业能力。

技能以文件夹形式存在，包含：

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

## 支持的应用

Skills 功能支持所有四种应用：

- **Claude Code**
- **Codex**
- **Gemini CLI**
- **OpenCode**

## 打开 Skills 页面

点击顶部导航栏的 **Skills** 按钮。

> 注意：Skills 按钮在所有应用模式下均可见。

## 页面概览

![image-20260108010253926](../../assets/image-20260108010253926.png)

## 发现技能

### 预配置仓库

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

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

![image-20260108010308060](../../assets/image-20260108010308060.png)

### 搜索过滤

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

#### 搜索框

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

#### 状态过滤

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

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

![image-20260108010324583](../../assets/image-20260108010324583.png)

#### 组合使用

搜索和过滤可以组合使用：

- 先选择「已安装」过滤
- 再输入关键词搜索
- 结果显示匹配数量

### 刷新列表

点击「刷新」按钮重新扫描仓库，获取最新技能。

## 安装技能

### 操作步骤

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

### 安装位置

| 应用     | 安装目录              |
| -------- | --------------------- |
| Claude   | `~/.claude/skills/`   |
| Codex    | `~/.codex/skills/`    |
| Gemini   | `~/.gemini/skills/`   |
| OpenCode | `~/.opencode/skills/` |

### 安装内容

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

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

## 卸载技能

### 操作步骤

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

### 卸载效果

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

### 从备份恢复

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

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

### 删除备份

如需删除旧的技能备份：

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

## 仓库管理

### 打开仓库管理

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

### 添加自定义仓库

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
```

### 删除仓库

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

删除仓库后，该仓库的技能不会从列表中消失，但无法再更新。

## 技能卡片信息

每个技能卡片显示：

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

## 技能更新

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

### 更新检测原理

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

### 单项更新

对于有新版本的 skill：

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

### 全部更新

当有多个 skill 需要更新时：

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

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

## 存储位置切换

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

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

### 切换方式

在 Skills 面板的设置或管理菜单中选择目标存储位置。切换过程**不会丢失 skill 状态** —— CC Switch 会平滑迁移现有 skill 到新位置。

> ⚠️ **区别提示**：本节的「存储位置切换」管理的是 skill 的**源存储**。而 [1.5 个性化配置 → Skills 同步方式](../1-getting-started/1.5-settings.md) 管理的是 skill 如何**分发到各应用目录**（软链接 vs 复制），两者配合使用。

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

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

### 使用步骤

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

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

## 常见问题

### 技能列表为空

可能原因：

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

解决方法：

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

### 安装失败

可能原因：

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

解决方法：

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

### 更新按钮不出现

可能原因：

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

解决方法：

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