为什么Agent可能看不懂你写好的Skill？

你有没有遇到过这种情况： 精心写了一个AI技能，测了好几遍逻辑没问题，但智能体就是从来不调用它。换个说法问，还是不触发。最后怀疑是AI不行，换了模型，还是一样。

一个技能，长什么样

很多人以为写技能就是写一段提示词，随便存个文件就算了。 实际上，一个规范的技能，是一个文件夹，里边有固定的结构：

退款技能/
├── SKILL.md ← 核心文件，说明+执行逻辑全在这里
├── scripts/ ← 需要执行的脚本（可选）
└── references/ ← 补充参考文档（可选）
└── assets/ ← 补充的附件（可选）

但……对于初学者，要求就不要太高了。今天咱们就举个最最简单的技能，只有一个 SKILL.md 就够了，打开来长这样：

---
name: refund-order
description: >
  当用户明确提出要退款，且订单还在处理中或还没发货时调用。
  已完成、已评价的订单不能退。支持退全款和退部分。
  触发词：退款、我要退、申请退款
---

第一步：检查订单状态，不符合条件直接返回原因
第二步：发起退款请求
第三步：返回退款单号或失败原因

横线以上是说明，横线以下是执行逻辑。说明是给AI看的，AI靠它决定要不要调用你这个技能。执行逻辑是调用之后按这个来干活的。 两部分缺一不可。 很多人只认真写了执行逻辑，说明随便糊弄几个字，结果技能永远不触发，然后以为是AI的问题。

AI靠说明选技能，不靠你的代码

AI每次接到任务，不会运行你的代码，只会读你写的说明。说明写得清楚，它就选对；说明写得含糊，它就乱猜。 之前帮一个朋友排查，他的智能体老是在不该退款的时候退款。找了半天，说明就四个字：“处理订单”。这个说明也太简略了，AI根本不知道这是退款，也不知道什么时候该用，只能靠感觉猜。

说明要写三件事

说明写起来，比大多数人预计的难。难不在于长，在于得想清楚这三个点： 什么时候用，什么时候不能用，会返回什么结果。 退款这个技能，很多人写：“用于退款”，三个字，没了。 应该这样写： 另外，最最重要的是：“什么时候不能用”。大多数人只写了能用的场景，没告诉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 梳理清楚需求。你需要了解技能的架构吗？不需要，你只需要负责安装，负责告诉它做什么、什么时候做、怎么做、做什么的效果最好就行了。 至于技能怎么安装，用什么工具最好，咱们下次聊。