关注 霍格沃兹软件测试开发 公众号回复「资料」, 领取人工智能测试开发技术合集我见过太多人兴冲冲地写完第一个Skill测试的时候逻辑没问题但一交给Agent就用不起来。换了好几个模型还是不行。最后跑来问我“是不是AI不行”问题不在AI在Skill的描述。一、Skill到底是个什么东西很多人以为Skill就是一段提示词随便存个文件就行了。实际上一个规范的Skill是一个文件夹里面有固定的结构退款技能/├── SKILL.md ← 核心文件说明执行逻辑全在这里├── scripts/ ← 需要执行的脚本可选└── references/ ← 补充参考文档可选对于初学者一个SKILL.md就够了。但恰恰是这个文件90%的新手都写错了。下面我把5个最致命的错误列出来每一个都是我帮人排查时遇到的真实案例。错误一description写得像“废话文学”问题表现Skill装好了但Agent从来不调用它。你问它为什么不调用它说“我不知道有这个技能”。真实案例有个朋友写了个退款Skilldescription就四个字——“处理订单”。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-orderdescription: 当用户明确提出要退款时调用…然后检查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不生效按这个顺序查序号检查项怎么查1YAML Front Matter是否存在打开SKILL.md看开头有没有—2name是否和文件夹名一致对比name:后面的值和文件夹名称3description是否包含“什么时候用”和“什么时候不能用”看描述里有没有触发条件和边界说明4一个Skill是否只干一件事试着用一句话说清楚这个Skill的功能5执行逻辑是否包含判断和分支看有没有如果…就…否则…这类逻辑6目标平台是否支持调用的工具在目标平台上单独测试工具调用最后写Skill这件事难的不是写代码是写说明。AI不像人它不会“猜”你的意图。你得把什么时候用、什么时候不能用、怎么执行、返回什么——所有这些都写清楚它才能正确地调用你的Skill。下次你的Skill不生效别急着怀疑AI不行。先打开SKILL.md对照上面这5个错误自查一遍。90%的问题都出在描述和结构上。本文系作者基于实际排查经验的总结欢迎同行交流讨论。本文部分内容参考了霍格沃兹测试开发学社整理的相关技术资料主要涉及软件测试、自动化测试、测试开发及 AI 测试等内容侧重测试实践、工具应用与工程经验整理。