技能写完、装好，然后发现：它从来没有被自动触发过。 每次都得手动点名才想起来用。
这不是模型的问题，九成出在两处——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 里列全了口语化触发词
- 技能内零绝对路径
- 技能内零环境专属工具
- 工具不可用时有兜底路径 + "已知做不通"清单
- 需要外部信息的环节：要么"问一次"，要么"自动化时喂全"
- 跨职责引用已清空
七、结尾
技能被不被调用，跟它写得好不好是两件事。description 是入口，可移植性是寿命——入口没写对，再好的内容也进不了上下文；换台机器就废，再常用的技能也传不出去。
写完技能之后，不妨做两个测试：把 description 单独拿出来，自问"看到这句话，能立刻判断什么时候该用吗"；再把整个目录拷到一台干净的机器上跑一遍。这两步过了，技能才算真的能用。
参考文章
- Anthropic 官方文档《Agent Skills》：description 是触发匹配依据，须说明"做什么 + 何时用"
- Anthropic Engineering《Equipping agents for the real world with Agent Skills》
- 《learn-agentic-coding》Step 07：项目规则与跨工具复用