1.2 跑通第一个技能 · 波仔的 AI 编程实战课

📄 一句话概括

同一段会议转承稿，直出是一坨，按技能跑是四段式纪要。差别不在模型，在于你有没有提前把「要什么形状」写清楚。这一篇从零建这个技能，再把它放进一个三技能的库里，看它被不被选中——以及在什么情况下选不中。

📝 本章和前面几章的关系

上一篇把环境铺好了，这一篇开始动真格。技能的最小单位是「一个文件夹 + 一个 SKILL.md」，没有任何代码也能跑起来。这一点很关键：它意味着写技能的门槛是「会不会把要求说清楚」，不是「会不会编程」。

一、不用技能的时候，发生了什么

你把一段会议转承稿丢给智能体，说「帮我整理成纪要」。它给你一段话，什么都说了，什么都不突出。这不是它不聪明。它只是不知道你要什么形状——你没有告诉它。没有技能的时候，它会挑一个「最常见」的形状给你。而「最常见」对你不一定有用。于是你开始补要求：议题单列、结论只放定了的、待办写负责人。补完发现这段话你上周说过一遍，上上周也说过一遍。技能就是把这段重复的要求，一次性写进一个文件里。

二、一份最小可用的 SKILL.md

最小可用的技能，只需要两部分：frontmatter 三行，加一段正文。

---
name: meeting-minutes
description: 把带说话人前缀的会议转承稿整理成四段式纪要……
---

## 你拿到的是什么
一段带说话人前缀的转承稿，一行一句，格式是「姓名：内容」。

## 你要产出什么
严格四段：议题、结论、待办、风险。

## 三条硬规矩
1. 不编造。转承稿里没有的数字、日期、人名一个都不许出现。
2. 结论段只放已经定了的，拿不准就放风险。
3. 全文不超过 400 字。

就这么多。没有一行代码，没有依赖，没有配置文件。 name 是技能的名字，description 是它的广告词，正文写规矩。 正文里的规矩要用否定句写。「不编造」比「准确」有用，「只放定了的」比「分清主次」有用。因为肯定句描述的是一个理想状态，否定句描述的是一条具体边界。模型对边界的反应更稳定。

三、从建好到被选中，中间隔了三步

技能写好放在那儿，不会自己跑起来。中间有三步。 第一步，被扫到。客户端启动时扫技能目录，只认 SKILL.md 这个文件名。名字差了、层级错了，扫不到，后面全白搭。 第二步，被选中。它不会把所有技能的正文都读进来——那样上下文立刻爆掉。它拿到的是一张清单：每个技能的名字和 description。然后它判断这一次该用哪个。 第三步，被读进来。选中之后才去读这个技能的 SKILL.md 正文，按里面的步骤干活。这三步决定了技能写作的重心：description 决定选不选得上，正文决定干得好不好。大部分人写技能只盯正文，结果技能写得挺好，就是没人用——问题在第二步。

四、没生效，先查这三处

技能没生效，九成是三个原因，而且都能在一分钟内查出来。 文件名不对。只能是 SKILL.md。叫 README.md、skill.md.bak、SKILL.MD 都可能不被认。 层级不对。通行约定是「一个技能一个子目录」，SKILL.md 放在子目录里，不是库根目录。 description 写歪了。写得太虚（「处理文本」）谁都不要；写得太宽（「各种文字工作」）到处抢活。前两个是硬错误，扫都扫不到。第三个是软错误，扫得到但选不中，最难查。所以每次改完技能，第一件事是问一句「你现在有哪些技能」。能看到它，说明前两关过了；看不到，问题一定在前两关。

五、装别人的技能，先读三样东西

社区里的技能可以直接下载来用。装之前花两分钟读三样东西，能躲掉大部分坑。 第一样，description。看它说自己什么时候用。和你手上的活对不上，就别装。 第二样，正文里的规矩。特别是那几条「不许做什么」，这是它的边界。 第三样，它引用了什么文件、跑什么脚本。这一步最容易被跳过，也最危险。一个技能如果在正文里写「运行 scripts/xxx.py」，而你没读过那个脚本，等于让一个陌生人写的程序在你的机器上跑。装之前至少打开看一眼。技能是文本，读起来比代码快得多——这个便宜不占白不占。

六、动手 Demo：从零建一个会议纪要技能，再看它被不被选中

这一段真跑四件事：同一段转承稿直出一次、写一份 SKILL.md、按模板再跑一次、放进三技能库里看选中谁。最后再加一段「三种没生效」的实测，把上面讲的三种原因逐个跑出证据。

# 技能库里长这样
skills/
  meeting-minutes/SKILL.md
  weekly-report/SKILL.md
  polish/SKILL.md

# SKILL.md 就三段：frontmatter、规矩、边界
---
name: meeting-minutes
description: 把带说话人前缀的会议转承稿整理成四段式纪要……
---

实跑输出：

--------------------------------------------------------------------
从零建一个会议纪要技能，再看它被不被选中
--------------------------------------------------------------------


  ① 先不用技能：把转承稿丢进去直出
  --------------------------------------------------------------------
  会议内容如下：今天主要三件事，一是七月的推广预算，二是新版本的发布时间，三是客服那边的投诉。
  预算这块，市场部报了八十万，财务说最多六十万，差二十万。那就先按六十万做，剩下的看效果再加。
  看出来了吧：谁说的、说定了什么、谁要去做，全糊在一段话里。
  这不是模型不行，是它不知道你要什么形状——你没告诉它。

  ② 写 SKILL.md：frontmatter 三行，正文写规矩
  --------------------------------------------------------------------
  ---
  name: meeting-minutes
  description: 把带说话人前缀的会议转承稿整理成四段式纪要：议题、结论、待办、风险。
  当用户给出会议记录、录音转写稿、讨论稿，要求整理成纪要或待办时使用。
  ---

  # 会议纪要

  ## 你拿到的是什么
  一段带说话人前缀的转承稿，一行一句，格式是「姓名：内容」。

  ## 你要产出什么
  严格四段，顺序不能变，每段用二级标题：

  ## 议题
  编号列出会上讨论到的事项，一句话一条，不写谁说的。

  ## 结论
  只写已经定下来的事。没定下来的写进风险，不要写进结论。

  ## 待办
  每条以 - [ ] 开头，格式是「负责人：要做的事 + 时间」。
  说话人里出现「我来」「牵头」「下周」的，基本都是待办。

  ## 风险
  没关掉的问题、没谈拢的差额、明确表达不满的地方。

  ## 三条硬规矩
  1. 不编造。转承稿里没有的数字、日期、人名，一个都不许出现。
  2. 结论段只放「已经定了」的，拿不准就放风险。
  3. 全文不超过 400 字，超过就说明你在复述，不是在提炼。
  整个技能就这么多：三行 frontmatter，加一段用中文写的规矩。没有代码。

  ③ 同一段转承稿，按技能里的模板再跑一遍
  --------------------------------------------------------------------
  ## 议题

  1. 今天主要三件事，一是七月的推广预算，二是新版本的发布时间，三是客服那边的投诉。
  2. 预算这块，市场部报了八十万，财务说最多六十万，差二十万。
  3. 新版本原定八月十号，测试还有十四个阻塞问题没关，我觉得要往后推一周。
  4. 客服投诉主要是退款流程太慢，平均要五天，用户很不满。

  ## 结论

  - 预算按六十万先做，看效果再加
  - 新版本推到八月十七号

  ## 待办

  - [ ] 张伟：推一周，八月十七号发。这个我来跟老板说。
  - [ ] 张伟：退款流程让王强牵头，两周内出个简化方案。
  - [ ] 王强：行，我下周先拉个会。

  ## 风险

  - 预算这块，市场部报了八十万，财务说最多六十万，差二十万。
  - 新版本原定八月十号，测试还有十四个阻塞问题没关，我觉得要往后推一周。
  - 客服投诉主要是退款流程太慢，平均要五天，用户很不满。
  直出 202 个字符、一段话；按模板 23 行、四段、3 条待办。
  注意这里的规则脚本只按字面抓线索：它把「张伟：推一周，八月十七号发。
  这个我来跟老板说」算成了待办，其实前半句是结论。
  真机上是模型读你的 SKILL.md 之后自己判断，这种混淆会少很多，
  但规矩写不清的时候，模型犯的是同一类错——把结论和行动混在一起。
  ! 技能没有让模型变聪明，它只是把「你要什么形状」提前写清楚了。
  ! 这就是技能最朴素的价值：把每次都说不清的要求，一次性说清楚。

  ④ 三个技能放一个库里，看它选中谁
  --------------------------------------------------------------------
| 技能 | description 字数 | 开头 |
|---|---|---|
| meeting-minutes | 68 | 把带说话人前缀的会议转承稿整理成四段式纪要：议题、结论、待办、风险。 |
| polish | 50 | 给中文文章做润色：改掉翻译腔、删掉套话、把长句拆短。当用户说润色、改 |
| weekly-report | 58 | 把一周的零散工作记录整理成周报，按「本周完成、下周计划、需要支持」三 |


  请求：帮我把今天这段会议记录整理一下，出一份纪要
    0.278  meeting-minutes
    0.167  weekly-report
    0.000  polish

  请求：这周的活儿太杂了，帮我写成周报
    0.250  weekly-report
    0.000  polish
    0.000  meeting-minutes

  请求：这段话读起来一股翻译腔，帮我润色一下
    0.200  polish
    0.000  weekly-report
    0.000  meeting-minutes
  三条请求各自都把对的技能排到了第一，分差也不小。
  ! 这个打分是本沙箱用「两字滑窗重合」算的，不是模型判断。
  ! 真机上是模型拿「请求 + 全部 description」比一次，语义比字面强得多。
  ! 这里能信的只有排序，绝对值没有意义——换一套分词，分数全变。

  ⑤ 技能没生效，九成是这三种
  --------------------------------------------------------------------
  第一种：description 写歪了——太虚，或者太宽
    请求 1：帮我把今天这段会议记录整理一下，出一份纪要
      0.278  meeting-minutes
      0.000  vague
      0.000  broad
    请求 2：帮我把这段话润色一下，改得自然点
      0.077  broad
      0.000  vague
      0.000  meeting-minutes
  「处理文本内容」两个请求都是 0.000——写得太虚等于没写，谁都不会选它。
  「各种文字工作」在润色请求上拿到 0.077，是这个库里唯一得分的那个。
  库里一旦再加一个正经的润色技能，它就会跟对方一起被端上去；
  模型看到两个都能干，选错就是这么来的。
  ! description 要写成「这个技能只干这一件事」，不是「越全越好」。

  第二种：目录里根本没有 SKILL.md
  文件叫 README.md，扫描器扫出 0 个技能。
  ! 文件名必须是 SKILL.md。本沙箱这个扫描器不分大小写，
  ! 真机上的枚举按字面比，名字差一个字母就是找不到。

  第三种：文件放错了层
  SKILL.md 直接扔在 skills 根目录，扫描器还是能扫到 1 个。
  因为递归扫描不挑层数。但真机上枚举技能是按「一层子目录一个技能」来的，
  根目录下那份不会被当成技能——这条本沙箱验不了，只能说扫描器不认这个约定。
  ! 统一写成 skills/<技能名>/SKILL.md，三家平台都认这个形状。

第一段是「不用技能」的直出：两百来字连成一段，谁说了什么全糊在一起。第二段把完整的 SKILL.md 打了出来——三行 frontmatter，四段规矩，就这么多。第三段是按模板跑的结果：四段、23 行、3 条待办。 注意那条被误判的待办：脚本把「推一周，八月十七号发。这个我来跟老板说」整句当成了待办，其实前半句是结论。规则脚本只按字面抓线索，分不清句子内部的主次。真机上是模型读完你的 SKILL.md 自己判断，这种混淆会少很多；但规矩写不清的时候，模型犯的是同一类错——把结论和行动混在一起。第四段是三个技能各配一条请求的打分。三条请求各自都把对的技能排到了第一。这个打分是本沙箱用「两字滑窗重合」算的，不是模型判断，能信的只有排序。第五段是三种没生效。第一种里「处理文本内容」两个请求都是 0.000——写太虚等于没写；「各种文字工作」在润色请求上拿到 0.077，是那个库里唯一得分的，这就是会抢活的写法。第二种把 SKILL.md 改成 README.md，扫描器扫出 0 个技能。第三种把 SKILL.md 扔在库根目录，扫描器还是扫到 1 个—— 因为递归扫描不挑层数。但真机枚举技能是按「一层子目录一个技能」来的，根目录那份不算。这一条本沙箱验不了，只能说扫描器不认这个约定，别赌。

30 秒实验

把你上周重复说过三遍的那段要求，写成一份 SKILL.md。不用代码，只写规矩。
把 description 先写得很虚（「处理文本」），跑一次；再写成具体的一句话，跑一次。对比选中结果。
把你装的第一个第三方技能打开，找到它引用的脚本，读一遍。读完再决定留不留。

常见误区

把技能写成一篇教程。技能不是给人看的文章，是给模型看的作业要求。步骤能短则短，规矩能硬则硬，铺垫和背景一律删掉。
description 写成技能名的扩写。meeting-minutes 配「会议纪要技能」，等于什么都没说。 description 要写「什么时候用它」，不是「它叫什么」。
一次写五个技能再一起测。五个一起不生效，你根本不知道是哪个的问题。一次一个，每加一个问一次「有哪些技能」。

自测三问（点开对答案）

1. 技能从写好到跑起来，中间有哪三步？ —— 被扫到（认 SKILL.md 与目录层级）、被选中（比 description）、被读进来（读正文）。 description 决定第二步，正文决定第三步。 2. 为什么正文里的规矩要用否定句写？ —— 肯定句描述理想状态，否定句描述具体边界。「不编造」比「准确」可执行，模型对边界反应更稳。 3. 装第三方技能，装之前必须读哪一样？ —— 它引用的文件和脚本。没读过就让别人的程序在你机器上跑，这是唯一可能造成实际损失的一步。

下一篇把技能文件夹整个拆开：三段结构各占多少、被引用的文件怎么组织、两个作用域同名时谁赢。

☐ （本篇完，下一篇 1.3 打开技能文件夹看看）