AI 给你写代码总差一口气?因为它根本没有说明书

开篇 我让 AI 写过 3 次测试，每次都不一样

我让 AI 写过 3 次单元测试。

第一次是一张表格。第二次是 3 段散文。第三次直接给我推荐结论。

同一个函数，同一段 prompt（提示词）。每次输出格式都不一样。

我一开始以为这是 AI 的「创意」。后来才知道——这叫 AI 不知道这事该怎么做。

这篇文章是「Claude Code Skills 实战 3 讲」的开篇，要讲清楚一件事：Skill 是什么，为什么 prompt 解决不了的问题，它能解决。

01｜痛点 AI 不是不会，是不知道怎么做

1.1 三个我反复踩的真实场景

场景一：让 AI 写单元测试

我让 AI 助手给一个函数写几个测试用例。听起来简单——你只是想要 it() 测试代码。

但 AI 实际要做的是：理解函数逻辑、设计测试场景（理想路径 + 边界情况）、编写符合项目风格的测试代码、验证覆盖率。

每次我都要重新解释一遍：「我要的不只是代码，还要完整的测试流程。」

跑 3 次，3 次结果不一样。第 4 次我放弃了。

场景二：批量整理 Markdown 文档

我说「把这 20 篇文档整理一下」，希望 AI 帮我做 4 件事：统一格式、提取关键信息、生成目录、检查链接有效性。

AI 做了什么？格式化了一下，结束。

我不能怪它——它确实没接到「提取关键信息」这道指令。但我每次都要把这 4 个步骤显式说明，就违背了「整理」这个词的本意。

场景三：让 AI 帮我找工具

我说「帮我找一个处理 PDF 的工具」，AI 推荐了一个。

我问：为什么是这个？

AI 答：因为它流行。

我心里直接反问：流行不等于适合我啊。

场景四：整理一份会议纪要

上周开了一个 1 小时的会，我让 AI 帮我整理纪要。

我期待的是：议题分类 / 关键决策 / 待办事项 / 责任人 / 截止日期 5 块结构。

AI 给我的是：500 字的散文，把所有人说过的话简单复述了一遍。

我问它「为什么没有结构化」，它说：「您没有要求结构化输出。」

这四个场景的共同点不是 AI 笨。是 AI 缺一份说明书——告诉它这类任务该怎么做、做到什么程度、什么算完成。

我后来反复想过一个问题：为什么我跟同事说「整理一下纪要」，他能马上给我结构化的 5 块？

因为他脑子里有一份《会议纪要模板》。这份模板是公司里反复跑出来、所有人默认知道的「行业惯例」。

AI 没有这份惯例。每次都需要从零开始猜「整理」是什么意思。

1.2 从技术视角看：3 个根本问题

我必须从架构层面再讲一层，因为这不只是「写指令不够清楚」的小事。

问题一：「巨型 prompt」灾难

如果你想让 AI 稳定输出，最直觉的做法是把所有规则、边界、流程全写进 prompt 里。

结果：prompt 越写越长，几千 Token 起步。

代价不是钱（虽然也是钱）。是 AI 的注意力分散——它面对一份 5000 字的指令时，会出现「中段失忆」（业内有个名词叫 Lost in the Middle），关键约束被静悄悄地忽略。

我必须说，这不是 AI 的能力问题，是 prompt 这种结构的天然缺陷。

问题二：「拥有工具」不等于「会用工具」

AI 现在有一堆外部工具：网页浏览、代码执行、文件读写、API 调用。

但拥有工具不等于知道专业地怎么用。

举个例子：AI 配了 SQL 执行工具，你让它「分析昨天的销售异常」。它会跑一个简单查询交差？还是会先做交叉验证再写报告？取决于它当时的「灵感」。

这不是工具的问题，是缺领域专家的操作智慧。

问题三：复用性、稳定性、可维护性

企业场景里，同一类任务一天可能跑 100 次。如果每次输出都不一样，这事就不能交给 AI。

需要的是：把资深专家的「隐性知识」转化成 AI 能理解的「标准操作流程」（SOP）。

这 3 个问题的共同本质是：当前架构缺一种「可插拔的领域专家大脑」。

这就是 Skill 要解决的事。

我不是在抱怨 AI 不行。事实上 AI 已经很强了——它能写代码、能理解需求、能调用工具。但「能做」和「稳定地做对」之间，差的就是这份说明书。

02｜定义 Skill 是给 AI 的「操作手册」

2.1 一句话定义

Skill = 一个可被 Agent 在运行时『发现、理解、调用、组合』的能力模块。

定义里有 4 个动作：发现 → 理解 → 调用 → 组合。每个动作都是 AI 自己完成的，不需要你手动指挥。

2.2 一个我反复用的类比

把 Agent（AI 智能体）想象成「刚入职的超级实习生」：

老板说「处理一下退款，发份财务报告」，实习生不会凭空猜——他从书架抽出《退款处理与报告生成 SOP》，照着步骤一步步用电脑和电话执行。

Skill 就是这本 SOP。

我认为这个类比比「手机 + App」的类比更贴切——因为手机 App 是给消费者用的，SOP 是给执行者用的。员工和 Agent 都是执行者，他们需要的是流程，不是娱乐。

让我把这个场景再演绎一遍，你感受一下「有 Skill」和「没 Skill」的差别。

没 Skill 的实习生：

老板说「处理一下退款」，他可能问：要走哪个系统？要不要老板审批？金额怎么核对？要不要通知客户？每问一个问题，老板就得回答一次。问到第 5 个，老板烦了：「你怎么什么都不会。」

有 Skill（也就是 SOP 文档）的实习生：

老板说「处理一下退款」，他从书架抽出《退款处理 SOP》，自己看一遍：先去 ERP 系统查订单、超过 500 元要老板邮件审批、按模板发退款通知给客户、退款完成后更新财务记录。

整个过程，老板说了一句话，实习生独立跑完。

两个实习生的区别不是智商，是手里有没有那份 SOP。AI 也一样。

2.3 Skill 的三大特性

后面所有内容，其实都围绕这三个词转。

特性一：可发现

Agent 能知道「我有这个能力，它适合干这事」——不只是「这个能力存在」。

实现靠的是 Skill 头部的描述字段（description，描述）。当用户说「帮我补充单元测试」时，AI 扫一遍所有 Skill 的描述，匹配到「测试驱动开发」这个 Skill。

特性二：可执行

进入 Skill 后，AI 不是自由发挥，而是有结构化流程支撑。

「测试驱动开发」Skill 里写得清清楚楚：第一步理解需求、第二步设计测试用例、第三步先写测试代码（红灯阶段）、第四步实现功能代码（绿灯阶段）、第五步重构。AI 必须按这个顺序走。

特性三：可复用

写一次，到处用。

你写好「测试驱动开发」Skill 后，这周用、下周用、新人也用、跨项目也用。同一份能力跨场景、跨任务、跨时间持续被调用。

这就是 Skill 比「一次性 prompt」更有价值的根本原因——一次性 prompt 写完就丢，Skill 写一次能用一年。

03｜对比 Skill 和 prompt 到底差在哪里

很多人会问：Skill 和 prompt 有什么区别？不都是「告诉 AI 怎么做」吗？

答案藏在 5 个维度里。

让我用一个具体场景说明——还是「补充单元测试」这件事。

用 prompt 的方式：

用户：「帮我给这个函数补充单元测试，要覆盖边界情况，要用 Jest 框架，要检查覆盖率，要……」

3 个明显问题：

• 每次都要重新描述需求，容易遗漏细节
• AI 可能理解偏差，执行不一致
• 下次类似任务，又要重新写一遍

用 Skill 的方式：

用户：「帮我补充单元测试」

Agent：识别到 test-driven-development（测试驱动开发）Skill

Agent：按 Skill 流程执行

3 个优势：

• 一句话触发，无需重复描述
• 流程一致，结果可预期
• 下次类似任务自动复用

我必须说清楚一件事——Skill 的核心价值不是「更长的 prompt」，是「可发现 + 可执行 + 可复用的能力模块」。

一个最简单的 Skill 长什么样

让你看一个真实的 Skill 文件——生成 Git 提交信息的 Skill，整个内容不超过 30 行：

---name:commit-message-generatordescription:基于暂存区的更改生成符合规范的提交信息---# 提交信息生成器## 目标生成清晰、符合最佳实践的规范化提交信息。## 工作流1.用gitdiff分析暂存区的代码更改2.识别提交的主要类型（feat/fix/docs/refactor/test）3.从被修改的文件中提取作用范围4.生成一条简明扼要的标题行（不超过50字符）5.如果逻辑复杂，可以加详细的正文说明## 约束-遵循ConventionalCommits格式：type(scope):subject-标题用祈使句（用"add"不用"added"）-标题严格控制在50字符以内-标题和正文之间用空行分隔

文件头有 2 个关键字段——name（Skill 名字）和 description（一句话描述）。AI 扫描所有 Skill 时，先看 description 决定要不要进来读详细内容。

下面是 3 个章节：目标（这个 Skill 要干什么）/ 工作流（按什么步骤）/ 约束（不能违反的规则）。

就这样。一份 30 行的文件，AI 就有了一个新能力。

写一个能用的 Skill 不需要写代码——你只需要写清楚「目标 / 工作流 / 约束」三件事。

Skill 的 3 种常见形态

我用了 4 个月、跑通了 100 多个 Skill 之后，发现 Skill 大致分 3 种形态。这 3 种形态决定了你创建一个 Skill 要花多长时间。

形态一：简单技能

只有一个 SKILL.md 文件，3-5 步线性流程，没有外部依赖。

刚才的「Git 提交信息生成器」就是典型代表。从想清楚到写完，5 分钟搞定。

适合：单一明确的任务，比如「生成 commit message」「检查代码格式」「写一段注释」。

形态二：多步骤工作流技能

也是单文件 SKILL.md，但工作流有 5-10 步，可能带分支判断。

比如「测试驱动开发」Skill：5 个阶段（理解需求 / 设计测试用例 / 写测试代码 / 实现功能 / 重构），每个阶段有明确的进入和退出标准。

适合：需要按规范流程协同的任务，比如「TDD 开发」「写公众号文章」「做需求调研」。从想清楚到写完，约 20 分钟。

形态三：资源依赖型技能

SKILL.md + 同级的资源目录（脚本、模板、数据文件）。

比如「HTML 交互课件设计」Skill：除了主文件，还有 templates/ 目录放 HTML 模板、patterns/ 目录放交互模式库、scripts/validate.py 做无障碍检查。

适合：需要复杂资源支撑的任务，比如「生成完整网站」「批量处理数据」「自动化运维流程」。从想清楚到写完，约 1 小时。

我必须强调一点：大部分人需要的是形态一和形态二，形态三只在少数情况用。

所以如果你刚开始接触 Skill，先写一个 30 行的简单技能，跑起来再说。不要一上来就模仿那些上千行的复杂 Skill——那是工程师做了几个月迭代的产物，不是入门起点。

我用 4 个月后的 3 个真实观察

我自己装了 100 多个 Skill 跑了 4 个月。这里讲 3 个我没看到别人讲过的、但每个 Skill 用户早晚会遇到的事。

观察一：装得越多越糊涂，不如装得对

我一开始的策略是「装就完了，反正不用」。结果装了 60 多个 Skill 之后，AI 开始出现 2 个症状：

第一，简单任务它非要去翻一个 Skill。比如我让它「写一句话总结这段文字」，它居然去翻「文档摘要 SOP」Skill，多走了好几步。

第二，相似 Skill 之间打架。我装了 3 个不同作者的「网页内容提取」Skill，AI 选谁都行——但每次选的不一样，输出格式也不一样。

后来我做了一次清理，砍到 30 个左右常用的，AI 反而更稳了。这是 Skill 反直觉的一面：多不等于强。

观察二：好 Skill 都长得像「岗位 SOP」，不像「教程」

很多人写 Skill 的时候，会按写教程的方式写——大段背景介绍、详细原理解释、各种示例代码。

这种 Skill 跑起来效果反而差。

好的 Skill 长得像公司里的标准流程文件：第一步做什么、判断条件是什么、第二步做什么、错了怎么办。一句废话都没有。

我的判断标准很简单——把这份 Skill 给一个新员工，他能不能照着做完事。如果中间有歧义，就要改。

观察三：写一个垃圾 Skill 也比不写强

很多人想写 Skill 但迟迟不动手，因为「我不知道写什么好」。

我必须说，第一个 Skill 你想都不用想，写「整理我的会议纪要」就行。

按你自己的会议结构（议题 / 决策 / 待办 / 截止日期）写 5 步工作流，30 行搞定。下次你说「整理纪要」，AI 就能稳定输出你想要的格式。

写完跑一次你就懂了。比读 5 篇 Skill 教程都管用。

路标 后面 2 篇会带你去哪里

系列承诺

3 篇正文，3 周读完。每篇有真实案例，每篇方法论可机械验证。

每一篇都从一个具体痛点出发，不堆砌理论。

后面 2 篇路线

写给读者的一段话

如果你最近也在用 AI 编程工具，遇到「prompt 写得越来越长」「同一类任务每次结果都不一样」「换台电脑或换个项目就崩」这些症状——欢迎在评论区留言你的具体场景。

我会把每一篇里读者反馈的真实痛点收进文章。这不是一次性的清单，是一个边写边改的系列。

Skill 不是银弹。我只是把这两年在 Claude Code 上跑通 100 多个 Skill 的真实路径，一段一段还原给你看。

下一篇见，第 2 篇。