说实话，写这篇博客的时候我心情挺复杂的。

一个月前我刚到实习岗位，满腔热血，觉得自己学了一年Java，终于能大展拳脚了。结果第一周下来，我发现自己每天干的最多的事情是——帮团队里各种人处理一些"小事"：格式化日志、检查SQL有没有带敏感字段、按固定模板写周报日报、把一堆散乱的设备上报数据整理成结构化文档……

每件事都不难，但每件都要重复做。

最离谱的是有一天，我上午花了两小时帮三个同事分别处理了三份格式不同但内容差不多的数据报告。下午我坐在工位上发呆，脑子里就一个念头：我是在用大学学的数据库知识干活吗？我明明是个复读机啊。

然后带我的老周（化名，别问了）看我状态不对，走过来问了一句：“你天天在忙啥？”

我把那一堆杂活一说，他笑了：“这些事儿你干嘛不让AI帮你干？”

我说：“让AI干？我连prompt都写不利索，每次出来的东西还得大改。”

他说：“那你有没有想过，不是每次重新教AI，而是写一份说明书，让它自己学会？”

这就是我第一次听说"Skill"这个东西。

---

一、Skill到底是个啥？别被概念唬住

我当时反应跟你现在可能一样——Skill？听起来很高大上，是不是要写什么复杂的插件？要不要学新框架？

老周当时的原话我记到现在，他说：“你就把它理解成你给实习生写的工作手册。”

你想啊，假设你带了个新来的实习生，你得告诉他：遇到A类数据怎么处理，遇到B类报告用什么模板，SQL里哪些字段不能碰，周报要按什么格式写……你把这些写成一个文档，他照着做就行了，对吧？

Skill就是这个文档。只不过你的"实习生"变成了AI助手。

技术上说，Skill就是一个叫SKILL.md的Markdown文件，放在一个固定目录里。AI助手启动的时候会读这些文件，遇到对应的场景就自动按你写的规则来执行。

就这么简单。没有SDK，没有编译，没有依赖管理。一个Markdown文件，就是你的全部武器。

---

二、我的第一个Skill：从翻车到能跑

我第一个Skill的需求特别朴素——我每天要检查一批SQL语句，看它们有没有带上权限过滤条件。这事儿我手动做了两周，眼睛都快瞎了。

我兴冲冲地跑去问老周：“我是不是直接写个Markdown告诉AI’帮我检查SQL’就行了？”

他说：“你写写看。”

我第一版大概是这么写的：

---
name: sql-checker
description: 帮助检查SQL语句
---

# SQL检查器

请帮我检查SQL语句是否合规。

跑了一下，AI回了我一句"您的SQL语句看起来没问题"。

我拿着这个结果去找老周，他看了一眼就乐了：“你这说明书也太敷衍了吧？你要是给实习生写’帮我检查SQL’，他也不知道你所谓的’合规’是啥意思啊。”

我愣住了。

他说：“你想想你手动检查的时候，脑子里在过哪些规则？把它们一条一条写下来。”

于是我回去，把脑子里的规则全倒了出来，写了第二版：

---
name: sql-checker
description: 检查SQL语句是否包含必要的权限过滤条件，
  适用于日常SQL审查、代码Review、数据查询校验等场景。
  当用户提到SQL审查、权限过滤、数据权限检查时使用此技能。
---

# SQL权限过滤检查

## 检查规则

1. 所有涉及用户数据的查询必须包含 zone_id 过滤条件
2. 涉及设备数据的查询必须关联用户设备类型权限表
3. SELECT * 语句需要标记为警告（建议显式列出字段）
4. 检查是否存在未加权限过滤的JOIN操作

## 输出格式

对每条SQL输出：
- 是否通过（✅ / ❌）
- 命中的规则编号
- 如果不通过，给出修改建议

## 示例

输入：
```sql
SELECT * FROM device_data WHERE create_time > '2026-01-01'

输出：

❌ 不通过
- 命中规则：#1 缺少 zone_id 过滤
- 命中规则：#3 使用了 SELECT *
- 建议：添加 WHERE zone_id = ? AND ... 并显式列出需要的字段

这次跑出来的结果，说实话把我惊到了——跟我手动检查的结论几乎一模一样，而且速度是我的一百倍。

老周看了一眼说："这还差不多。但你注意到没有，你第二版比第一版多了什么？"

我想了想：**规则具体了，输出格式固定了，还给了例子。**

他说："对，这就是写Skill的三个核心——**告诉它做什么、怎么做、做完了长什么样**。"

---

### 三、踩过的坑，替你提前排掉

接下来两周我陆续写了四五个Skill，有做得好的也有翻车的。把教训整理一下，省得你们再踩：

**坑1：description写得太笼统**

我有个Skill一开始description写的是"帮助处理数据报告"。结果呢，我让它干啥它都觉得跟"数据报告"有关，连我让它写个Hello World它都要扯到数据报告上去。

后来我改成了"将设备上报的JSON原始数据整理为结构化Markdown报告，适用于日报生成、数据归档、异常数据标注等场景"，这下它只在真正需要的时候才触发。

description这个字段，是AI判断"我该不该用这个Skill"的唯一依据。你写得越具体，它越聪明；写得越模糊，它越抽风。

**坑2：SKILL.md写成了教科书**

我有个Skill写了快800行，把各种背景知识、原理说明全塞进去了。结果AI执行的时候经常"跑偏"——因为它在上下文里要处理的信息太多了，反而抓不住重点。

老周跟我说了一句话我印象很深：**"AI已经很聪明了，你只需要写它不知道的东西。"**

后来我把那个800行的文件砍到了200行，把详细的参考资料拆到了另一个文件里（叫`reference.md`），只在主文件里留了一句"详细参考见reference.md"。效果反而好了。

这就好比你给实习生写手册，核心操作写在第一页，背景资料附在后面，他想看自己翻。别把第一页就搞得像论文一样。

**坑3：没有给示例**

这个坑我踩了两次。有一次写了一个代码审查的Skill，规则写得很详细，但没给例子。结果AI输出的审查报告格式每次都不一样，有时候用表格，有时候用列表，有时候还给我来个诗歌体（夸张了，但真的很难统一）。

加了两三个示例之后，输出格式就稳定了。**示例是最好的老师，对AI也一样。**

---

### 四、我现在的工作流：一套Skill组合拳

到现在为止，我给自己写了这些Skill（举几个例子，你们可以举一反三）：

| Skill名称 | 干什么的 | 触发场景 |
|-----------|---------|---------|
| sql-review | 检查SQL权限过滤 | 提到SQL审查/权限检查时 |
| daily-log-format | 按固定格式整理工作日志 | 提到日报/工作日志时 |
| api-doc-gen | 根据Controller代码生成接口文档 | 提到接口文档/API文档时 |
| data-clean | 清洗设备上报的脏数据 | 提到数据清洗/脏数据处理时 |

每天早上到工位，AI助手会自动加载这些Skill。我遇到对应场景的时候，它就直接按规则干活，我负责审核就行。

最直观的变化是：以前每天花两三个小时的重复性工作，现在压缩到了半小时左右。剩下的时间我可以看看源码、学学架构设计、写写博客——这才是实习该干的事。

---

### 五、手把手：你现在就能动手的5步

光看故事不够，来点干货。如果你现在就想写自己的第一个Skill，按这个步骤来：

**第一步：找到你每天重复做的事**

不用是什么高大上的事。越琐碎越好。比如"每天把Excel数据整理成固定格式"、"每次写commit message都要想半天"、"帮人检查代码格式"……

**第二步：把你脑子里的规则写下来**

别想着一步到位写Markdown。先拿张纸或者打开备忘录，用大白话写：你在做这件事的时候，脑子里在过哪些判断？

比如你要写一个"检查SQL"的Skill，你就想：我每次看一条SQL，第一眼看什么？第二眼看什么？什么情况我会说"不行"？什么情况我会说"可以"？

**第三步：写SKILL.md**

格式就三样东西：

```markdown
---
name: 你的skill名字（小写英文+短横线）
description: 一句话说清楚它干什么、什么时候用
---

# 标题

## 规则
（你第二步写的那些判断规则）

## 输出格式
（你希望结果长什么样）

## 示例
（给一两个真实例子）

第四步：放到正确的目录里

在你的用户目录下，找到 .qoderworkcn/skills/ 这个目录，在里面建一个以你skill名字命名的文件夹，把SKILL.md丢进去。

比如你写了个叫sql-review的Skill，路径就是：

~/.qoderworkcn/skills/sql-review/SKILL.md

Windows上就是 %USERPROFILE%\.qoderworkcn\skills\sql-review\SKILL.md

第五步：试一下，然后迭代

不用追求完美。先跑起来，看看AI的输出跟你预期差多少，然后改规则、加示例、调描述。一般迭代个两三轮就很好用了。

---

六、几个写Skill的"潜规则"

这些是我翻过文档、踩过坑之后总结出来的，文档里不一定有，但很实用：

name字段别乱起。 只能用小写字母、数字和短横线，最长64个字符。别用中文，别用大写，别用下划线。sql-review可以，SQL_Review不行。

description要写"什么时候触发"。 很多人只写了"这个Skill干什么"，忘了写"什么时候该用它"。AI是靠description来决定要不要加载你的Skill的，你不写触发条件，它就只能靠猜。

主文件控制在500行以内。 超过的话，把详细内容拆到单独的文件里。AI的上下文窗口是有限的，你的Skill只是它加载的众多信息之一，别抢别人的空间。

术语要统一。 别一会儿说"接口"一会儿说"API"一会儿又说"端点"，AI会懵。选定一个词，全文统一。

别写时效性内容。 比如"2026年7月之前用旧版API"这种，过期了就出问题。如果有新旧版本，用"当前方案"和"历史方案（已废弃）"这种结构来组织。

---

七、从"能用"到"好用"：我的一些进阶心得

写了几周Skill之后，我发现有一些模式特别好用，分享给你们：

"检查清单"模式。 如果你的Skill是做审查/检查类的，给AI一个checklist格式，让它逐项打勾。输出特别清晰，也不会漏项。

"如果-那么"分支模式。 如果你的任务有好几种情况要分别处理，别把所有规则混在一起写。用"情况A→走这条路"、"情况B→走那条路"的方式组织，AI理解起来更准确。

"先做再验"模式。 对于特别重要的操作（比如批量修改数据），你可以让AI先执行，再自己验证一遍结果，验证不通过就回滚。相当于给AI加了一道保险。

还有一个心得：好的Skill不是写出来的，是改出来的。 别指望第一版就完美。你用的过程中发现AI哪里做得不对，就去改规则。这其实就是一个"训练"的过程，只不过你训练的不是模型本身，而是给模型的说明书。

---

写在最后

回头看这一个月，写Skill这件事给我最大的收获不是"省了多少时间"——虽然确实省了很多。

真正的收获是，我开始用"能不能自动化"的视角去审视自己的工作了。

以前遇到重复劳动，我的反应是"忍着做完"。现在我的反应是"这个能不能写个Skill让AI帮我干"。这个思维转变，比任何技术都值钱。

说实话，实习生的工作大多确实琐碎。但你可以在琐碎中找到杠杆，用一个下午的时间写出一个Skill，然后接下来每天省下两个小时。这两个小时，拿来学源码、看论文、写博客、准备面试，哪样不比当复读机强？

最后送一句老周跟我说的话，也是我现在的工作信条：

“重复的事情做两遍，就该想想有没有第三遍的必要。”

共勉。