AI 使用实战复盘——怎么写SKILL

写 Skill 最容易从正文开始。把步骤、禁区、语气、输出格式一股脑倒进去，写到一两百行，感觉这张卡很完整。

完整是给人看的感觉。一张卡要稳定干活，要把一个工作系统的六层都答上，而不是把说明书写厚。

Skill 就是把你反复要教 AI 的那套做法写成文件。Harness 是模型外面那套让它稳定干活的东西：该看什么、用什么工具、步骤怎么串、资料放哪、怎么知道做对了、出错怎么办。一个完整的 AI 工作系统有这六层。

写一张 Skill，就是搭一个微型 Harness。

麻雀虽小，六层俱全。每一层都在逼你回答一个具体问题。

下笔顺序不是按层号从 1 排到 6。工具是第 2 层，配脚本却排在第 4 步，因为先有重复，再有脚本。评估是第 5 层，验证却放最后，因为卡还没写完，测无从谈起。骨架就是这六步：

| 架构层      | 这一层管什么        | 写卡时你要回答       | 对应步骤                  |
| -------- | ------------- | ------------- | --------------------- |
| L1 信息边界  | AI 该看什么、不该看什么 | 它怎么知道现在该用这张卡  | 第 1 步 · 写 description |
| L3 执行编排  | 多步骤任务怎么串      | 正文按什么节奏写，写多死  | 第 2 步 · 写正文           |
| L4 记忆与状态 | 大量资料放哪、何时加载   | 大段参考塞卡里还是拆出去  | 第 3 步 · 拆参考文件         |
| L2 工具系统  | 怎么跟外部世界交互     | 哪些动作值得固化成脚本   | 第 4 步 · 配脚本           |
| L6 约束恢复  | 出错怎么办         | 意外发生时，默认行为是什么 | 第 5 步 · 写失败处理         |
| L5 评估观测  | 怎么知道做对了       | 写完怎么验证它真能用    | 第 6 步 · 验证迭代          |

第 1 步 · L1 信息边界：先写 description

这一层管 AI 该看什么、不该看什么。落到写卡上，问题是：它怎么知道现在该用这张卡。

文件头上有一段 description，人话讲就是开关：做什么、什么时候用、用户会说的原话、什么时候不用。

平时 AI 只能看见每张卡的名字和这段大约 100 词的说明。正文是被叫起来之后才加载的。何时使用写在正文里，等于没写。

Claude Code、Codex、WorkBuddy、Trae 这几家帮你生成 Skill 的工具，在这点上说法几乎一样：description 是主要触发机制。Claude Code 甚至会拿大约 20 条该触发、不该触发的原话，去反复测这段开关准不准。

写成广告语，AI 没法判断。比如”强大的文档处理技能，智能化，支持多格式”。换成能对上的话，要落到动作：新建一张卡、改已有的卡、跑评测时使用。Trae 社区版还会多写一句反例，别拿去做普通写代码、写文档。

有个评测结论：模型天生欠触发。宁可把用户可能的说法多列几种。”写小红书笔记、做封面、改排版时使用”，比”用于内容创作”更容易被叫起来。

这一层还有一个更安静的死法。description 里有个冒号没加引号，文件可能被静默丢掉。目录里还躺着，对话里一次都点不到。你还在改正文里的步骤，AI 连这张卡在不在都不知道。

遮住正文只看 description，问自己用户说哪句话会命中。超过三句话才说得清，写得太抽象，重写。

第 2 步 · L3 执行编排：再写正文

这一层管多步骤任务怎么串。落到写卡上，问题是：正文按什么节奏写，写多死。

开关命中之后，AI 才读正文。这时候内容通常不缺，缺的是你敢把指令写多死。

Codex 给了三档，我觉得够用。

• 高自由度只讲目标和方法，适合写文案、做设计。

• 中自由度规定步骤，不锁每一处细节。

• 低自由度给精确命令和护栏，一步都不能偏，适合发布、删除、支付这类错了代价很大的事。

判断标准就一句：任务越脆弱，指令写得越死。写文案的卡别锁死用词。付款、删文件的卡别只写”小心一点”。

定完松紧，正文不必自己发明结构。DeepSeek 那批实战卡里，反复出现同一套五段：

1. 开场白：它是什么、不是什么。有的卡会补一句，这是指导，不是剧本。

2. 规则在哪：给路径，别把整份规范抄进卡里。指路，别抄路。

3. 边界：管什么，更要写不碰什么。

4. 步骤：编号。每步一个动作，或一个判断标准。宁可少而准。

5. 汇报：做完交代什么。别只丢一句”已完成”。

语言上有两条我跟着走。用祈使句，”先确认主题，缺信息就停下问”，别写成”主题是应该被确认的”。解释为什么，少堆大写的 ALWAYS / NEVER。给理由，AI 才能在你没写到的场景里做判断。

把卡交给一个不了解背景的人，或者另一个 AI，让它照着跑一次。它卡在哪一步反复问你，那一步就写松了。

第 3 步 · L4 记忆与状态：拆参考文件

这一层管大量资料放哪、何时加载。落到写卡上，问题是：大段参考塞卡里，还是拆出去。

正文写完如果超过大约 500 行，或者出现大段示例、表格、术语表，别硬塞。Codex 有句话我记得很清楚：上下文窗口是公共资源。你往卡里多塞一段废话，AI 干活时能用的上下文就少一段。

原则很朴素。正文放主干，细节放到参考文件，用到再加载。信息只放一处。正文和参考文件两处都有，以后改一处忘一处。偶尔才查的，全部搬走。参考文件特别长时，正文里给怎么查的提示，比如关键词，别让它通读。

问自己：这段内容是每次都要看，还是偶尔才查。偶尔才查的，搬出去。

第 4 步 · L2 工具系统：配脚本

这一层管怎么跟外部世界交互。落到写卡上，问题是：哪些动作值得固化成脚本。

它排在第 4 步，原因很简单：先有重复，再有脚本。信号很土：同一件事在多个测试里被 AI 反复现写，就固化进脚本。脚本不进上下文，直接执行，等于把最确定的部分从自由发挥里摘出来。

这一步很多人可以先跳过。一旦写了，三条必须守：有副作用的操作前先校验输入；成功失败都打印清楚，别让 AI 猜结果；至少真实跑过一次成功路径和一次失败路径。没测过的脚本，不要绑进流程。

需要 AI 判断的，留在正文里用文字教。每次都一模一样的，才配做成脚本。

第 5 步 · L6 约束恢复：写失败处理

这一层管出错怎么办。落到写卡上，问题是：意外发生时，AI 的默认行为是什么。

大多数卡只写了一切顺利时怎么办。缺信息时如果没写默认动作，AI 会猜。猜完还继续往下做，就是翻车。

三条够用。

• 缺信息：停下问一句。

• 超边界：不碰，报告，把禁区写死。

• 执行失败：保留报错原文停下，绝不假装成功。

写法不用花。用户没说清主题，问一句再动笔。要改的文件在禁区里，跳过并在汇报里说明。脚本报错，把原文贴出来，停下等指示。故意扣掉某一步需要的信息，看它下一步干什么。卡上没写，它就会自己补。

决定一张卡下限的，是这一层，不是正文写了多长。

第 6 步 · L5 评估观测：验证与迭代

这一层管怎么知道做对了。落到写卡上，问题是：写完怎么验证它真能用。写完不等于能用。

最低配是触发测试：用真实口吻说一句该触发的话，看卡会不会加载；再说一句不该触发的，看会不会误加载。中配是先写 3 到 5 个评测用例，黄金路径、边界、不该触发的负例，过了才算写完。高配是同一任务带卡和不带卡各跑一遍，看通过率、耗时、用量。

改卡时别为某一次翻车加一条只适用那次的规矩。Claude 的教训是，技能可能被用一万次，补丁打偏了，其他正常场景会一起坏。问这次翻车缺的是哪类判断，补那一类，不要补那一次。

真实任务里用，发现卡壳，回来改，再用。卡和文章一样，第一版都是草稿。上限由这一层决定：你肯不肯拿真实任务打回去。

六步合成一张最小的卡

需要落文件的时候，骨架可以小到这样。行尾标的是对应哪一步、哪一层：

---
name: 和目录名一致
description: "做什么。当用户说出哪些原话时使用。不要用于哪些事。"  # 第1步 L1
---

# 标题
一句话：它是什么、不是什么                         # 第2步 L3 开场白

## 规则在哪                                         # 第3步 L4
- 指向模板或规范的相对路径，不复述内容

## 边界                                             # 第5步 L6 禁区
- 管什么
- 不碰什么

## 步骤                                             # 第2步 L3
1. 动作 + 判断标准
2. 重复性操作调用脚本（没有就不写）               # 第4步 L2

## 出了意外怎么办                                   # 第5步 L6
- 缺关键信息 → 停下问，不要猜
- 操作失败 → 保留报错原文，停下汇报

## 做完汇报                                         # 第2步 L3
- 做了什么、改了什么、跳过了什么

参考文件和脚本都是可选件。用不上就不建。第 6 步不写进文件里，写完用真实任务跑一次，该触发的触发，不该的不误触，哪里卡改哪里。

发布前过一遍这些就够了：

• 只看 description，能说清谁会叫它

• 写了何时用，必要时写了何时不用

• 含冒号的 description 已加引号

• 正文按这件事的脆弱程度写过松紧

• 步骤里没有”处理一下”这种含糊动词

• 写了不碰什么；缺信息时默认是问

• 每条信息只出现在一个地方

• 偶尔才查的已经拆走

• 做完要汇报什么已经写明

• 用真实口吻做过触发测试

核心是这样子。一个 Skill 就是一个微型 Harness。

六层不是理论，是六道写作题：

触发、编排、记忆、工具、恢复、评估。

下笔顺序按六步走，不按层号走。

上下文是大家共用的。卡的下限由失败处理决定，上限由你肯不肯拿真实任务打回去。

你最近写的那张卡，六层里哪一层还是空的？