我见过太多人兴冲冲地写完第一个Skill，测试的时候逻辑没问题，但一交给Agent就用不起来。换了好几个模型，还是不行。最后跑来问我：“是不是AI不行？”
问题不在AI，在Skill的描述。
一、Skill到底是个什么东西？
很多人以为Skill就是一段提示词，随便存个文件就行了。实际上，一个规范的Skill是一个文件夹，里面有固定的结构：
退款技能/
├── SKILL.md ← 核心文件，说明+执行逻辑全在这里
├── scripts/ ← 需要执行的脚本（可选）
└── references/ ← 补充参考文档（可选）
对于初学者，一个SKILL.md就够了。但恰恰是这个文件，90%的新手都写错了。
下面我把5个最致命的错误列出来，每一个都是我帮人排查时遇到的真实案例。
错误一：description写得像“废话文学”
问题表现：Skill装好了，但Agent从来不调用它。你问它为什么不调用，它说“我不知道有这个技能”。
真实案例：有个朋友写了个退款Skill，description就四个字——“处理订单”。
Agent看到这四个字，根本不知道这个Skill是干嘛的。是处理新订单？处理退款？处理改地址？AI只能靠猜。猜错了，你才发现问题。
原因：AI每次接到任务，不会运行你的代码，只会读你写的description。描述写得清楚，它就选对；描述写得含糊，它就乱猜。
解决方法：description要写清楚三件事：
什么时候用：触发条件是什么
什么时候不能用：边界在哪里
会返回什么结果：调用后能得到什么
❌ 错误写法：
description: 用于退款
✅ 正确写法：
description: >
当用户明确提出要退款，且订单还在处理中或还没发货时调用。
已完成、已评价的订单不能退。
退款成功返回退款单号，失败返回具体原因。
触发词：退款、我要退、申请退款
很多新手只写了“能用的场景”，没告诉AI“什么时候不能用”。AI不知道边界，就会自己推断。与其等AI犯错再改，不如先把边界写清楚。
错误二：一个Skill塞了太多功能
问题表现：Skill能触发，但执行起来要么卡死，要么输出乱七八糟，要么AI在里面转圈圈最后超时。
真实案例：有人写了一个“用户管理”Skill，同时包含查用户、改用户、删用户、发通知。看起来很强大，但AI调用的时候根本不知道该干哪件事。
AI在一个Skill里转了十几圈，最后什么都没输出，因为进程超时了。
原因：Skill的定位是单一职责——一件事，一个Skill。你把多个功能塞在一起，AI的上下文会被搞混，它不知道当前应该执行哪个分支。
解决方法：一个Skill只干一件事。用一句话说不清楚这个Skill是干嘛的，就说明它太复杂了，拆开。
❌ 错误：一个Skill叫“用户管理”，包含查改删发通知 ✅ 正确：拆成“查询用户”“修改用户”“删除用户”“发送通知”四个独立Skill
错误三：YAML Front Matter格式不对
问题表现：Skill文件存在，目录结构也对，但Agent根本识别不到这个Skill。
原因：SKILL.md文件开头必须包含YAML Front Matter——就是那两个---之间的部分。缺少这个头部，Agent根本不知道这是一个Skill文件。
常见的格式错误包括：
缺少开头的---
缺少结尾的---
name字段和文件夹名称不一致
YAML缩进错误（YAML对缩进极其敏感）
解决方法：确保SKILL.md以标准的YAML Front Matter开头：
name: refund-order
description: 当用户明确提出要退款时调用...
然后检查：
name字段的值是否和文件夹名称完全一致（包括大小写）
三个---是否都正确
缩进是否用了空格（不要用Tab）
错误四：把Skill写成了“操作手册”而不是“执行规范”
问题表现：Skill能触发，但执行结果不稳定。同一个输入，有时候对有时候错。
原因：很多人把Skill当成一段加长版的Prompt，写完就觉得大功告成。但官方文档对Skill的定位是——程序。
Skill不是一段静态的描述文本，而是一个有输入、有处理逻辑、有预期输出的执行单元。
❌ 错误写法（像操作手册）：
第一步：检查订单状态
第二步：如果状态符合条件，发起退款
第三步：返回结果
✅ 正确写法（像执行规范）：
执行流程
- 调用订单查询接口，获取订单状态
- 判断订单状态：
- 如果是"处理中"或"未发货" → 执行退款
- 如果是"已完成"或"已评价" → 返回"该订单不支持退款"
- 退款成功后，返回退款单号
- 退款失败，返回具体错误原因
关键是：要写清楚判断逻辑和分支处理，而不是只写步骤描述。
错误五：忽略了跨平台兼容性
问题表现：Skill在Claude Code上跑得好好的，换到Claude Desktop或Claude.ai就不行了。或者在macOS上正常，在Windows上就报错。
原因：不同平台支持的工具有差异。同一个Skill，在不同平台上的行为可能完全不同。
常见的坑包括：
Write和create_file的覆盖行为不同
Skill调用的工具在某个平台上不存在，会静默失败
AskUserQuestion和ask_user_input_v0是两个不同的工具，schema和限制都不一样
references/目录的路径解析方式在不同平台上不一致
解决方法：
明确目标平台：先想清楚这个Skill要在哪个平台上用，再针对性地写
用兼容性检查工具：GitHub上有个claude-skills-pitfalls项目，提供了兼容性检查器，可以把你的SKILL.md贴进去，自动标出跨平台问题
多平台测试：如果需要在多个平台使用，在每个平台上都跑一遍
工具调用前先确认：如果调用了特定工具，先在description里说明该工具的平台要求
快速自查清单
如果你写好的Skill不生效，按这个顺序查：
序号
检查项
怎么查
1
YAML Front Matter是否存在
打开SKILL.md，看开头有没有---
2
name
是否和文件夹名一致
对比name:后面的值和文件夹名称
3
description是否包含“什么时候用”和“什么时候不能用”
看描述里有没有触发条件和边界说明
4
一个Skill是否只干一件事
试着用一句话说清楚这个Skill的功能
5
执行逻辑是否包含判断和分支
看有没有如果...就...否则...这类逻辑
6
目标平台是否支持调用的工具
在目标平台上单独测试工具调用
最后
写Skill这件事，难的不是写代码，是写说明。
AI不像人，它不会“猜”你的意图。你得把什么时候用、什么时候不能用、怎么执行、返回什么——所有这些都写清楚，它才能正确地调用你的Skill。
下次你的Skill不生效，别急着怀疑AI不行。先打开SKILL.md，对照上面这5个错误自查一遍。90%的问题，都出在描述和结构上。
本文系作者基于实际排查经验的总结，欢迎同行交流讨论。
