AI超载 | 第8章:Skill系统——把老员工的脑子「复制」进AI

章节关键词：渐进式披露、三层结构、知识封装、SKILL.md、好 Skill vs 差 Skill

章节字数：8,000+

阅读时间：约 25 分钟

///

PART 01

开篇：一个让你崩溃的周一早晨

周一早上 9 点，你刚坐到工位，老板发来一条消息：

你打开对方代码库——没有文档，没有注释，10 万行代码，技术栈和你熟悉的完全不同。

你花了 30 分钟才搞懂他们在支付模块的 3 个核心设计决策：

他们的「订单」表叫 order_info，你们叫 orders
他们的「已支付」状态是 paid，你们是 PAYMENT_COMPLETED
他们的「退款」逻辑写在一个 2000 行的工具类里，你找了 2 小时

你多么希望：如果有人能提前告诉你这些就好了。

如果有一个人——一个懂这个代码库的「老员工」——提前把这些知识告诉你，你就能节省 3 小时。

Skill 系统，就是为了解决这个问题。

///

PART 02

8.1 Skill 解决的核心问题

8.1.1 每次对话 AI 都是「全新的我」

使用 AI 编程工具时，你有没有遇到过这种情况：

第 1 天：

你：「帮我写一个支付模块的代码」

AI：「好的，你需要：1. 创建订单表...」

你：「等等，我们公司不是这样设计订单的...」

第 2 天：

你：「帮我写一个支付模块的代码」

AI：「好的，你需要：1. 创建订单表...」

你：「...我昨天说过了我们不是这样设计的」

AI：「抱歉，我没有昨天的记忆。」

问题根源：每次新对话，AI 都是「全新的我」。

它不记得：

你们公司的命名规范
你们的技术栈选择
你们踩过的坑和解决方案
你们特有的业务概念

8.1.2 传统解决方式的局限性

方式一：每次都从头解释

你：「记住，我们公司的订单表叫 order_info，不是 orders...」

你：「还有，已支付状态是 paid，不是 PAYMENT_COMPLETED...」

你：「还有，退款逻辑在这个工具类里...」

缺点：

每次对话都要重复
容易遗漏
费时费力

方式二：写在项目 README 里

# 支付模块开发规范

1. 订单表：order_info

2. 状态定义：paid（已支付）、refunded（已退款）

3. 退款逻辑：PaymentRefundUtil

缺点：

AI 不一定会读
分散在各处，AI 不知道在哪找
格式不标准，AI 难以理解

8.1.3 Skill 的解决思路

Skill 的核心理念是：

Skill 系统：

├── 订单规范 Skill

│ ├── 表名：order_info（不是 orders）

│ ├── 状态定义：paid/refunded

│ └── 退款逻辑位置

├── React Hook Skill

│ ├── 常用模式

│ ├── 最佳实践

│ └── 避坑指南

└── Python 测试 Skill

├── pytest 用法

├── fixtures 模式

└── 覆盖率要求

效果：

知识只写一次
AI 在需要时自动加载
团队共享，不遗漏

///

PART 03

8.2 渐进式披露三层结构设计

8.2.1 为什么需要渐进式披露？

想象一下：

如果你把所有的知识一次性全告诉 AI：

知识量太大，AI 消化不了
大量无关知识占用上下文
AI 不知道哪些是现在需要的

如果 AI 每次都要读全部知识才能判断是否相关：

效率低下
浪费 Token

渐进式披露解决的就是这个问题——让 AI 只读取「当前需要的」知识。

8.2.2 三层结构一览

Skill 三层结构：

第一层：name + description

├── 始终可见

├── 用于判断是否加载

└── 极小，毫秒级

第二层：SKILL.md 正文

├── 任务匹配时加载

├── 核心知识内容

└── 适量，需要时读取

第三层：references/ 目录

├── 需要时显式引用

├── 详细参考资料

└── 大型，不自动加载

8.2.3 第一层：name + description

Skill 元信息：

├── name：skill-name（小写连字符）

└── description：简短描述（用于自动激活判断）

示例：

---

description: 公司支付模块开发规范，包含表名、状态定义、退款逻辑位置

---

只有这两行始终可见，AI 用它判断「这个 Skill 和当前任务是否相关」。

为什么这一层最重要？

因为 AI 在决定「是否加载这个 Skill」时，只看这一层。

AI 决策过程：

1. 用户任务：「帮我写支付模块代码」

2. AI 检查所有 Skill 的 name + description

3. 发现「company-payment-patterns」描述中有「支付」

4. 决定加载这个 Skill

5. 读取第二层 SKILL.md 正文

8.2.4 第二层：SKILL.md 正文

SKILL.md 正文内容：

# 公司支付模块开发规范

## 什么时候使用

当需要开发、修改支付相关代码时使用本 Skill。

## 核心规范

### 表命名

- 订单表：order_info（不是 orders）

- 支付记录表：payment_transaction

### 状态定义

| 状态 | 值 | 说明 |

|------|-----|------|

| 待支付 | pending | 订单创建 |

| 已支付 | paid | 支付成功 |

| 已退款 | refunded | 退款完成 |

### 退款逻辑

退款逻辑统一在 PaymentRefundUtil 类中，不要自行实现。

位置：src/utils/payment/PaymentRefundUtil.java

这一层是 Skill 的核心，AI 在匹配成功后加载。

8.2.5 第三层：references/ 目录

references/ 目录：

├── api-reference.md # API 详细文档

├── legacy-notes.md # 历史遗留说明

├── troubleshooting.md # 常见问题排查

└── related-skills.md # 相关 Skill 链接

AI 默认不加载这一层，只有在需要时显式引用。

什么情况下加载第三层？

用户问：「退款失败怎么排查？」

AI 发现：当前 Skill 的第二层只有退款逻辑位置，没有排查指南。

AI 主动读取 references/troubleshooting.md

AI 输出：退款失败排查步骤...

///

PART 04

8.3 SKILL.md 标准格式与 YAML frontmatter

8.3.1 完整 SKILL.md 示例

---

description: 公司支付模块开发规范，包含表名、状态定义、退款逻辑位置

origin: company-internal

tags: [payment, backend, java]

version: 1.0.0

---

# 公司支付模块开发规范

## When to Activate（什么时候激活）

当遇到以下场景时，AI 应自动加载本 Skill：

- 用户请求开发支付相关功能

- 用户请求修改订单表结构

- 用户请求实现退款逻辑

- 用户询问支付状态相关问题

## Core Concepts（核心概念）

### 表命名规范

...

### 状态定义

...

### 退款流程

...

## Code Examples（代码示例）

### 正确示例

// ✅ 使用 PaymentRefundUtil 处理退款
PaymentRefundUtil.refund(orderId, amount);

### 错误示例

// ❌ 不要自行实现退款逻辑
if (order.paid) {
order.status = "refunded";
}

## Anti-Patterns（反模式）

1. 不要直接在 Service 层实现退款逻辑

2. 不要硬编码支付状态值

3. 不要在订单表存储支付流水

## Best Practices（最佳实践）

- 支付状态始终使用 PaymentStatus 枚举

- 退款必须经过 PaymentRefundUtil

- 支付异常记录到 PaymentErrorLog 表

8.3.2 YAML frontmatter 字段说明

字段	必须	说明
`name`	✅	小写连字符，语义化命名
`description`	✅	一行描述，用于自动激活判断
`origin`	❌	来源：ECC / community / 公司名
`tags`	❌	分类标签数组
`version`	❌	版本号，格式：1.0.0

8.3.3 name 命名规范

✅ 好的 name：

company-payment-patterns
react-hook-patterns
postgresql-indexing
pytest-fixtures

❌ 差的 name：

payment（太宽泛）
react（太宽泛）
database（太宽泛）
code（毫无意义）

命名原则：name 应该描述 Skill 的具体内容，而不是笼统的领域。

///

PART 05

8.4 真实案例：sql-analysis Skill

8.4.1 问题背景

不同公司对同一个概念有不同的定义。

例如「收入」：

A 公司：「收入」= 实际付款金额
B 公司：「收入」= 订单金额（不管付没付款）
C 公司：「收入」= GMV（成交总额）

如果 AI 不知道你们公司的定义，它写的 SQL 可能完全错误。

8.4.2 sql-analysis Skill 的实现

---

description: 公司数据分析 SQL 规范，包含收入定义、常用指标、查询示例

origin: company-internal

tags: [sql, analytics, data]

version: 1.0.0

---

# 公司数据分析 SQL 规范

## 重要概念定义

### 收入定义

**本公司的「收入」定义**：

收入 = 订单状态为 PAID 且支付完成时间在统计区间内的订单金额

⚠️ **注意**：不是 GMV，不是订单金额，是实际已支付的金额。

### 常用指标定义

| 指标 | SQL 字段 | 说明 |

|------|----------|------|

| 收入 | paid_amount | 已支付金额 |

| 订单数 | COUNT(order_id) | 订单总数 |

| 客单价 | paid_amount / order_count | 每单平均 |

| 退款率 | refunded_amount / paid_amount | 退款占比 |

### 正确示例

-- ✅ 正确的收入查询
SELECT
SUM(paid_amount) as revenue,
COUNT(order_id) as order_count,
SUM(paid_amount) / COUNT(order_id) as avg_order_value
FROM orders
WHERE status = 'PAID'
AND paid_at BETWEEN '2024-01-01' AND '2024-01-31'

### 错误示例

-- ❌ 错误的收入查询（GMV 而非实际收入）
SELECT SUM(order_amount) as revenue
FROM orders
WHERE created_at BETWEEN '2024-01-01' AND '2024-01-31'

### 常用查询模板

-- 日报：今日收入
SELECT SUM(paid_amount)
FROM orders
WHERE DATE(paid_at) = CURDATE()
AND status = 'PAID'

-- 月报：月度收入趋势
SELECT
DATE(paid_at) as date,
SUM(paid_amount) as daily_revenue
FROM orders
WHERE status = 'PAID'
GROUP BY DATE(paid_at)
ORDER BY date

## Related Skills

- `company-payment-patterns`：支付模块开发规范

- `company-metrics-definition`：公司指标定义文档

8.4.3 效果对比

没有 Skill 时：

用户：帮我查一下 1 月的收入

AI：SELECT SUM(order_amount) FROM orders WHERE ...

用户：不对，我们公司的收入是指已支付的金额，不是订单金额

AI：抱歉，我重新查询...（浪费一次对话）

有 Skill 时：

用户：帮我查一下 1 月的收入

AI：[加载 company-sql-analysis Skill]

AI：SELECT SUM(paid_amount) FROM orders WHERE status = 'PAID' ...

用户：✅ 正确（一次搞定）

///

PART 06

8.5 Skill vs Agent vs Command vs Hook

8.5.1 一张表讲清楚

组件	用途	激活方式	生命周期
Skill	知识仓库	上下文自动触发	持久化
Agent	任务执行器	显式委托	临时任务
Command	用户操作	用户调用（`/command`）	一次性
Hook	自动化	事件触发	事件驱动

8.5.2 何时用 Skill？

场景：需要 AI 学习特定知识 → 用 Skill

示例：

公司代码规范
特定技术栈模式
业务概念定义
项目特定知识

8.5.3 何时用 Agent？

场景：需要 AI 执行特定任务 → 用 Agent

示例：

代码审查
架构设计
安全分析
性能优化

8.5.4 何时用 Command？

场景：用户需要执行特定操作 → 用 Command

示例：

/help：显示帮助
/plan：进入规划模式
/compact：压缩上下文

8.5.5 何时用 Hook？

场景：需要在特定时机自动执行 → 用 Hook

示例：

工具执行前：验证参数
工具执行后：格式化输出
会话开始：加载上下文
会话结束：保存笔记

///

PART 07

8.6 好 Skill vs 差 Skill：聚焦原则

8.6.1 为什么聚焦很重要？

❌ 差的 Skill（太宽泛）：

description: React 相关开发

问题：

- 什么都能沾边，什么都不精准

- AI 加载后还是不知道具体怎么用

- 知识太泛，缺乏深度

✅ 好的 Skill（聚焦）：

description: React Hook 最佳实践，包含 useState、useEffect、useCallback 等常用模式

问题：

- 精准匹配，命中率高

- 知识深度足够

- AI 知道什么时候加载、怎么使用

8.6.2 好 Skill vs 差 Skill 对比表

✅ 好 Skill	❌ 差 Skill
`react-hook-patterns`	`react`
`postgresql-indexing`	`databases`
`pytest-fixtures`	`python-testing`
`nextjs-app-router`	`nextjs`
`docker-patterns`	`devops`
`api-design`	`backend`
`git-workflow`	`vcs`

8.6.3 聚焦原则的具体指导

原则一：描述具体问题，不是宽泛领域

❌ 太宽泛：python
✅ 聚焦：python-testing、python-patterns

❌ 太宽泛：security
✅ 聚焦：security-review、api-security-check

原则二：包含足够的上下文

❌ 模糊：react-hooks
✅ 具体：react-hook-patterns（包含具体模式）

❌ 模糊：sql
✅ 具体：sql-query-optimization、sql-indexing-strategies

原则三：符合使用者的心智模型

使用者想找什么？
❌ 数据库优化（不知道搜什么）
✅ PostgreSQL 索引优化（知道搜什么）

❌ 测试（太宽泛）
✅ pytest fixtures（具体技术+具体模式）

///

PART 08

8.7 Skill 分类体系

8.7.1 ECC 的 182 个 Skill 分类

根据技术底稿，ECC（Everything Claude Code）生态提供了 182 个精选 Skill，分为以下类别：

分类	示例 Skill	用途
开发流程	`tdd-workflow`、`systematic-debugging`、`requesting-code-review`	规范开发流程
代码质量	`coding-standards`、`refactor-cleaner`、`code-reviewer`	提升代码质量
架构设计	`architect`、`backend-patterns`、`api-design`	系统架构
专业领域	`pytorch-patterns`、`nestjs-patterns`、`database-reviewer`	特定技术栈
效率工具	`continuous-learning-v2`、`context-budget`、`autonomous-loops`	效率提升
业务内容	`article-writing`、`market-research`、`brand-voice`	非技术任务

8.7.2 常见 Skill 用途说明

tdd-workflow

当：需要开发新功能或修复 Bug 时
加载：TDD 开发流程规范
包含：RED-GREEN-REFACTOR 三阶段、测试优先原则

systematic-debugging

当：遇到 Bug 需要调试时
加载：系统化调试方法论
包含：复现→定位→修复→验证流程

coding-standards

当：需要审查或编写代码时
加载：代码规范检查清单
包含：命名、格式、最佳实践

api-design

当：需要设计或审查 API 时
加载：API 设计规范
包含：REST 命名、分页、错误处理

///

PART 09

8.8 如何创建你的第一个 Skill

8.8.1 创建步骤

第一步：确定 Skill 的目标

问自己：

这个 Skill 解决什么问题？
什么时候应该加载它？
它包含什么知识？

第二步：编写 SKILL.md

---

description: 描述这个 Skill 做什么

---

# 标题

## When to Activate

描述什么时候使用这个 Skill

## Core Concepts

核心知识内容

## Examples

代码示例

第三步：放置到正确位置

skills/

└── my-first-skill/

└── SKILL.md

第四步：测试 Skill

测试流程：

1. 触发 Skill 的场景

2. 检查 AI 是否自动加载

3. 检查加载的内容是否正确

4. 根据需要调整

8.8.2 创建公司规范 Skill 的完整示例

假设你需要创建一个「公司 Git 提交规范」的 Skill：

---

description: 公司 Git 提交规范，包含提交信息格式、分支命名规范、PR 流程

origin: company-internal

tags: [git, workflow, 规范]

version: 1.0.0

---

# 公司 Git 提交规范

## When to Activate

当用户提到以下场景时加载：

- 提交代码（git commit）

- 创建分支

- 发起 Pull Request

- 使用 git 工作流

## 提交信息格式

### 格式要求

<body>

### Type 类型

| Type | 说明 | 示例 |

|-|-|-|

| feat | 新功能 | feat(order): 添加订单导出功能 |

| fix | Bug 修复 | fix(payment): 修复支付回调失败问题 |

| docs | 文档更新 | docs: 更新 README |

| style | 代码格式 | style: 格式化代码 |

| refactor | 重构 | refactor(order): 重构订单服务 |

| test | 测试 | test: 添加订单测试用例 |

| chore | 构建/工具 | chore: 升级依赖版本 |

### 正确示例

feat(order): 添加订单导出 Excel 功能

支持导出字段：

订单号、创建时间
商品名称、数量
支付金额、支付方式

影响范围：order-service
相关 issue：#1234

### 错误示例

feat: 修改代码

（没有 scope、没有 subject、没有 body）

## 分支命名规范

格式：<type>/<ticket-id>-<简短描述>

示例：

feature/PROJ-123-add-order-export
fix/PROJ-456-payment-callback
hotfix/PROJ-789-critical-security

## PR 规范

### PR 要求

1. 必须关联对应 ticket

2. 必须通过 CI 检查

3. 必须有至少 1 人 review

4. 必须 squash commit 后合并

### PR 描述模板

PART 10

变更内容

...

PART 11

测试情况

[ ] 单元测试通过
[ ] 集成测试通过
[ ] 手动测试通过（如有）

PART 12

影响范围

...

## Related Skills

- `company-git-workflow`：Git 工作流详细说明

- `requesting-code-review`：代码审查规范

///

PART 13

8.9 Skill 的进阶用法

8.9.1 Skill 组合

多个 Skill 可以组合使用：

用户任务：开发一个新的订单导出功能

AI 自动加载：

├── company-payment-patterns（支付规范）

├── company-git-commit（Git 提交规范）

├── tdd-workflow（TDD 开发流程）

└── api-design（API 设计规范）

8.9.2 Skill 继承

可以创建「父 Skill」和「子 Skill」：

父 Skill：python-patterns

├── Python 通用模式

└── 内容广泛

子 Skill：pytest-fixtures

├── pytest fixtures 专用模式

└── 基于 python-patterns

8.9.3 Skill 版本管理

---

version: 1.0.0 # 初始版本

---

# v1.0.0：初始版本

# - 基础表命名规范

# - 状态定义

当规范更新时：

---

version: 1.1.0 # 更新版本

---

# v1.1.0：新增退款流程规范

# - 添加 RefundStatus 枚举

# - 新增退款 API 规范

///

PART 14

8.10 常见问题与解决方案

Q1：Skill 太多，AI 不知道加载哪个怎么办？

A：优化 description，确保描述精准。

❌ 模糊描述：

description: Python 开发规范

✅ 精准描述：

description: Python 代码规范，包含 PEP8、命名规范、类型提示要求

Q2：多个 Skill 内容冲突怎么办？

A：明确 Skill 的优先级和适用范围。

company-payment-patterns：

- 适用于：支付模块开发

- 优先级：高（公司强制）

python-patterns：

- 适用于：通用 Python 开发

- 优先级：低（通用规范）

当两者冲突时，company-payment-patterns 优先。

Q3：Skill 的知识过期了怎么办？

A：建立 Skill 维护机制。

维护流程：

1. 定期审查 Skill 内容

2. 根据代码库变化更新

3. 记录更新日志

4. 通知团队成员

Q4：团队如何共享 Skill？

A：使用 Git 管理 Skill 仓库。

skill-repo/

├── company-payment-patterns/

├── company-git-commit/

├── python-patterns/

└── README.md

团队成员克隆到本地：

git clone skill-repo.git ~/.claude/skills/

更新 Skill：

git pull origin main

///

PART 15

8.11 本章小结

核心知识点

知识点	关键内容
Skill 核心问题	每次对话 AI 都是「全新的我」，Skill 解决知识复用
渐进式披露	第一层：name+description；第二层：SKILL.md；第三层：references/
SKILL.md 格式	YAML frontmatter + Markdown 正文
聚焦原则	`react-hook-patterns` > `react`
Skill vs Agent	Skill=知识仓库，Agent=任务执行

关键术语

术语	定义
Skill	可复用的知识模块，AI 上下文触发加载
渐进式披露	只在需要时加载对应层次的知识
SKILL.md	Skill 的核心定义文件
name	Skill 的唯一标识，小写连字符
description	Skill 描述，用于自动激活判断
references/	Skill 的参考资料目录

Skill 命名对比

❌ 太宽泛	✅ 聚焦
`react`	`react-hook-patterns`
`databases`	`postgresql-indexing`
`python-testing`	`pytest-fixtures`
`nextjs`	`nextjs-app-router`

行动建议

立即行动（15 分钟）：创建你的第一个 Skill

选择一个你经常需要「教 AI」的知识
按照 SKILL.md 格式编写
测试 AI 是否能正确加载

下一步（1 小时）：创建团队共享 Skill

收集团队共同的开发规范
整理成多个聚焦的 Skill
建立 Skill 仓库，团队共享

持续优化：建立 Skill 维护机制

定期审查 Skill 内容
根据项目变化更新
分享好的 Skill 给团队

///

PART 16

下章预告

*本章完。第 9 章：Hook 自动化——让 AI 长出「肌肉记忆」*

///

*本章完。*

THANKS FOR READING

🦐 龙虾 · OpenClaw 技术分享