文章总结： 文章分析了AI不执行用户编写Skill的5个常见错误：description字段过于模糊、文件超过300行、缺少具体输出示例、指令存在冲突（Skill与CLAUDE.md/SystemPrompt层次不清）、以及缺乏多说法测试。引用Karpathy的4条规则（先想再写、极简优先、精准修改、目标驱动）说明规则越精简AI越易遵守。核心结论是好的Skill不在于详尽而在于精准，建议从改写description入手，用5种不同说法测试确保执行一致性。 综合评分： 74 文章分类： AI安全,安全开发
你写的Skill AI看不懂——5个常见坑和改法
原创
6曦轩 6曦轩
6曦轩
2026年8月29日 00:00 广东
在小说阅读器读本章
去阅读
在公众号小说中沉浸阅读
你花了一下午写的 Skill，AI 根本不执行。
不是 AI 笨，是你的 Skill 写得有问题。
这篇文章，教你写出 AI 真的会执行的 Skill。
小张坐在工位上，咖啡已经凉了。
他盯着屏幕上的 SKILL.md 文件，第 287 行。三个小时前他开始写这个 Skill，教 AI 助手帮团队处理 PDF 报告的提取和归档。他觉得自己写得很用心，把每一步都交代清楚了，从文件类型判断到输出格式，事无巨细。
他保存，退出，在对话里输入，“帮我把这份 Q3 财报提取成结构化数据”。
AI 回复了一段话。
跟 Skill 里写的完全没关系。
他又试了一次。换个说法，换个问法，甚至把 PDF 直接拖进去。AI 依然我行我素，好像那个 Skill 根本不存在。
小张往后一靠，椅子吱嘎响了一声。他不是第一次遇到这种情况了。之前写过一个处理 Excel 的 Skill，也出现过类似的“已读不回”。当时他以为是模型版本的问题，换了个模型好了。这次换了三个模型，都不管用。
他打开社区论坛，搜了一圈。
发现不只是他。
问题出在哪
Skill 这个概念，用过 Claude Code 或者 OpenClaw 的人应该不陌生。简单说，它就是一份 Markdown 文件，告诉 AI 在遇到特定场景时该怎么干活。你可以把它理解成给 AI 写的一份“操作手册”。
问题在于，大多数人写操作手册的方式，是错的。
社区里有个流传很广的说法，写 Skill 最难的不是懂技术，是懂“怎么让另一个智能体读懂你在说什么”。这跟写代码不一样。代码是给机器执行的，编译器不跟你讲情面，错了就是错了。Skill 是给一个有理解能力的 agent 读的，它可能会“理解”你的意思，但这个理解跟你想要的，可能差了十万八千里。
写代码你习惯了精确，写 Skill 你需要的是“恰到好处”。太粗了 AI 不知道怎么干，太细了 AI 会被信息淹没，抓不住重点。
Karpathy 之前总结过 4 条规则，被社区广泛传播。那 4 条规则看上去很简单，但每一条背后都有故事。
Karpathy 的 4 条规则
Andrej Karpathy，前 Tesla AI 总监，前 OpenAI 研究员。他最近在做 Eureka Labs，一个 AI-native 的学校项目。他写了一个叫 eureka-workflows 的仓库，教 AI 助手怎么在编码时保持纪律。这个仓库社区 fork 迭代，衍生版本累计超过20 万星，已经超过了绝大多数人。
他的 4 条规则是这样的。
- 1. Think Before Coding——先想再写。不假设、不隐藏困惑、有歧义先问。
- 2. Simplicity First——极简优先。写最少的代码解决问题，不加没被要求的东西。
- 3. Surgical Changes——精准修改。只改该改的，不“顺手优化”旁边的代码。
- 4. Goal-Driven Execution——目标驱动。先定义“成功长什么样”，循环验证直到通过。
Think Before Coding：先想再写
这条听起来像废话，但你仔细看社区里那些失败的 Skill，一半以上的问题出在这。写 Skill 的人以为自己说清楚了，实际上有一堆隐含假设没写出来。比如你说“处理 PDF 文件”，什么 PDF，扫描件还是文字版，几页还是几百页，需要 OCR 吗。这些你心里知道，但 AI 不知道。
Simplicity First：极简优先
这条对 Skill 同样适用。很多人写 Skill 的时候有一种冲动，想把所有可能的情况都覆盖到。“如果用户遇到 A 情况就这样处理，遇到 B 情况就那样处理，如果同时遇到 A 和 B 就……”写着写着就写成了一个 if-else 地狱。
AI 不需要你预判所有可能性，它需要你把核心路径说清楚，边角情况它自己能推理。
Surgical Changes：精准修改
写 Skill 的时候，这条对应的是“边界感”。你的 Skill 管什么，不管什么，要画清楚。我见过一个 Skill，目标是帮用户发邮件，结果里面写了半页关于怎么在邮件里用 markdown 格式化的内容。这跟发邮件有关系吗，有。但那是另一个 Skill 的事。
Goal-Driven Execution：目标驱动
这一条最容易被忽略。大部分 Skill 只有“过程描述”，没有“结果定义”。你告诉 AI 第一步做什么第二步做什么，但没告诉它做完了怎么判断成功。AI 执行完了一堆步骤，它自己也不知道做对了没有。
这 4 条规则表面上在讲编码纪律，底层逻辑其实是同一个东西：减少不确定性。让 AI 在每一步都知道自己该干什么、干到什么程度算完。
5 个致命错误
说完了原则，来说具体的。
我翻了社区里上百个 Skill，加上论坛和 Discord 里的吐槽帖，总结了 5 个最致命的问题。说“致命”不是夸张，因为只要踩中一个，你的 Skill 基本就废了。
第一个，Description 写得太模糊
Skill 文件开头都有一个 description 字段，告诉 AI 这个 Skill 是干什么用的。AI 靠这个字段判断什么时候该加载你的 Skill。
我见过这样的 description，“帮助处理各种文档”。
这是什么意思，处理什么文档，怎么处理，转 PDF 还是从 PDF 提取。这句话等于没说。AI 看到这种描述，要么根本不加载你的 Skill，要么在不该加载的时候加载了。
正确的写法应该具体到场景。 比如，“从 PDF 格式的季度财报中提取关键财务数据，输出为 JSON 格式”。你看，一下子就知道什么时候该用、什么时候不该用。
好的 Skill 应该像给新队友的说明，不是给机器的伪代码。你想想，如果团队来了一个新人，你会怎么跟他交代工作——“小张，帮忙处理一下文档”。他不会懂的。你会说，“小张，每周五下午把客户发来的 PDF 合同里的付款条件提取出来，填到这个 Excel 表里”。
Skill 的 description，就应该是后面这种。
第二个，文件太长
社区的共识是 300 行以内。 超过这个数，AI 的注意力就开始分散。
我知道你想说什么，“我的场景很复杂，300 行写不完”。场景复杂我理解，但 300 行写不完通常意味着你试图在一个 Skill 里解决太多问题。拆。一个 Skill 干一件事，干净利落。
我见过一个800 行的 Skill，里面同时包含了邮件处理、日程管理、会议纪要生成三个功能。作者可能是觉得“放在一起方便管理”。对你是方便了，对 AI 来说是一场灾难。它在 800 行里找跟自己当前任务相关的部分，找到最后大概率找错。
第三个，缺少具体示例
这条可能是最重要的。
示例比指令管用。这不是我的观点，是社区里反复被验证的事实。你写 10 行指令告诉 AI 该怎么格式化输出，不如直接给它看一个格式化好的例子。
反面案例。你在 Skill 里写，“输出结果要结构化，便于阅读”。
什么叫结构化，什么叫便于阅读。每个人的理解都不一样。
正确做法是直接贴一个例子。
# 正确的做法：直接给示例
示例输出:
报告名称: "2025 年 Q3 季度财报"
提取日期: "2025-10-15"
关键数据:
营收: "¥3,200 万"
净利润: "¥480 万"
同比增长: "+12.3%"
风险提示: ["应收账款周期延长", "原材料成本上升"]
AI 看了这个例子，比看你写 500 字描述“什么是结构化输出”都管用。它会模仿你的格式、你的字段命名、你的粒度。
示例是最强的指令。
第四个，指令冲突
这个问题比较隐蔽，但杀伤力很大。
当你的 Skill 文件里有两条规则互相矛盾的时候，AI 不会报错，它会随机选一个执行。你测试的时候可能正好走了一条规则的路径，觉得没问题。换个输入，它走了另一条，你就懵了。
常见的冲突比如：前面写了“遇到不确定的情况要问用户”，后面又写了“尽可能自动完成任务不要打断用户”。这两条放在一起，AI 到底问不问？
还有一种冲突是跨文件的。你的 Skill 里写了一套规则，CLAUDE.md 里又有一套，System Prompt 里还有一套。三套规则对同一件事的要求不一样，AI 就会在三个来源之间左右横跳。
这就要说到 Skill、CLAUDE.md 和 System Prompt 的区别了。
| 特性 | Skill | CLAUDE.md | System Prompt | | — | — | — | — | | 干什么的 | 教 AI 做一件具体的事 | 项目级规则和规范 | 修改 AI 的通用行为 | | 什么时候生效 | 上下文匹配时自动加载 | 始终生效，每次对话都读 | 始终生效，每次对话都读 | | Token 消耗 | 未加载时只占少量 token | 持续消耗，越长越贵 | 持续消耗，越长越贵 | | 可复用性 | 可版本控制、可分享 | 跟项目绑定 | 跟会话绑定 |
这三层各有各的管辖范围。Skill 管具体任务，CLAUDE.md 管项目规范，System Prompt 管通用行为。如果你把任务逻辑写进了 CLAUDE.md，或者把项目规范写进了 Skill，迟早会打架。
分清楚层次，冲突就少了。
第五个，不测试
这条放在最后，因为它最不应该出现，但也最普遍。
不测试的 Skill 等于没写。
我知道写 Skill 的人很多是开发者，写代码都会测试。但写 Skill 的时候，不知道是什么原因，大家就默认“我写得这么清楚了，应该没问题吧”。
“应该没问题”，这四个字是 bug 之母。
你需要测试的场景至少包括：
- • 正常输入会不会按预期执行
- • 边界输入会不会崩溃
- • 模糊输入会不会给你有意义的反馈
跑三遍，每次换个说法，比写 300 行指令管用。
社区有个哥们分享了他的方法，写完 Skill 之后，用5 种不同的说法描述同一个需求，看 AI 是不是都能走到正确的路径上。如果 5 种说法结果一致，这个 Skill 基本就稳了。
我觉得这个方法值得抄。
几个可以马上做的事
如果你也遇到了“Skill 写了但 AI 不执行”的问题，可以试试这几步。
- 1. 检查 Description 字段。 打开你的 Skill 文件，只看 description 字段。找一个不了解这个项目的朋友，让他读完这段描述，问他“你觉得这个 Skill 什么时候该被加载”。如果他答不上来，或者答错了，重写。
- 2. 数行数。 数一下你的 Skill 有多少行。超过300 行，考虑拆。一个 Skill 只干一件事，这不是一句口号，是用 token 消耗换来的教训。
- 3. 加示例。 检查你有没有给示例。如果没有，现在就加一个。不用很完美，一个最简单的“期望输出”就行。AI 的模仿能力比你想象的强，但你得先给它一个可以模仿的对象。
- 4. 检查冲突。 把你的 Skill 跟 CLAUDE.md 和 System Prompt 摊在一起看。有没有对同一件事说了两种话的地方。如果有，决定它归谁管，从其他地方删掉。
- 5. 5 种说法测试。 用 5 种不同的说法测一遍。不是 5 个不同的需求，是同一个需求的 5 种说法。“帮我提取这份 PDF 的数据”“把这个财报里的数字拿出来”“Q3 报告结构化处理一下”——换着花样来。结果一致才算过关。
一个值得关注的信号
你知道 Karpathy 的那个 Skill 仓库为什么火了吗。
因为他的 SKILL.md 只有4 条规则，不到50 行。
有人拿他的版本去测试，发现 AI 的执行准确率比那些几百行的“详尽版”高出很多。原因不复杂：
规则越少越清晰，AI 越容易遵守。规则越多，AI 越容易在规则之间迷失。
这跟管理团队的逻辑是一样的。你给一个新人 50 页的操作手册，他看完也记不住。你给他 4 条核心原则，他马上就能开始干活，遇到特殊情况自己判断。
好的 Skill，不是写得有多详细，而是写得有多精准。
你知道什么时候该加内容，更知道什么时候该停下来。
回到那个下午
小张后来怎么样了。
他打开了自己那个 287 行的 Skill，删掉了三分之一。把模糊的“处理文档”改成了“从季度财报 PDF 中提取营收、净利润、同比增长率，输出 JSON 格式”。给每条规则都加了一个示例。最后用 5 种不同的说法跑了一遍。
第 4 种说法的时候，他发现 AI 还是会跑偏。回去一看，有一条规则跟 CLAUDE.md 里的冲突了。删掉 Skill 里那条，改到 CLAUDE.md 里。
再跑。5 种说法全过了。
他端起那杯已经凉透的咖啡喝了一口。
其实味道还行。
不是 AI 笨。
是你的 Skill，需要换一种写法了。
如果你也想试试上面的方法，可以从那个 description 字段开始。那是最容易改、也最容易看到效果的地方。
改完以后你会发现，AI 不是不听话，是它从来没听懂过你在说什么。
现在，它听懂了。
免责声明：
本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。
任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。
本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。
本文转载自：6曦轩 6曦轩 6曦轩《你写的Skill AI看不懂——5个常见坑和改法》
版权声明
本站仅做备份收录，仅供研究与教学参考之用。
读者将信息用于其他用途的，全部法律及连带责任由读者自行承担，本站不承担任何责任。
评论