你的 AI 编程助手每天都在帮你写代码，但三个月后回头看，它依然在用同样的方式犯同样的错误。问题不在于 AI 不够强，而在于你没有把自己的经验"固化"给它。

---

一、一个令人沮丧的真相

过去半年，我深度使用 AI Coding 工具完成了三个完整项目。累计生成的代码超过 15 万行。但复盘时发现一个扎心的事实：

第 1 周和第 12 周，AI 犯的错误几乎一模一样。

同样的数据库连接池配置问题，同样的异常处理遗漏，同样的 API 参数校验缺失。每次都需要我手动纠正，每次纠正的方式也相差无几。

这不是 AI 的问题，这是我的问题 —— 我没有建立自己的 Skill 体系。

---

二、从 Prompt 到 Skill：一次认知升级

让我们先理清一个关键概念：

	Prompt	Skill
本质	一次性指令	可复用的能力模块
生命周期	用完即弃	持续迭代
知识载体	自然语言描述	结构化规则 + 示例 + 约束
适用场景	临时任务	高频重复模式
维护成本	无	需要持续更新

通俗地说：Prompt 是你每次都要口头嘱咐实习生的话，Skill 是你写给他的《岗位操作手册》。

一个成熟开发者的价值，不仅仅在于能写出多少代码，更在于能把多少隐性经验转化为显性规则。Skill 就是这个转化过程的产物。

---

三、什么样的场景值得沉淀为 Skill

不是所有经验都值得做成 Skill。判断标准很简单：频率 × 复杂度 × 犯错成本。

满足以下任一条件，就应该考虑沉淀：

3.1 高频重复模式（频率 > 每周 3 次）

• 项目的新增 CRUD 接口
• 数据库迁移脚本
• 单元测试用例生成
• 日志规范检查

3.2 高复杂度模式（非标准流程）

• 微服务间的事务补偿逻辑
• 多数据源读写分离配置
• OAuth2.0 多端认证流程
• 消息队列的死信处理策略

3.3 高犯错成本模式

• SQL 注入防护
• 敏感数据脱敏
• 并发安全的缓存更新
• 幂等性设计

反例：一次性数据迁移脚本、临时调试用的 mock 数据生成器 —— 这些用 Prompt 就够了，不值得做成 Skill。

---

四、Skill 的结构化设计模板

经过三个项目的摸索，我总结出一套 Skill 模板，分为四个层次：

# Skill Name: [简短描述这个 Skill 做什么]

## 1. 触发条件
- 用户说"新建一个 xxx 接口"、"添加数据库迁移"等关键词
- 文件路径匹配 `src/api/**/*.ts`
- 当前上下文包含特定框架标记

## 2. 核心约束（必须遵守的硬规则）
- 所有 SQL 查询必须使用参数化查询，禁止字符串拼接
- 异常处理必须包含错误码、错误消息、日志记录三层
- API 响应必须遵循 `{ code, data, message }` 统一格式
- 涉及金额的字段统一使用 `BigDecimal` / `decimal.Decimal`

## 3. 推荐模式（建议使用的最佳实践）
- 优先使用项目已有的工具类和基类
- 数据库操作统一通过 Repository 层
- 复杂业务逻辑拆分为独立的 Service 方法
- 超过 3 个参数的函数使用对象参数

## 4. 代码示例
### 正确示例
```python
# 参数化查询
cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))

错误示例

# 字符串拼接 - 禁止
cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")

5. 常见陷阱

• 不要信任前端传来的 page_size，必须限制最大值
• 批量操作必须分批处理，单批不超过 500 条
• 定时任务必须加分布式锁

这个模板的核心设计理念是：**约束比建议更重要，示例比描述更有效。**

---

## 五、实战：从日常 AI Coding 中提取 3 个典型 Skill

以下是我在实际项目中沉淀的三个 Skill，直接可复用。

### Skill 1：安全编码基础规范

**触发条件**：任何涉及数据库操作、用户输入处理、文件上传的代码生成。

**核心约束**：

1. SQL 必须使用预编译语句，禁止拼接
2. 用户输入必须做 XSS 过滤和长度校验
3. 文件上传限制类型白名单 + 大小上限
4. 敏感配置（密钥、密码）禁止硬编码，统一走配置中心
5. 日志中禁止打印用户手机号、身份证、密码明文

**收益**：AI 生成代码的安全问题从每周 8-12 个降到 0-1 个。

### Skill 2：RESTful API 设计规范

**触发条件**：涉及 Controller / Router 层代码生成。

**核心约束**：

1. URL 使用复数名词：/api/users 而非 /api/getUserList
2. HTTP 方法语义正确：GET 查询 / POST 创建 / PUT 全量更新 / PATCH 部分更新 / DELETE 删除
3. 分页参数统一：page (默认1) / page_size (默认20，最大100)
4. 排序参数：sort_by + sort_order (asc/desc)
5. 错误码体系：4xxx 客户端错误 / 5xxx 服务端错误 / 业务错误码 6 位
6. 响应体结构：{ “code”: 0, “data”: {}, “message”: “ok”, “request_id”: “uuid” }

**收益**：团队成员无需每次 Code Review 时重复指出 URL 命名和响应格式问题。

### Skill 3：Go 项目错误处理范式

**触发条件**：涉及 Go 语言项目代码生成。

**核心约束**：

1. 禁止使用 panic 处理业务错误
2. 每个 error 必须 wrap 上下文信息：fmt.Errorf(“doSomething: %w”, err)
3. 使用 errors.Is / errors.As 进行错误类型判断
4. DAO 层返回原始 error，Service 层 wrap，Controller 层转换 HTTP 状态码
5. 禁止吞掉 error（if err != nil { return nil } 视为吞错误）

**收益**：错误定位时间从平均 15 分钟降到 3 分钟，因为堆栈信息完整体现了调用链。

---

## 六、Skill 的管理与迭代

沉淀 Skill 只是第一步，真正的价值在于持续管理。

### 6.1 版本化管理

每个 Skill 都应该像一个软件模块一样有版本号：

security-baseline/v1.2.0 # 主版本.次版本.修订版本
api-design/v2.0.0 # 不兼容的架构级变更
error-handling/v1.0.3 # 小修补

版本变更日志记录到 CHANGELOG，让团队成员知道改了哪些约束。

### 6.2 定期回顾（每两周）

- 这周 AI 犯的新错误，哪些可以通过新增约束来避免？
- 哪些现有约束已经被团队养成了肌肉记忆，可以降级为"推荐模式"？
- 哪些约束过于严格，导致了不必要的代码冗余？

### 6.3 团队共建

Skill 不应该是一个人闭门造车。建议做法：

1. 每个 Skill 指定一个 Owner
2. 新增约束需要至少一人 Review
3. 争议约束用数据说话：统计"如果没有这条约束，过去一个月会产生多少问题"
4. 新成员入职第一周必须通读所有 Skill

---

## 七、常见误区与避坑指南

### 误区 1：Skill 越多越好

**真相**：Skill 超过 20 个后，AI 会出现"约束冲突"——不同 Skill 的规则互相矛盾，导致生成质量反而下降。

**建议**：控制在 10-15 个核心 Skill，其余经验用更轻量的"代码片段模板"承载。

### 误区 2：Skill 写一次就完事

**真相**：框架升级、依赖变更、团队规模变化都会让 Skill 过时。我有一次因为 Go 版本从 1.20 升到 1.22，`for` 循环变量语义变了，Skill 里关于闭包捕获的约束反而成了错误引导。

**建议**：每个 Sprint 结束时花 10 分钟检查 Skill 是否仍然有效。

### 误区 3：把 Skill 当成银弹

**真相**：Skill 解决的是"一致性问题"，不解决"创新性问题"。架构设计、技术选型、复杂业务建模仍然需要人的判断力。

---

## 八、总结：Skill 的本质是工程化思维

如果用一句话总结：**Skill 体系是软件工程中"Code Review Checklist"和"团队编码规范"在 AI 时代的自然延伸。**

区别在于：以前的规范是给人看的，靠 Code Review 强制执行；现在的 Skill 是给 AI 看的，在代码生成阶段就自动生效。

两者的底层逻辑完全一致：**把隐性知识显性化，把个人经验组织化，把一次性判断规则化。**

---

## 附：我的 Skill 文件目录结构

skills/
├── README.md # 索引与使用说明
├── security-baseline/
│ ├── SKILL.md # v1.2.0
│ └── CHANGELOG.md
├── api-design/
│ ├── SKILL.md # v2.0.0
│ └── CHANGELOG.md
├── error-handling/
│ ├── SKILL.md # v1.0.3
│ └── CHANGELOG.md
├── database-convention/
│ ├── SKILL.md # v1.1.0
│ └── CHANGELOG.md
├── testing-standard/
│ ├── SKILL.md # v1.0.0
│ └── CHANGELOG.md
└── code-templates/ # 轻量级模板（非 Skill）
├── crud-controller.go.tmpl
├── unit-test.go.tmpl
└── migration.sql.tmpl

---

**最后说一句大实话**：如果你的 AI Coding 效率在三个月内没有明显提升，不是 AI 不够好，是你没有把自己的经验喂给它。Skill 不是可选项，是 AI Coding 时代每个开发者的必修课。