CodeBuddy 专题/第 8 章

Skills 技能开发

技能定义、Skills.md规范、PPT/文档/代码技能实战

引言

如果 Rules 是"告诉 AI 什么不能做"，那么 Skills 就是"教 AI 怎么做"。

Skills 是 CodeBuddy 最强大的扩展机制之一——它让你可以为 AI 配备任何专业能力，从代码审查到 PPT 生成，从数据库迁移到安全扫描。

核心思想：Skills = 把你的专业知识打包成 AI 可执行的指令

一、Skills 的本质

1.1 什么是 Skill？

一个 Skill 是一个文件夹，包含：

.codebuddy/skills/deploy/
├── SKILL.md          # 技能描述和使用指南
├── scripts/          # 可执行脚本
│   └── deploy.sh
├── references/       # 参考资料
│   └── checklist.md
└── templates/        # 模板文件
    └── nginx.conf

1.2 Skills vs Rules vs MCP

概念	角色	数据流向	类比
Rules	约束 AI 输出行为	你 → AI	公司制度
Skills	为 AI 配备专业能力	你 → AI	专业培训
MCP	连接外部工具和数据源	AI ↔ 外部系统	工具箱

关键区别：

Rules 说"不要用 any 类型" → AI 遵守
Skills 说"按这个清单做代码审查" → AI 执行
MCP 说"连接 PostgreSQL 数据库" → AI 查询

1.3 为什么 Skills 比 MCP 更高效？

MCP 工具：需要在上下文中加载工具描述 → 消耗 Token
Skills：只在需要时加载 → 不消耗额外 Token

Skills 的定义不占上下文，只有显式调用时才加载。这意味着你可以有几十个 Skills，但不会影响正常对话的 Token 预算。

二、SKILL.md 规范

2. Skills 三级加载机制

2.1 渐进式披露设计原则

Skills 使用三级加载系统来高效管理上下文：

级别	内容	加载时机	大小
元数据	name + description	始终在上下文中	~100词
Skill 主体	SKILL.md body	Skill 被触发时加载	<5k词
打包资源	scripts/references/assets	按需加载	可变

2.2 三级加载的优势

节省 Token：元数据始终在上下文中，但只有 ~100 词
按需加载：只有被触发时才加载完整内容
渐进式披露：先看描述，再看详情，最后看资源

2.3 触发方式

Skills 支持三种触发方式：

触发方式	说明	示例
description	AI 根据描述判断是否使用	description: "PDF编辑"
glob	基于文件类型匹配	*/.pdf
@skills/name	手动触发	@skills/pdf-editor

3.1 基本结构

---
name: code-review
description: 执行代码审查
triggers:
  - 代码审查
  - review
  - CR
---

# 代码审查技能

## 使用场景
当用户请求代码审查时使用

## 执行步骤
1. 读取目标文件
2. 按检查清单逐项检查
3. 输出审查结果

## 检查清单
- [ ] 安全性
- [ ] 性能
- [ ] 可维护性

2.2 Frontmatter 字段

字段	必填	说明
`name`	✅	技能名称（唯一标识）
`description`	✅	技能描述
`triggers`	可选	触发关键词
`tools`	可选	需要的工具列表
`model`	可选	指定使用的模型

2.3 触发机制

Skills 通过触发词自动激活：

---
triggers:
  - 部署
  - 上线
  - deploy
  - 发布
---

当用户说"帮我部署到生产环境"时，AI 会自动加载这个 Skill。

三、内置 Skills

CodeBuddy 内置了多种实用技能：

3.1 PPT Skill

支持三种工作流：

工作流	输入	输出
从零创建	文字描述	PPT 文件
修改现有	现有 PPT + 修改指令	修改后的 PPT
模板模式	模板 + 内容	基于模板的 PPT

使用示例：

你：帮我做一个关于项目架构的 PPT，10 页左右
AI：（调用 PPT Skill）
    ✅ 生成封面页
    ✅ 生成目录页
    ✅ 生成架构图页
    ✅ 生成技术选型页
    ✅ 生成总结页
    → 文件已生成：project-architecture.pptx

3.2 文档 Skill

自动生成技术文档：

API 文档（从代码注释生成）
README（从项目结构生成）
架构文档（从代码分析生成）

3.3 测试 Skill

自动生成测试用例：

单元测试
集成测试
E2E 测试

四、自定义 Skills 实战

4.1 案例：创建代码审查 Skill

需求：团队需要统一的代码审查标准

步骤 1：创建目录

mkdir -p .codebuddy/skills/code-review

步骤 2：编写 SKILL.md

---
name: code-review
description: 执行团队标准的代码审查
triggers:
  - 代码审查
  - review
  - CR
  - 审查
---

# 代码审查技能

## 审查标准

### 🔴 严重问题（必须修复）
- SQL 注入风险
- XSS 漏洞
- 硬编码密钥/密码
- 未处理的异常
- 无限循环风险

### 🟡 警告（建议修复）
- 函数超过 50 行
- 嵌套超过 3 层
- 缺少错误处理
- 缺少类型定义
- 重复代码

### 🔵 建议（可优化）
- 命名不够清晰
- 缺少注释
- 可以使用更简洁的写法
- 性能优化空间

## 输出格式

按文件分组，按严重程度排序：

### src/auth/login.ts
🔴 第 45 行：SQL 拼接，存在注入风险
  建议：使用参数化查询
🟡 第 23 行：函数过长（67行）
  建议：拆分为 validateInput、authenticate、generateToken 三个函数
🔵 第 12 行：变量名 `d` 不够清晰
  建议：改为 `userDetails`

步骤 3：使用

你：帮我审查 src/auth/ 目录的代码

AI：（加载 code-review Skill，按审查标准逐项检查）

### src/auth/login.ts
🔴 第 45 行：SQL 拼接
  ```typescript
  const query = `SELECT * FROM users WHERE email = '${email}'`;

风险：SQL 注入修复：

const query = 'SELECT * FROM users WHERE email = $1';
const result = await db.query(query, [email]);

🟡 第 23 行：authenticate 函数 67 行建议：拆分为 3 个子函数


### 4.2 案例：创建部署 Skill

```markdown
---
name: deploy
description: 将项目部署到生产环境
triggers:
  - 部署
  - 上线
  - deploy
---

# 部署技能

## 部署前检查
1. ✅ 所有测试通过（npm test）
2. ✅ 代码已提交（git status clean）
3. ✅ 环境变量已配置
4. ✅ 数据库迁移已执行

## 部署步骤
1. 运行测试：npm test
2. 构建生产版本：npm run build
3. 上传到服务器
4. 执行数据库迁移
5. 重启服务
6. 健康检查（curl /health）

## 回滚方案
如果部署失败：
1. 恢复上一版本代码
2. 回滚数据库迁移
3. 重启服务

五、Skills 的高级特性

5.1 组合使用

多个 Skills 可以组合使用：

你：帮我发布新版本

AI：
  1. 加载 code-review Skill → 审查代码
  2. 加载 test Skill → 运行测试
  3. 加载 deploy Skill → 部署上线
  4. 加载 changelog Skill → 生成变更日志

5.2 条件执行

# 部署技能

## 条件
- 仅在 main 分支执行
- 仅在测试通过后执行

## 步骤
1. 检查当前分支
2. 运行测试
3. 执行部署

5.3 版本管理

Skills 支持版本管理，团队可以共享和迭代：

.codebuddy/skills/
├── code-review/
│   ├── SKILL.md        # v1.0
│   └── CHANGELOG.md
├── deploy/
│   ├── SKILL.md        # v2.1
│   └── CHANGELOG.md

六、常见陷阱

陷阱 1：触发词太宽泛

❌ triggers: ["做", "写", "改"]  # 会误触发
✅ triggers: ["代码审查", "review", "CR"]  # 精确匹配

陷阱 2：Skill 太复杂

❌ 一个 Skill 包含 20 个步骤
✅ 拆分为多个小 Skill，按需组合

陷阱 3：不维护 Skill

❌ 写完就放着，项目变了 Skill 没变
✅ 定期更新 Skill，与项目保持同步

七、总结

问题	答案
Skills 是什么？	为 AI 配备的专业能力包
和 Rules 的区别？	Rules 约束行为，Skills 武装能力
如何创建？	.codebuddy/skills/ 目录 + SKILL.md
如何触发？	自然语言触发词或 /skill 命令
最佳实践？	精确触发词、单一职责、定期维护