可复现的智能体技能：从自检开始

很多团队在搭建 AI 智能体时会陷入一个怪圈：技能（skill）写了几十个，模型却经常在关键时刻"失忆"——要么误用不适合当前环境的能力，要么在明明失败的操作上反复重试。复盘这些事故，根因往往不在模型能力，而在技能定义缺少"可复现"的地基：没有自检、没有前置条件声明、没有失败语义。

技能不是提示词的堆砌

传统写法把技能当作一段长提示词，描述"你应该如何做"。问题在于，模型无法在执行前验证自己是否真的具备条件。一个健康的技能体系应当像可执行程序那样，先看入口条件，再执行主体，最后定义明确的退出码。

具体而言，每个技能至少应包含三段结构：

• 前置检查：执行任何实质动作前，先用只读操作验证依赖是否就绪。例如需要 SSH 的技能，先跑一次 echo ok；需要凭据的技能，先验证 token 是否有效、权限是否足够。失败即终止，不进入正文。
• 幂等主体：核心步骤应支持重复执行而不产生副作用。写操作前先读当前状态，写入后再读校验，比"盲写不管"稳健一个数量级。
• 失败契约：定义"什么算失败"以及失败后返回什么。没有失败契约的技能会把错误抛给上下文，让模型自行猜测下一步，这是多数循环重试的源头。

自检优先的顺序

把自检放在最前面还有一个容易被忽略的好处：它能在技能真正消耗 token 与外部 API 配额之前，就决定"不该运行"。一次自检的成本通常是几条只读命令，而一次误运行的成本可能是半小时的清理、被污染的数据，甚至一次需要人工介入的审批。

实践中推荐这样的骨架：先探测环境与参数合法性，再获取一次性资源（如临时 token），然后才进入业务逻辑。每一步都要显式抛出失败，而不是吞掉错误继续往下走。

可复现性来自可观测

技能要可复现，前提是失败可观察。给每个技能约定统一的错误返回格式——至少包含错误码、人可读原因、可安全重试与否三个字段——能让编排层做出正确决策。重试一个不可重试的操作，比不重试危害更大。

另一个观测手段是给技能加"干跑"（dry-run）模式：所有写操作降级为打印意图，让使用者在真实执行前确认影响面。这对生产环境的自动化管道尤其重要，因为线上没有撤销键。

从第一天就固化的习惯

最后几条建议来自踩坑后的固化：

1. 技能文档里写明"何时不要用"，和"何时使用"同等重要。
2. 任何外部写操作必须先 GET 后确认字段写入成功，再进入下一步。
3. 凭据永远不落日志，哪怕是日志级别为 debug。
4. 每个技能都要有一个探针用例，验证从真实入口进入后能否正确失败和正确成功。

技能工程的核心不是让模型更聪明，而是把不确定性挡在执行之前。自检先行的技能，是智能体系统从"演示可用"走到"长期可靠"的第一块基础设施。