CodeBuddy 学习（6）：Skills 技能系统

一、概述：为什么需要 Skills

1.1 传统 Prompt 的三大痛点

用 Prompt 直接指挥 AI 有三个难以绕开的问题：

痛点	具体表现	后果
重复写	每次都要从头描述工作流程	效率低，容易漏步骤
Prompt 太密	一股脑塞大量指令给 AI	模型忽略约束，Token 成本高
不可复用	没有模板，每次从零交代	输出质量不稳定

1.2 Skills 的解决方案

Skills 的核心理念：把工作流程封装为模块，需要时触发，不需要时不占上下文。

它是 CodeBuddy 原生的模块化机制，允许你定义"做什么"（流程步骤）、“输出什么”（固定格式）和"怎样算成"（验收标准），像搭积木一样组合使用。

---

二、什么是 Skill

2.1 原理讲解

一个 Skill = 一个 .codebuddy/skills/<skill-name>/SKILL.md 文件。

三级加载机制（节省上下文的核心设计）：

级别	内容	加载时机	大小
一级：元数据	name + description	启动时始终加载	极小（几十字节）
二级：指令	SKILL.md 正文	description 匹配后加载	中等（几 KB）
三级：资源	reference.md / 脚本	执行中按需加载	可能很大

触发流程：

1. 用户输入需求，AI 将需求与所有已注册 Skill 的 description 做语义匹配。
2. 匹配成功后，加载二级指令（SKILL.md 全文）。
3. 执行过程中，若内部调用了其他 Skill 或需要查 reference.md，按需加载三级资源。

关键优势：不需要 reference.md 时，完全不加载——保持上下文精简。

---

三、Skill 的四段式结构

3.1 标准模板

---
name: skill-name
description: 触发条件描述（决定何时匹配加载此 Skill）
---

# Skill 标题

## Input
定义 Skill 接收什么输入（必填项 / 可选项）

## Output
定义输出格式（固定结构，不随输入变化）

## Procedure
定义分步执行流程（第 1 步做什么、第 2 步做什么）

## Acceptance
验收标准（怎样算成功，什么情况算失败）

3.2 目录结构

.codebuddy/skills/
  meeting-minutes/
    SKILL.md          # 核心：指令 + 流程 + 验收
  expense-reimbursement/
    SKILL.md          # 核心指令
    reference.md      # 三级资源：政策数据（仅在需要时加载）

---

四、实战示例一：会议纪要 Skill

4.1 创建

mkdir -p .codebuddy/skills/meeting-minutes
touch .codebuddy/skills/meeting-minutes/SKILL.md

4.2 完整 SKILL.md 文件

---
name: meeting-minutes
description: 当用户提供会议讨论内容或聊天记录，并需要生成规范会议纪要时使用此技能。
当讨论中出现费用/报销/预算相关内容时，请自动调用 expense-reimbursement Skill 处理。
---

# Meeting Minutes（项目会议纪要）

## Input
- 会议文本、聊天记录或要点（必填）
- 会议背景和目标（可选）

## Output
请严格按照以下栏目输出，不得遗漏：

1. 背景与目标（Background & Goals）
2. 结论摘要（Executive Summary，不超过 10 行）
3. 决策记录（Decisions）
   表格格式：| 事项 | 结论 | 影响范围 |
4. 待办事项（Action Items）
   表格格式：| 事项 | Owner | Deadline | 风险/依赖 |
5. 未决问题（Open Questions）
6. 风险与依赖（Risks & Dependencies）
7. 费用/报销（若涉及）

## Procedure
1. 判断信息是否足够生成完整纪要。
   如果不够，先问 3 个最关键的问题（不要猜测补充）。
2. 按 Output 结构生成纪要。
3. 检查纪要中是否出现了费用、报销、预算相关内容。
4. 如果涉及费用：调用 expense-reimbursement Skill 处理费用部分。

## Acceptance
- 纪要可以直接放入项目文档库（不需要二次整理）
- 所有待办必须包含 Owner 与 Deadline
- 信息缺失处标注 UNKNOWN，并在末尾列出追问清单
- 严禁猜测：不清楚的地方标注 UNKNOWN，不要自行编造

4.3 验证

确认 Skill 已注册：

你输入：list skills
AI 返回：已注册 Skills：meeting-minutes

触发测试：
输入一段模拟的会议讨论记录：

今天开会讨论了三个问题：
1. 用户反馈登录太慢，技术评估后决定加 Redis 缓存，
   张三负责，下周五前完成。
2. 下周要去深圳出差，预计费用 2000 元，需要报销。
3. 移动端首页改版方案还没定，待下次讨论。
请生成会议纪要。

预期输出：

# Meeting Minutes（项目会议纪要）

## 背景与目标
团队技术例会，讨论登录性能优化、出差安排和移动端改版方向。

## 结论摘要
- 登录性能问题确定使用 Redis 缓存方案
- 出差安排已定，费用需按政策处理
- 移动端改版方案暂时搁置

## 决策记录
| 事项 | 结论 | 影响范围 |
|------|------|---------|
| 登录性能优化 | 使用 Redis 缓存 | 后端 + 基础设施 |

## 待办事项
| 事项 | Owner | Deadline | 风险/依赖 |
|------|-------|----------|----------|
| Redis 缓存接入 | 张三 | 下周五 | 需要运维配置 Redis 实例 |

## 未决问题
- 移动端首页改版方案（待下次讨论）

## 风险与依赖
- Redis 实例配置依赖运维支持

## 费用/报销
（调用 expense-reimbursement Skill 处理出差报销）
- 类型：差旅费
- 金额：2000 元
- 地点：深圳
- ...

4.4 调试过程

场景一：Skill 未被触发

现象：你输入了会议内容，但 AI 没有按会议纪要格式输出。
原因排查：
  1. description 字段是否足够具体？
     ❌ "处理会议" → 太模糊
     ✅ "当用户提供会议讨论内容或聊天记录，并需要生成规范会议纪要时使用"
  2. SKILL.md 文件名和目录名是否正确？
     目录名必须与 name 一致：skills/meeting-minutes/SKILL.md
     name 必须是：meeting-minutes
  3. 检查大小写——Skills 系统对大小写敏感。
修复：
  1. 修改 description，加入更具体的触发关键词（"会议纪要""聊天记录""生成纪要"）。
  2. 确认 name 和目录名完全一致。
  3. 运行 list skills 确认 Skill 是否成功注册。

场景二：输出格式不对

现象：AI 输出了会议纪要，但缺少 Decision 表格，或 Owner/Deadline 字段为空。
原因排查：
  1. Output 段是否足够具体？
     "生成一个表格" 不够 → "表格格式：| 事项 | Owner | Deadline |"。
  2. Acceptance 是否可验证？
     "输出清晰" 不可验证 → "所有待办必须包含 Owner 与 Deadline" 可验证。
修复：
  1. 回到 SKILL.md，细化 Output 部分的格式要求。
  2. 在 Acceptance 中添加可量化检查项。
  3. 可以加入反面约束："严禁输出不完整的待办行（缺少 Owner 或 Deadline）"。

场景三：内容不准确（AI 猜测了缺失信息）

现象：AI 在没有提供 Deadline 的情况下，自己编了一个日期。
原因：
  1. Acceptance 中没有明确"禁止猜测"。
  2. AI 默认倾向于"给出完整回答"而非"标注缺失"。
修复：
  1. 在 Acceptance 中加："信息缺失处标注 UNKNOWN，严禁自行编造或猜测"。
  2. 在 Procedure 中加："如果信息不够，先提问，不要猜"。
  3. 使用 reference.md 提供权威数据源，减少 AI 猜测的动机。

---

五、实战示例二：费用报销 Skill（链式调用）

5.1 原理

一个 Skill 可以在 Procedure 中调用另一个 Skill。这是 Skills 系统的核心能力——通过链式调用组合多个模块化的工作流程。

5.2 SKILL.md（核心指令）

---
name: expense-reimbursement
description: 当讨论中出现差旅、招待、办公用品等费用报销事宜时使用此技能。
---

# Expense Reimbursement（费用报销）

## Input（4 项必填）
- expense_type：费用类型（差旅费 / 招待费 / 办公费）
- amount：金额
- occurrence_date：发生日期
- pre_approved：是否已预审批

## Output
| 项目 | 说明 |
|------|------|
| 费用类型 | [类型] |
| 金额 | [金额] |
| 政策标准 | [标准] |
| 超标情况 | 超标 / 未超标 / 需补充材料 |
| 审批流程 | [流程说明] |
| 所需材料 | [材料清单] |

## Procedure
1. 从 reference.md 查找对应费用类型的政策。
2. 对比实际金额与政策标准。
3. 返回结构化输出。
4. 如果 reference.md 中没有对应政策 → 输出 NEED MORE INFO。

## Acceptance
- 严禁猜测：reference.md 中没有的政策信息 → 输出 NEED MORE INFO
- 金额对比必须基于政策标准计算，不能凭经验估计

5.3 reference.md（三级资源）

# 报销政策参考

## 差旅费
- 城市等级：
  - 一线城市（北京/上海/广州/深圳）：500 元/天
  - 其他城市：350 元/天
- 审批：主管审批
- 材料：行程单 + 发票

## 招待费
- 标准：人均 200 元/次
- 审批：总额 > 2000 元需经理审批
- 材料：发票 + 参与人名单

## 办公费
- 标准：单品 500 元以下
- 审批：部门主管审批
- 材料：发票 + 购买清单

5.4 调用链

用户输入会议记录
  → meeting-minutes Skill 触发
    → 检测到"出差费用 2000 元"
      → 调用 expense-reimbursement Skill
        → 加载 reference.md，查找差旅政策
        → 返回：500 元/天 × 3 天 = 1500 元标准
        → 实报 2000 元 → 超标 500 元 → 需经理审批

5.5 调试过程

场景：reference.md 数据缺失

现象：差旅政策中只有"一线城市 500/天"，但用户去了杭州（非一线），
     AI 应该返回 NEED MORE INFO，但实际上按 500/天算了。
原因：reference.md 中"其他城市"的标准写了，但 AI 没有按城市匹配。
排查：
  1. 检查 reference.md 中"其他城市"的标准是否明确。
  2. 检查 Procedure 中的匹配逻辑：先判断城市等级，再查标准。
修复：
  1. 更新 reference.md，明确标注城市分类。
  2. 在 Procedure 中增加匹配步骤："先查 expense_type → 再查 city_level → 匹配标准"。

---

六、设计要点总结

设计点	为什么重要
Output 定义固定栏目	让 AI 每次输出格式一致，下游可自动化处理
Procedure 分步写清	AI 知道先做什么后做什么，不会跳步骤
缺失标注 UNKNOWN	信息不足时不猜，保持输出可信性
Acceptance 可验证	你可以客观判断这个 Skill 是否执行成功
description 精准	决定了 Skill 是否在正确的时机被触发

---

七、Skills vs MCP

维度	Skills	MCP
本质上	行为规范——定义怎么做	能力接口——提供外部数据/工具
角色比喻	指挥官：管流程	手和眼睛：拿数据
触发方式	description 语义匹配	按需调用工具

最强组合：Skills 指挥流程 + MCP 提供执行能力。例如：会议纪要 Skill 指挥"查政策"→ 报销 MCP 工具执行数据库查询获取最新标准。

---

八、小结

Skill 是什么？ → 把工作流程封装为可复用的模块
怎么创建？     → 四段式：Input / Output / Procedure / Acceptance
怎么触发？     → description 匹配 → 加载指令 → 按需加载资源
怎么验证？     → list skills 确认 → 模拟输入 → 检查 Output 结构
不生效？       → 先查 description + 命名 → 再查 Output 是否具体