你有没有遇到过这种情况： 精心编写了一个 AI 技能，反复测试逻辑都没有问题，但 Agent 就是从来不调用它。换一种问法，仍然不触发。最后怀疑是 AI 能力不足，换了模型，结果还是一样。

一个技能的基本结构

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

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

不过……对于刚入门的用户，要求不必太高。今天我们就用一个最简单的技能为例，只需一个 SKILL.md 就够了，打开内容如下：

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

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

横线以上是说明部分，横线以下是执行逻辑。说明是给 AI 看的，AI 依靠它来决定是否调用你这个技能。执行逻辑则是调用后按照这个流程来执行。 两部分缺一不可。 很多人只认真写了执行逻辑，说明随便凑几个字，结果技能永远无法触发，然后还以为是 AI 有问题。

AI 依据说明选择技能，而非你的代码

每次接到任务时，AI 并不会运行你的代码，只会读取你写的说明。说明写得清晰，AI 就能准确选择；说明写得模糊，AI 只能靠猜。 之前帮一位朋友排查，他的 Agent 总在不该退款的时候退款。找了半天，说明里只有四个字：“处理订单”。这个描述太笼统，AI 根本不知道这是退款技能，也不清楚什么时候该用，只能凭感觉推测。

说明需要涵盖三方面的内容

编写说明比大多数人想象的要难。难处不在于长度，而在于必须想清楚以下三个点： 什么情况下可以使用，什么情况下不能用，以及会返回什么结果。 就拿退款这个技能来说，很多人只写：“用于退款”，三个字就收工了。 正确的写法应该是： 另外，最重要的一点是：“什么时候不能用”。大多数人都只写了能使用的场景，却没有告诉 AI 边界在哪里，于是 AI 只能自己推断。推断出错后你才能发现问题，与其等 AI 犯错再修正，不如提前把问题扼杀在摇篮里。

一个技能只做一件事

还有一个很常见的错误：一个技能里塞了太多功能。 查询用户、修改用户、删除用户，顺便再发个通知，全堆在一起。看起来很强大，但实际上 AI 调用的时候，它自己也不知道具体要执行哪一项——反正我什么都会，但好像我又说不清到底会什么。 然后 AI 就会在你定义的功能里来回绕圈。我见过最严重的案例，AI 在一个技能里转了十几圈，最后什么都没输出，因为进程超时了。简单说，就是 Agent 觉得这件事拖得太久，强行中途停止了。 一个技能，只干一件事。 如果一句话说不清楚，就拆分成多个。

参数命名不对，数据就对不上

参数叫“id”，一个请求里既有用户 id 又有订单 id，AI 随手传一个，数据就对不上了。排查半天，发现只是名字没写清楚。 参数命名要说人话：`user_id`、`order_id`，一眼就能看懂是什么。对于固定选项的参数，要把所有可填的值都列出来，别让 AI 去猜——它猜出来的词大概率对不上你的系统。（不过这件事，程序开发中用得比较多，如果你不熟悉也属正常，可直接跳过这一节。）

技能并不是越多越好

很多人觉得技能越多，Agent 就越强大？事实并非如此。 当技能超过一定数量时，AI 每次选择工具都要在大量选项里翻找，越翻越容易选错——该用的用不上，不该用的反而被调用了。从实际经验来看，单个 Agent 的技能数量最好不超过 10 个。如果真的需要很多工具，就拆分成多个专职 Agent，每个只负责自己那部分。 这就好比相亲的时候，七大姑八大姨都来替你拿主意，最后这门婚事肯定成不了——你到底该听谁的？

写不好时，让 AI 帮你想清楚

上面提到的这些细节，大多数人栽在同一个地方：说明没有写清楚，技能永远无法触发，而自己又不知道问题出在哪里。 市面上有一个名为 skill-creator 的功能，它不仅会帮你写技能，还会帮你把“什么时候触发”这件事想清楚——而这恰恰是最容易被跳过的一步。 为什么之前有一堆像“前任.skill”、“蒸馏员工.skill”之类的技能，大部分都是通过 skill-creator 梳理清楚需求的。你需要了解技能的架构吗？不需要。你只需要负责安装，负责告诉它做什么、什么时候做、怎么做、以及做什么效果最好就行了。 至于技能怎么安装，用什么工具最好，我们下次再聊。