你有没有遇过这种情况：
精心写了一个AI技能，测了好几遍逻辑没问题，但Agent就是从来不调用它。换个说法问，还是不触发。最后怀疑是AI不行，换了模型，还是一样。
问题不在AI，在你写的那个说明。
一个技能，长什么样
很多人以为写技能就是写一段提示词，随便存个文件就算了。
实际上一个规范的技能，是一个文件夹，里边有固定的结构：
退款技能/
├── SKILL.md ← 核心文件，说明+执行逻辑全在这里
├── scripts/ ← 需要执行的脚本（可选）
└── references/ ← 补充参考文档（可选）
└── assets/ ← 补充的福建(可选)
但....对于初学者要求,就不要太高了吧,今天咱们就举个最最最最简单的技能，只有一个 SKILL.md 就够了,打开来长这样：
name: refund-order
description: >
当用户明确提出要退款，且订单还在处理中或还没发货时调用。
已完成、已评价的订单不能退。支持退全款和退部分。
触发词：退款、我要退、申请退款
第一步：检查订单状态，不符合条件直接返回原因
第二步：发起退款请求
第三步：返回退款单号或失败原因
横线以上是说明 ，横线以下是执行逻辑。说明是给AI看的，AI靠它决定要不要调用你这个技能。执行逻辑是调用之后按这个来干活的。
两部分缺一不可。
很多人只认真写了执行逻辑，说明随便糊弄几个字，结果技能永远不触发，然后以为是AI的问题。
AI靠说明选技能，不靠你的代码
AI每次接到任务，不会运行你的代码，只会读你写的说明，说明写得清楚，它就选对，说明写得含糊，它就乱猜。
我之前帮一个朋友排查，他的Agent老是在不该退款的时候退款,找了半天，说明就四个字："处理订单"，我滴个乖乖哦，这是什么神仙处理逻辑！！
Agent不知道这是退款，也不知道什么时候该用，只能靠感觉猜。
说明要写三件事
说明写起来，比大多数人预计的难，难不在于长，在于得想清楚这三个点：
什么时候用，什么时候不能用，会返回什么结果。
退款这个技能，很多人写："用于退款"，三个字，没了。
应该这样写：
当用户明确提出要退款，且订单还在处理中或还没发货时调用，已完成、已评价的订单不能退，退款成功返回退款单号，失败返回具体原因。
另外最最最重要的是："什么时候不能用"，大多数人只写了能用的场景，没告诉AI边界在哪里，AI就只好自己推断，推断错了你才能发现问题，与其等 AI 犯错再改，不如先把问题摁下去。
一个技能只干一件事
还有一个很常见的错误：一个技能塞太多功能。
查用户、改用户、删用户，顺便发个通知，全放在一起，看起来很强大，实际上AI调用的时候，它自己也不知道要干哪件事，反正我就是啥都会，但好像我到底会啥我也不知道。
然后开始在你定义的功能里绕圈，我见过最严重的，AI在一个技能里转了十几圈，最后什么都没输出，因为进程超时了，简而言之就是你的智能体觉得这事坐太久了，有可能是报错，强行中途停下。
一个技能，只干一件事。
用一句话说不清楚，就拆开。
参数名不对，数据就对不上
参数叫"id"，一个请求里既有用户id又有订单id，AI随手传一个，数据就对不上了，排查半天，就是名字没说清楚。
参数名要说人话：user_id、order_id，一眼看懂是什么，固定选项的参数，把所有可以填的值都列出来，别让AI猜，猜出来的词大概率对不上你的系统。【不过这事，程序员用得比较多，如果你不懂也属正常，可直接跳过】
技能不是越多越好
很多人觉得技能越多，Agent越强大？并不是。
超过一定数量，AI每次选工具要在一堆东西里翻，越翻越容易选错，该用的用不到，不该用的反而跑了，我自己的经验，单个Agent不超过10个技能。真的需要很多工具，拆成多个专职Agent，每个只负责自己那块。
突然想到我父亲给我一个非常恰当的比喻，比如当你去相亲的时候，七大姑八大姨都给你拿主意，最后这婚事肯定成不了，因为你到底要听谁的？答：不知道。
写不好，让AI替你想清楚
上面这些细节，大多数人栽在同一个地方：说明没写清楚，技能永远不触发，但自己不知道哪里出了问题。
市面上有一个叫skill-creator的功能，它不止替你写技能，还帮你把"什么时候触发"这件事想清楚，这恰好是最容易跳过去的那一步。
为什么之前有一堆的什么前任.skill、蒸馏员工.skill，大都是用skill-creator梳理清楚需求，什你需要了解技能的架构吗？不需要，你只需要负责安装，负责告诉他做什么，什么时候做，怎么做，做什么的效果是最好的就行了。
至于技能怎么安装，用什么工具最好，欢迎关注，咱们下次聊。
我是黄啊码，码字的码，如果觉得受用，欢迎一键三连