CodeBuddy Code Skills （技能系统） ​

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

什么是 Skills ​

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

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

Skills vs Slash Commands ​

特性SkillsSlash 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
---
name: pdf
description: PDF 文档处理专家
allowed-tools: Read, Write, Bash, WebFetch
---

你是一个 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

使用示例 ​

示例 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 中）。

下一步 ​

Skills - 让 AI 成为领域专家