第 5 课：Skill 技能系统

什么是 Skill？

Skill（技能）就是一份给 AI 看的操作手册。

打个比方：你招了一个很聪明的实习生，但他不知道你们公司用什么工具、什么格式。你需要给他一份文档，告诉他"要生成 Word 文件的时候，用这个库，按这个规范来"。

这份文档就是 Skill。

resume-generator 里的 Skill

这个项目只有一个技能：docx（Word 文档生成），放在这个位置：

code

.claude/skills/docx/
├── SKILL.md      ← 技能入口：告诉 AI 该用什么工作流
└── docx-js.md    ← 参考手册：docx 库的具体 API 用法

SKILL.md —— 技能入口

SKILL.md 是 AI 的"决策导航"。它先有一个头部信息：

code
---
name: docx
description: "Comprehensive document creation, editing, and analysis..."
---

然后是一棵"决策树"，告诉 AI 遇到不同情况该走哪条路：

graph TD A["AI 拿到一个文档任务"] --> B{"需要读/分析文档？"} A --> C{"需要创建新文档？（简历生成走这条路）"} A --> D{"需要编辑已有文档？"} B --> B1["用 pandoc 转成 markdown"] C --> C1["用 docx-js（JavaScript 库）"] C1 --> C2["1. 先读 docx-js.md（必须！）"] C2 --> C3["2. 写 JS 代码用 Document, Paragraph, TextRun 等组件"] C3 --> C4["3. 用 Packer.toBuffer 导出 .docx"] D --> D1["用 Python 的 OOXML 方式"]

对于简历生成，AI 会走"创建新文档"这条路。SKILL.md 告诉它：先去读 docx-js.md，然后用 JavaScript 来生成文档。

docx-js.md —— API 参考手册

这是一份大约 350 行的参考文档，相当于给 AI 看的 docx 库速查手册。它包含：

基本结构：怎么创建一个文档

code
const doc = new Document({
  sections: [{
    children: [/* 内容放这里 */]
  }]
});
Packer.toBuffer(doc).then(buffer =>
  fs.writeFileSync("doc.docx", buffer)
);

文字格式：粗体、斜体、字号、颜色

code
new Paragraph({
  children: [
    new TextRun({ text: "粗体", bold: true }),
    new TextRun({ text: "红色大字", color: "FF0000", size: 28 }),
  ]
})

样式系统：标题、正文、自定义样式

code
styles: {
  default: { document: { run: { font: "Arial", size: 24 } } },
  paragraphStyles: [
    { id: "Heading1", name: "Heading 1", run: { size: 32, bold: true } }
  ]
}

列表：项目符号、编号列表

表格：行列、边框、合并单元格

页面设置：页边距、页眉页脚、页码

还有一大堆"千万不要这样做"的警告：

code

❌ 永远不要用 \n 换行 → 用单独的 Paragraph
❌ 永远不要用 Unicode 符号做列表 → 用 LevelFormat.BULLET
❌ PageBreak 不能独立使用 → 必须放在 Paragraph 里

这些"坑"是前人踩过的，写进参考手册让 AI 也能避开。

Skill 是怎么被 AI 加载的？

整个加载链条是这样的：

graph TD A["第一步：query 配置 settingSources: project"] --> B["SDK 从项目的 .claude/ 目录加载配置"] B --> C["第二步：SDK 扫描 .claude/skills/ 目录"] C --> D["发现了 docx 技能"] D --> E["第三步：AI 在 allowedTools 里有 Skill"] E --> F["AI 可以用 Skill 工具来读取技能文件"] F --> G["第四步：AI 调用 Skill - 读取 SKILL.md"] G --> H["AI 了解到要用 docx-js"] H --> I["第五步：AI 用 Read 工具读取 docx-js.md"] I --> J["AI 学会了 docx 库的用法"] J --> K["第六步：AI 写出正确的 JS 代码生成 Word 文档"]

用一句话概括：settingSources 告诉 SDK 去哪找技能 → Skill 工具让 AI 能读技能 → AI 读完就"学会"了。

为什么不把技能直接写进 systemPrompt？

你可能会想："干嘛这么麻烦？把 docx-js.md 的内容直接塞到系统提示词里不就行了？"

不行，有三个原因：

1. 太长了

docx-js.md 有 350 行。系统提示词塞这么多内容，AI 的注意力会被稀释，重要指令可能被忽略。

2. 不灵活

如果你想生成 PDF 而不是 Word，就得把整个 systemPrompt 换掉。而用 Skill 的话，只需要在 .claude/skills/ 里加一个 pdf 技能就行。

3. 按需加载

AI 不一定每次都需要读完整个参考手册。Skill 系统让 AI 自己决定什么时候读、读多少。

code

systemPrompt 写法（❌ 笨重）：
  "你是简历写手。以下是 docx 库的完整 API 文档：
   （350 行参考手册全塞进来）
   现在开始工作。"

Skill 写法（✅ 灵活）：
  systemPrompt: "你是简历写手。用 docx 库生成 Word 文件。"
  + .claude/skills/docx/（AI 自己去读）

怎么自己写一个 Skill？

如果你想添加新的技能（比如 PDF 生成、Excel 处理），只需要三步：

第一步：创建目录

code

mkdir -p .claude/skills/你的技能名/

第二步：写 SKILL.md

code
---
name: 你的技能名
description: "一句话描述这个技能干嘛的"
---

# 技能说明

## 什么时候用
描述在什么场景下应该用这个技能

## 怎么用
具体的操作步骤和代码示例

## 注意事项
常见的坑和解决办法

第三步：添加参考文档（可选）

如果技能涉及某个库的详细 API，可以单独写一个参考文档（就像 docx-js.md）。

本课小结

Skill 是给 AI 看的操作手册，放在 .claude/skills/ 目录
resume-generator 用了一个 docx 技能，包含 SKILL.md（决策导航）和 docx-js.md（API 参考）
通过 settingSources: ['project'] + Skill 工具让 AI 能访问技能
Skill 比直接写进 systemPrompt 更灵活、更高效

课后练习

打开 .claude/skills/docx/SKILL.md，通读一遍决策树
打开 docx-js.md，注意那些"❌ WRONG"和"✅ CORRECT"的对比——这些就是 AI 踩坑后总结出来的
想一想：如果要做一个"自动生成 Excel 报表"的工具，Skill 文件里应该写什么？