我见过太多人兴冲冲地写完第一个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不是一段静态的描述文本，而是一个有输入、有处理逻辑、有预期输出的执行单元。

❌ 错误写法（像操作手册）：

第一步：检查订单状态
第二步：如果状态符合条件，发起退款
第三步：返回结果

✅ 正确写法（像执行规范）：

## 执行流程

1. 调用订单查询接口，获取订单状态
2. 判断订单状态：
   - 如果是"处理中"或"未发货" → 执行退款
   - 如果是"已完成"或"已评价" → 返回"该订单不支持退款"
3. 退款成功后，返回退款单号
4. 退款失败，返回具体错误原因

关键是：要写清楚判断逻辑和分支处理，而不是只写步骤描述。

错误五：忽略了跨平台兼容性

问题表现：Skill在Claude Code上跑得好好的，换到Claude Desktop或Claude.ai就不行了。或者在macOS上正常，在Windows上就报错。

原因：不同平台支持的工具有差异。同一个Skill，在不同平台上的行为可能完全不同。

常见的坑包括：

• Write和create_file的覆盖行为不同
• Skill调用的工具在某个平台上不存在，会静默失败
• AskUserQuestion和ask_user_input_v0是两个不同的工具，schema和限制都不一样
• references/目录的路径解析方式在不同平台上不一致

解决方法：

1. 明确目标平台：先想清楚这个Skill要在哪个平台上用，再针对性地写
2. 用兼容性检查工具：GitHub上有个claude-skills-pitfalls项目，提供了兼容性检查器，可以把你的SKILL.md贴进去，自动标出跨平台问题
3. 多平台测试：如果需要在多个平台使用，在每个平台上都跑一遍
4. 工具调用前先确认：如果调用了特定工具，先在description里说明该工具的平台要求

快速自查清单

如果你写好的Skill不生效，按这个顺序查：

最后

写Skill这件事，难的不是写代码，是写说明。

AI不像人，它不会“猜”你的意图。你得把什么时候用、什么时候不能用、怎么执行、返回什么——所有这些都写清楚，它才能正确地调用你的Skill。

下次你的Skill不生效，别急着怀疑AI不行。先打开SKILL.md，对照上面这5个错误自查一遍。90%的问题，都出在描述和结构上。

关于我们

本文部分内容参考了霍格沃兹测试开发学社整理的相关技术资料，主要涉及软件测试、自动化测试、测试开发及 AI 测试等内容，侧重测试实践、工具应用与工程经验整理。