# Snow CLI 使用文档——Skills 指令详细说明

Skills 是 Snow CLI 的强大扩展功能，允许您创建和使用专门的知识库和工具集。每个技能都包含特定领域的专业知识和实用工具，可以通过 `skill-execute` 工具在对话中调用。

## Skills 概述

Snow CLI 的 Skills 功能与 **Claude Code Skills** 完全兼容，您可以：

- 创建自定义技能来封装特定领域的知识和工具
- 复用常用的任务模式和最佳实践
- 在不同项目间共享技能
- 限制技能可访问的工具权限
- 为团队创建标准化的开发流程

### 技能类型

技能主要分为以下几类：

- **工具技能**: 提供特定工具的封装和使用方法（如 slack-gif-creator）
- **知识技能**: 包含特定领域的专业知识和最佳实践
- **模板技能**: 提供可复用的代码、文档或配置模板
- **工作流技能**: 定义标准化的任务执行流程

## 技能结构

每个技能都是一个目录，包含以下标准结构：

```
skill-name/
├── SKILL.md          # 主文档（必需）
├── core/             # 核心代码模块
│   ├── __init__.py
│   ├── main.py       # 主要逻辑
│   └── utils.py      # 工具函数
├── templates/        # 模板文件
│   ├── template1.md
│   └── template2.txt
├── scripts/          # 辅助脚本
│   ├── setup.sh
│   └── process.py
├── requirements.txt  # 依赖列表
└── LICENSE.txt       # 许可证文件
```

### SKILL.md 主文档

主文档是技能的核心，包含：

- **YAML 前置元数据**: 定义技能名称、描述、允许的工具等
- **详细说明**: 技能的功能、使用方法、API 参考
- **代码示例**: 展示如何使用技能的代码片段
- **最佳实践**: 使用技巧和注意事项

```markdown
---
name: skill-name
description: 技能的详细描述
allowed-tools: tool1, tool2, tool3
license: Complete terms in LICENSE.txt
---

# 技能标题

## 功能描述

详细说明技能的功能和用途...

## 使用方法

# 代码示例

## API 参考

### 函数名

描述函数的用途和参数...

## 最佳实践

使用技能时的注意事项和最佳实践...
```

## 技能位置

技能可以来自三个位置：

- **CLI 内置位置（builtin）**: 随 Snow CLI 安装包发布（例如 `bundle/skills/`）
  - 无需手动安装
  - 与当前 CLI 版本同步
  - 当前内置技能：`snow-docs`（官方文档查询）
- **全局位置**: `~/.snow/skills/`
  - 可在所有项目中使用
  - 适合通用的、跨项目的技能
- **项目位置**: `.snow/skills/`
  - 仅在当前项目中使用
  - 适合项目特定的技能

**优先级**: 项目级 > 全局 > 内置（builtin）。同名技能时，更高优先级会覆盖较低优先级。

### 内置技能 snow-docs

Snow CLI 自带内置技能 `snow-docs`，用于在配置/排错 Snow 时按官方文档回答。它会配合只读工具：

- `snow-docs-list`
- `snow-docs-search`
- `snow-docs-get`

可通过 `disabledSkills` 禁用该技能，或通过 `disabledBuiltInServices` 禁用文档工具服务。详见：[官方文档工具（snow-docs）](./28.官方文档工具snow-docs.md)。

## 创建技能

使用 `/skills` 指令创建新的技能：

1. 输入 `/skills` 打开技能创建对话框
2. 输入技能名称（小写字母、数字、连字符，最多 64 字符）
3. 输入技能描述
4. 选择存储位置（全局或项目）
5. 确认创建

创建完成后，系统会自动生成：

- SKILL.md（主文档）
- 必要的目录结构
- 基础模板文件

### 技能列表与更新

使用 `/skills -l` 打开技能列表面板，可以查看、启用/禁用所有已安装的技能，并更新从 GitHub 安装的技能。

面板快捷键：

| 快捷键                   | 功能                                       |
| ------------------------ | ------------------------------------------ |
| `↑` / `↓`                | 上下导航技能列表                           |
| `Tab` / `空格` / `Enter` | 启用/禁用选中技能                          |
| `U`                      | 更新光标选中的单个 GitHub 技能             |
| `A`                      | 更新全部 GitHub 技能（同一仓库只下载一次） |
| `ESC`                    | 关闭面板（更新进行中按 ESC 取消更新）      |

更新过程配有 120 秒超时保护，防止网络请求无限卡住。更新完成后如有技能版本变化，会自动刷新技能列表。

## 使用技能

### 使用 `/skills-` 打开技能选择器（注入到输入框）

`/skills-` 是一个“选择并注入技能内容”的快捷指令（类似 `/agent-`、`/todo-` 的选择面板），用于把某个技能的内容以“注入块”的形式插入到当前输入框中，方便你在本次对话里直接携带该技能的提示词。

它与 `/skills` 的区别：

- `/skills`：创建一个新的技能模板（生成目录、`SKILL.md` 等）。
- `/skills-`：从已有技能列表里选择一个技能，把该技能内容注入到输入框（不创建文件）。

打开方式：

- 在输入框输入 `/skills-`，然后回车；或在命令面板中选中 `skills-`（回车）。

面板交互（默认行为）：

- 上/下方向键：切换技能条目（循环）。
- Tab：在“搜索框(search)”与“附加内容(append)”之间切换焦点。
- 回车：确认选择并注入。
- Esc：关闭面板并回到输入。

注入后的文本形态（内部完整内容）：

- 会生成一段以 `# Skill: <skill-id>` 开头、以 `# Skill End` 结尾的注入块。
- 输入框视觉上会折叠为占位符：`[Skill:<skill-id>] `（末尾带一个空格，方便你继续输入）。
- 发送消息时会按完整注入块发送（不是只发送占位符）。

附加内容（append）如何生效：

- 如果技能的 `SKILL.md` 内容里包含占位符 `$ARGUMENTS`，则会用 append 内容替换 `$ARGUMENTS`。
- 如果不包含 `$ARGUMENTS`，则会在注入块末尾追加一个：
  - `[User Append]` 区块（仅当 append 非空时）。

注意事项：

- 注入块结尾的 `# Skill End` 必须以换行结束，否则你在占位符后继续输入时可能与 end marker 黏连，导致显示层折叠范围异常。
- 技能内容来源于 CLI 内置 skills、`.snow/skills/`（项目级）与 `~/.snow/skills/`（全局）。同名技能时优先级为：项目级 > 全局 > 内置。

### 在对话中调用（直接调用技能工具）

使用 `skill-execute` 工具调用技能：

```

skill: "skill-name"

```

调用后，您会看到：

```

<command-message>The "skill-name" skill is loading</command-message>

```

随后技能的内容会展开，提供详细的指导和使用说明。

### 使用示例

#### slack-gif-creator 技能示例

这是一个完整的技能示例，用于创建适合 Slack 的动画 GIF：

```python
# 加载技能
skill: "slack-gif-creator"

# 技能会提供详细的使用指导，包括：
# - Slack 的 GIF 要求（尺寸、帧率、颜色等）
# - GIFBuilder 工具类的使用方法
# - 动画效果实现（抖动、脉冲、弹跳等）
# - 优化技巧

# 例如创建动画GIF
from core.gif_builder import GIFBuilder
from PIL import Image, ImageDraw

# 创建构建器
builder = GIFBuilder(width=128, height=128, fps=10)

# 生成帧
for i in range(12):
    frame = Image.new('RGB', (128, 128), (240, 248, 255))
    draw = ImageDraw.Draw(frame)

    # 绘制动画
    # ... 绘制代码 ...

    builder.add_frame(frame)

# 保存优化的 GIF
builder.save('output.gif', num_colors=48, optimize_for_emoji=True)
```

## 技能管理

### 列出可用技能

所有可用的技能会在 `skill-execute` 工具的描述中列出，包括：

- 技能名称
- 技能描述
- 技能位置（全局/项目）

### 删除技能

删除自定义技能使用 `-d` 参数：

- **删除全局技能**: `/skill-name -d`（在非项目目录执行）
- **删除项目技能**: `/skill-name -d`（在项目目录执行）

系统会自动识别技能位置并删除对应文件。

### 技能限制

可以通过 `allowed-tools` 字段限制技能可访问的工具：

```yaml
---
name: restricted-skill
description: 限制工具访问的技能
allowed-tools: filesystem-read, filesystem-edit, terminal-execute
---
```

这确保技能只能使用指定的安全工具，提高系统安全性。

## 技能开发最佳实践

### 1. 文档编写

- 使用清晰的结构和标题
- 提供丰富的代码示例
- 包含常见问题和解决方案
- 说明依赖和环境要求

### 2. 代码组织

- 将核心逻辑放在 `core/` 目录
- 使用模块化设计
- 提供清晰的 API
- 添加适当的错误处理

### 3. 模板和脚本

- 在 `templates/` 目录提供常用模板
- 在 `scripts/` 目录提供辅助脚本
- 确保脚本可执行权限
- 提供使用说明

### 4. 工具限制

- 仅允许必要的工具
- 避免高风险操作
- 使用工具限制提高安全性
- 记录限制原因

### 5. 版本控制

- 为技能添加版本信息
- 记录变更日志
- 使用语义化版本号
- 保持向后兼容

## 常用技能示例

### 1. 代码生成技能

```markdown
---
name: code-generator
description: 代码生成模板和最佳实践
allowed-tools: filesystem-read, filesystem-edit, terminal-execute
---
```

提供常用的代码生成模板和模式。

### 2. 文档模板技能

```markdown
---
name: doc-templates
description: 文档和注释模板集合
allowed-tools: filesystem-read, filesystem-edit
---
```

提供 README、API 文档、注释等模板。

### 3. 测试用例技能

```markdown
---
name: test-templates
description: 测试用例模板和测试工具
allowed-tools: filesystem-read, filesystem-edit, terminal-execute
---
```

提供单元测试、集成测试等模板。

### 4. 部署脚本技能

```markdown
---
name: deploy-scripts
description: 自动化部署脚本和流程
allowed-tools: filesystem-read, filesystem-edit, terminal-execute
---
```

提供 CI/CD 部署脚本和最佳实践。

## 与 Claude Code Skills 的兼容性

Snow CLI 的 Skills 功能与 Claude Code Skills 完全兼容：

- **相同的调用方式**: 使用 `skill: "skill-name"` 调用
- **相同的结构要求**: SKILL.md 作为主文档
- **相同的元数据格式**: YAML 前置元数据
- **相同的工具限制**: 支持 allowed-tools 字段
- **完全兼容的生态**: 可以直接使用现有的 Claude Code Skills

这意味着您可以直接在 Snow CLI 中使用：

- Anthropic 官方提供的 Claude Code Skills
- 社区创建的兼容技能
- 您自己创建的 Snow CLI 技能

## 技能安全

### 工具权限控制

强烈建议为每个技能指定允许的工具列表：

```yaml
---
name: safe-skill
description: 安全的技能示例
allowed-tools: filesystem-read, filesystem-edit
---
```

### 敏感操作

避免在技能中包含：

- 直接的系统调用
- 敏感信息（密钥、密码等）
- 破坏性操作（删除、格式化等）

### 代码审查

定期审查技能代码：

- 检查安全漏洞
- 验证工具使用
- 更新依赖版本
- 移除废弃功能

## 故障排除

### 技能未找到

**症状**: 调用技能时提示 "Skill not found"

**解决方案**:

1. 检查技能名称拼写
2. 确认技能已正确安装
3. 验证技能位置（全局/项目）
4. 检查 SKILL.md 文件是否存在

### 工具权限错误

**症状**: 技能运行时提示工具权限不足

**解决方案**:

1. 检查 allowed-tools 配置
2. 验证工具名称拼写
3. 在权限管理中添加必要工具
4. 联系管理员授予权限

### 依赖缺失

**症状**: 技能运行时提示模块未找到

**解决方案**:

1. 检查 requirements.txt
2. 安装缺失的依赖: `pip install -r requirements.txt`
3. 验证 Python 环境
4. 检查虚拟环境激活状态

### 语法错误

**症状**: 技能文档或代码存在语法错误

**解决方案**:

1. 检查 YAML 前置元数据格式
2. 验证 Markdown 语法
3. 检查代码语法
4. 使用代码格式化工具

## 相关配置

- [指令面板说明](./09.0.指令面板说明.md) - 基础指令介绍
- [MCP 配置](./14.MCP配置.md) - MCP 服务配置
- [官方文档工具（snow-docs）](./28.官方文档工具snow-docs.md) - 内置官方文档 skill/工具
- [敏感命令配置](./06.敏感命令配置.md) - 安全工具配置
- [子代理设置](./05.子代理设置.md) - 子代理工具配置

## 高级用法

### 技能组合

可以将多个技能组合使用：

```python
# 先调用代码生成技能
skill: "code-generator"

# 再调用测试模板技能
skill: "test-templates"

# 最后调用部署脚本技能
skill: "deploy-scripts"
```

### 动态技能

技能支持动态加载，修改后立即生效：

1. 编辑技能文件
2. 保存更改
3. 重新调用技能

无需重启应用程序。

### 技能调试

使用以下方法调试技能：

1. 检查技能目录结构
2. 验证 SKILL.md 格式
3. 测试核心代码模块
4. 查看错误日志

## 社区和共享

### 技能分享

可以将您的技能分享给社区：

1. 确保代码质量和文档完整
2. 添加适当的许可证
3. 创建使用示例
4. 发布到技能仓库

### 技能发现

寻找有用技能的方式：

1. 查看官方技能列表
2. 搜索社区技能库
3. 询问其他用户推荐
4. 根据项目需求定制

## 总结

Snow CLI 的 Skills 功能是一个强大的扩展系统，让您可以：

- **封装专业知识**: 将领域知识封装为可复用的技能
- **标准化流程**: 建立团队统一的开发流程
- **提高效率**: 减少重复工作，专注于创新
- **保证质量**: 使用经过验证的最佳实践
- **促进协作**: 在团队间共享经验和技能

通过合理使用 Skills，您可以显著提升开发效率和代码质量，同时建立更加规范和高效的开发流程。