技能装了却从没被调用：description 与可移植性

技能写完、装好，然后发现：它从来没有被自动触发过。 每次都得手动点名才想起来用。

这不是模型的问题，九成出在两处——description 写得不像触发条件，或者技能里藏着换台机器就废的东西。

技能的第一层加载（常驻上下文）只有 name 和 description 两项。也就是说：模型判断"该不该用这个技能"时，它手里只有这两行字。

正文写得再好，description 没写对，就等于这个技能不存在。

官方对 description 的要求很明确：必须同时说清"做什么"和"什么时候用"。对比一下：

# 差的写法
description: 处理文章相关任务

# 好的写法
description: 为已完成并落盘的 Markdown 文章生成封面图，并把本地相对路径引用写回 md。
  必须先运行 gate.py 校验文章确实写完，不通过一律禁止出图。
  当用户要求"生成封面"、"配图"、"封面图"、"补封面"时使用本技能。

好的写法有三个要素：

第三点最容易被忽略。用户不会照着你的专业术语说话，他会说"配个图""补一下封面"。把用户真实的叫法写进 description，命中率会明显不一样。

第二个高频问题是技能在本机跑得好好的，发给别人就废。原因通常藏在两处：

绝对路径。 技能里写着某个具体目录，换台机器那个路径根本不存在：

# 有问题
- 交付目录：/Users/<某人>/workspace/articles/<系列名>

# 正确
- 交付目录：第 1 次运行时向用户确认；未指定时默认当前工作目录下的 articles/<系列名>

更隐蔽的是写 ~/Desktop/... 这类看着通用、其实仍然绑定个人习惯的路径。

环境专属工具。 从别的环境照搬技能时，里面可能引用了本机没有的工具。技能一旦调用了不存在的工具，整个流程直接断在第一步。

发布前跑这三条检查，都必须为空：

grep -rn "/Users/\|/home/\|C:\\\\" <技能目录>/
grep -rni "browser use\|<某环境专属工具名>" <技能目录>/
grep -rni "封面\|出图" <写作类技能目录>/     # 跨职责引用

第三条是解耦的验收：写作技能不该出现配图相关的内容（这一点在上一篇展开过）。

不要只写"用 X 工具打开某页面"，要写清拿不到时怎么办：

- 首选：某某榜单页（网页抓取工具读取榜单文本）
- 补充：其他榜单（多为 JS 渲染，抓不到就只读可见部分）
- 兜底：都抓不到时，改用搜索引擎检索「今日热搜 + 当天日期」，
        按权威报道还原，并在结果里注明用了兜底方式

已知做不通、不要再试：
- 某某 JSON 接口（Forbidden）
- 某某榜单页（返回空）

"已知做不通"清单非常值钱。 把踩过的死路写进去，能省掉下一轮的大量无效尝试——模型不知道哪些路是死的，它只会一遍遍重试。

需要外部信息（存哪儿、发给谁）时，两种极端都错：写死会失效，每轮都问会烦人。

好用的句式是三句话成套：

- 第 1 次运行时向用户确认…
- 用户未指定时，默认 X（相对路径）
- 同一会话后续沿用，不反复问

但在无人值守的自动化场景里要反过来：没人回答问题，所以必须把答案一次性写进任务描述。同一条规则，交互式问一次，自动化喂全——这点很容易搞混。

技能不是写完就一劳永逸的。有三类东西会过期：

外部工具变了。 你依赖的接口可能下线、返回结构可能调整、鉴权方式可能更换。这就是为什么要把"已知做不通"的清单维护下去——每遇到一条新的死路就补进去，能省掉下一轮的大量重试。

环境变了。 本机升级了运行时、换了默认包管理器、项目迁移了目录，都可能让技能里的示例命令失效。建议每隔一段时间在干净环境里跑一遍（上一节提到的两条测试）。

需求变了。 用户开始用新的说法叫它（比如从"配图"变成"出个头图"），description 里的触发词就要补。判断方法很简单：如果最近几次都是你手动点名才用上它，八成是触发词没覆盖到。

复查的节奏不用很重，一个实用做法是：每次技能被手动调用时，顺手问一句"这次它为什么没被自动触发"，然后把答案补回 description。

技能被不被调用，跟它写得好不好是两件事。description 是入口，可移植性是寿命——入口没写对，再好的内容也进不了上下文；换台机器就废，再常用的技能也传不出去。

写完技能之后，不妨做两个测试：把 description 单独拿出来，自问"看到这句话，能立刻判断什么时候该用吗"；再把整个目录拷到一台干净的机器上跑一遍。这两步过了，技能才算真的能用。

#智能体 #AgentSkills #AI工程 #可移植性 #技术实践