# CodeBuddy Code Skills （技能系统）

Skills 是 CodeBuddy Code 的扩展能力系统，允许您创建专业的领域知识和工作流模板，让 AI 助手能够更专业地处理特定类型的任务。

## 什么是 Skills

Skills 类似于为 AI 助手提供的"专业培训"。通过 Skill，您可以：

- **封装专业知识**：将特定领域的最佳实践和操作流程封装成可复用的技能
- **提供工作流模板**：定义标准化的任务处理流程，提高工作效率
- **扩展 AI 能力**：让 AI 助手能够处理更专业、更复杂的任务
- **团队协作共享**：项目级 Skills 可以在团队成员间共享专业知识

## Skills vs Slash Commands

| 特性 | Skills | Slash Commands |
|-----|--------|----------------|
| **触发方式** | AI 模型自动识别并调用 | 用户手动输入命令 |
| **使用场景** | 专业领域任务处理 | 快捷操作和工作流 |
| **权限控制** | 支持工具白名单限制 | 无特殊权限控制 |
| **工作目录** | 支持自定义基础目录 | 使用当前工作目录 |
| **可见性** | 对用户透明，AI 自动决策 | 用户主动发起 |

**简单来说**：
- **Slash Commands** 是用户主动调用的快捷方式
- **Skills** 是 AI 根据任务需求自动选择的专业能力

## 创建 Skills

### 目录结构

Skills 通过在特定目录中创建 `SKILL.md` 文件来定义：

1. **项目级 Skills**：`.codebuddy/skills/`（项目根目录下）
2. **用户级 Skills**：`~/.codebuddy/skills/`（用户主目录下）

每个 Skill 一个独立的目录，包含 `SKILL.md` 文件：

```
.codebuddy/skills/
├── pdf/
│   └── SKILL.md
├── data-analysis/
│   └── SKILL.md
└── code-review/
    └── SKILL.md
```

### SKILL.md 格式

Skill 文件使用 Markdown 格式，支持 YAML Frontmatter 定义元数据：

```markdown

你是一个 PDF 文档处理专家，擅长：
- 解析和提取 PDF 内容
- 转换 PDF 为其他格式
- 生成 PDF 报告

当用户需要处理 PDF 相关任务时，请使用以下工作流：
1. 首先检查 PDF 文件是否存在
2. 使用适当的工具提取内容
3. 根据需求进行处理
4. 生成结果报告

可用工具：
- pdftotext：提取文本内容
- pdfinfo：获取 PDF 信息
```

### Frontmatter 字段

| 字段 | 必填 | 说明 | 示例 |
|-----|------|------|------|
| `name` | 否 | Skill 名称，未指定时使用目录名 | `pdf` |
| `description` | 否 | Skill 描述，帮助 AI 理解何时使用 | `PDF 文档处理专家 （project)` |
| `allowed-tools` | 否 | 允许使用的工具白名单，逗号分隔 | `Read, Write, Bash` |
| `disable-model-invocation` | 否 | 设置为 `true` 时，Skill 不会出现在 Skill 工具中，只能通过 `/skill-name` 手动触发 | `true` |
| `user-invocable` | 否 | 设置为 `false` 时，Skill 从 `/` 菜单中隐藏，仅供 AI 内部调用或其他 Skill 引用，默认 `true` | `false` |
| `context` | 否 | 设置为 `fork` 时，Skill 在独立的 subagent 上下文中执行 | `fork` |
| `agent` | 否 | 指定 subagent 类型，仅在 `context: fork` 时有效 | `Explore` |

## 执行 Shell 命令

与[斜杠命令](slash-commands.md)一样，Skills 也支持在 SKILL.md 中使用 `!`command`` 语法内联执行 Shell 命令。当 Skill 被触发时（无论是 AI 自动调用还是用户通过 `/skill-name` 手动触发），这些命令会被执行，输出结果会替换到 Skill 内容中，供 AI 后续分析。

**示例**：

```markdown
---
description: 项目状态分析
---

### 当前工作目录

!`echo "CWD=$(pwd)"`

### Git 状态

!`git status --short`

### 最近提交

!`git log --oneline -5`

请基于以上信息分析项目当前状态。
```

### 支持的特性

- **`$ARGUMENTS` 参数替换**：在 Shell 命令执行前，`$ARGUMENTS` 会被替换为用户传入的参数
- **`@file` 文件引用**：Shell 命令执行后，`@file` 引用会被处理并注入文件内容
- **错误隔离**：单个命令执行失败不会影响其他命令，失败的命令会被替换为空字符串

> 💡 **处理管道**：`$ARGUMENTS` 替换 → `!`command`` 执行 → `@file` 引用处理，与斜杠命令的处理顺序一致。

## Context Fork

`context: fork` 使 Skill 在隔离的子代理上下文中运行，不访问对话历史。

```yaml
---
name: deep-research
description: 深入研究某个主题
context: fork
agent: Explore
---

研究 $ARGUMENTS：
1. 使用 Glob 和 Grep 查找相关文件
2. 读取并分析代码
3. 总结发现并附加具体文件引用
```

### 可用 Agent 类型

| 类型 | 说明 |
|-----|------|
| `general-purpose` | 通用（默认） |
| `Explore` | 只读工具，优化代码库探索 |
| `Plan` | 规划和分析 |
| 自定义 | `.codebuddy/agents/` 中定义的 agent |

### 隐藏 Skill（user-invocable）

`user-invocable: false` 使 Skill 从 `/` 菜单中隐藏，适用于：
- 背景知识类 Skill（如项目规范、编码标准）
- 仅供其他 Skill 或 AI 内部引用的辅助 Skill

```yaml
---
name: project-guidelines
description: 项目编码规范和最佳实践
user-invocable: false
---

# 项目编码规范

本项目遵循以下编码标准：
- 使用 TypeScript 严格模式
- 函数命名使用 camelCase
- 组件命名使用 PascalCase
...
```

这类 Skill 会被加载到 AI 的上下文中，但用户无法通过 `/` 菜单直接调用。

### 执行流程

1. 创建新的隔离上下文
2. 子代理接收 Skill 内容作为提示
3. `agent` 字段决定执行环境
4. 结果返回主对话

> **注意**：`context: fork` 只适用于包含明确任务的 Skill。仅有指导方针没有具体任务时，不会产生有意义的输出。

## 使用示例

### 示例 1：PDF 处理 Skill

**文件**：`.codebuddy/skills/pdf/SKILL.md`

```markdown
---
name: pdf
description: PDF 文档处理和转换专家
allowed-tools: Read, Write, Bash, WebFetch
---

# PDF 处理专家

你是一个专业的 PDF 文档处理专家。

## 核心能力
- 提取 PDF 文本内容
- 转换 PDF 为 Markdown、HTML 等格式
- 合并和拆分 PDF 文件
- 提取 PDF 元数据和书签

## 工作流程
1. 检查 PDF 文件是否存在并可访问
2. 使用 pdftotext 或 pdfinfo 获取基本信息
3. 根据任务类型选择合适的处理工具
4. 验证输出结果的完整性

## 可用工具
- pdftotext：提取纯文本
- pdfinfo：获取文档信息
- pdftk：合并拆分操作
```

**使用**：当用户询问 "帮我提取这个 PDF 的内容" 时，AI 会自动识别需要 PDF 处理能力并调用该 Skill。

### 示例 2：数据分析 Skill

**文件**：`~/.codebuddy/skills/data-analysis/SKILL.md`

```markdown
---
name: data-analysis
description：数据分析和可视化专家
allowed-tools: Read, Write, Bash, WebFetch, NotebookEdit
---

# 数据分析专家

你是一个专业的数据分析师，擅长使用 Python 和相关工具进行数据分析。

## 核心能力
- 数据清洗和预处理
- 统计分析和建模
- 数据可视化
- 生成分析报告

## 分析流程
1. 理解数据结构和质量
2. 清洗和预处理数据
3. 执行统计分析
4. 创建可视化图表
5. 生成分析结论

## 工具库
- pandas：数据处理
- numpy：数值计算
- matplotlib/seaborn：可视化
- scikit-learn：机器学习

## 最佳实践
- 始终先探索数据质量
- 使用 Jupyter Notebook 进行交互式分析
- 保存中间结果避免重复计算
```

### 示例 3：代码审查 Skill

**文件**：`.codebuddy/skills/code-review/SKILL.md`

```markdown
---
name: code-review
description：代码审查和质量检查专家
allowed-tools: Read, Grep, Bash, Edit
---

# 代码审查专家

你是一个经验丰富的代码审查者，遵循业界最佳实践。

## 审查重点
1. **代码质量**
   - 命名规范
   - 代码复杂度
   - 重复代码

2. **安全性**
   - SQL 注入风险
   - XSS 漏洞
   - 认证授权问题

3. **性能**
   - 算法效率
   - 资源使用
   - 缓存策略

4. **可维护性**
   - 代码注释
   - 模块化设计
   - 测试覆盖

## 审查流程
1. 理解代码变更的目的
2. 检查代码风格和规范
3. 分析潜在的 Bug 和性能问题
4. 验证安全性
5. 提供建设性的改进建议

## 输出格式
- ✅ 优点：列出做得好的地方
- ⚠️ 问题：指出需要改进的地方
- 💡 建议：提供具体的改进方案
```

## AI 如何选择 Skills

AI 根据以下因素决定是否调用 Skill：

1. **任务匹配度**：任务描述与 Skill description 的相关性
2. **工具需求**：任务所需工具是否在 allowed-tools 范围内
3. **上下文相关性**：当前对话上下文是否适合使用该 Skill
4. **Skill 来源**：项目级 Skills 优先于用户级 Skills

## 权限控制

### allowed-tools 白名单

通过 `allowed-tools` 字段限制 Skill 可以使用的工具：

```yaml
allowed-tools: Read, Write, Bash(git:*), Grep
```

支持的工具模式匹配：
- `Bash(git:*)` - 只允许 git 相关命令
- `Edit(src/**/*.ts)` - 只允许编辑特定路径文件

### 工作目录限制

每个 Skill 都有自己的 `baseDirectory`（SKILL.md 所在目录），可以在 Skill 指令中引用：

```markdown
当处理文件时，优先在 {baseDirectory} 目录下查找相关资源。
```

## 最佳实践

### 1. 清晰的 Skill 描述

```yaml
# ❌ 不好
description：处理文件

# ✅ 好
description: PDF 文档解析和转换专家，支持文本提取和格式转换 （project)
```

### 2. 详细的指令内容

提供详细的：
- 核心能力说明
- 标准工作流程
- 可用工具列表
- 常见场景处理方法
- 输出格式要求

### 3. 合理的工具权限

只授予必需的工具权限：

```yaml
# ❌ 权限过大
allowed-tools: Bash

# ✅ 精确控制
allowed-tools: Read, Write, Bash(git:status,git:diff), Grep
```

### 4. 组织 Skill 目录

按功能领域组织 Skills：

```
.codebuddy/skills/
├── document/
│   ├── pdf/SKILL.md
│   └── markdown/SKILL.md
├── data/
│   ├── analysis/SKILL.md
│   └── visualization/SKILL.md
└── code/
    ├── review/SKILL.md
    └── refactor/SKILL.md
```

## 调试 Skills

### 查看已加载的 Skills

使用 `/skills` 命令查看当前已加载的所有 Skills：

```
/skills
```

Skills 面板会显示：
- **User skills**：用户级 Skills（`~/.codebuddy/skills/`）
- **Project skills**：项目级 Skills（`.codebuddy/skills/`）
- **Plugin skills**：插件提供的 Skills

每个 Skill 会显示名称和预估的 token 数量。

### 常见问题

**Q: Skill 没有被触发？**
- 检查 description 是否清晰描述了 Skill 的功能
- 确认任务描述与 Skill 能力匹配
- 验证 allowed-tools 是否包含所需工具

**Q: Skill 权限不足？**
- 检查 allowed-tools 配置
- 确认工具名称拼写正确
- 使用模式匹配精确控制权限

**Q：项目级和用户级 Skill 冲突？**
- 项目级 Skills 优先级更高
- 使用不同的 name 避免冲突

## 与其他功能的配合

### Skills + Memory

Skills 可以访问 Memory 系统存储的信息：

```markdown
在执行数据分析时，参考 Memory 中保存的数据模式和业务规则。
```

### Skills + Slash Commands

Slash Commands 可以引用 Skills：

```markdown
<!-- .codebuddy/commands/analyze-data.md -->
请使用 data-analysis skill 分析文件：$1
```

### Skills + MCP

Skills 可以调用 MCP 提供的外部工具（如果在 allowed-tools 中）。

## 下一步

- [斜杠命令](slash-commands.md) - 了解用户主动命令
- [设置配置](settings.md) - 配置工具权限
- [MCP 集成](mcp.md) - 扩展外部工具能力

---

*Skills - 让 AI 成为领域专家*
