Agent Skill工程：如何把一次成功运行提炼成可测试的方法

Agent Skill 工程：如何把一次成功运行提炼成可测试的方法

Agent 完成一次任务后，最容易做错的事，就是立刻加个 cron。

一次成功可能依赖操作者临时补的数据、模型偶然选中的路径，或者人工在最后一步修掉的问题。把整段对话复制到定时任务里，只是在自动重放偶然性。

SpaceXAI 的 Grok Bot 文档给出了更稳妥的顺序：先完成一次任务，让方法可靠，保存为 Skill，测试，再创建 Routine。对开发团队而言，这可以直接翻译成一套 Skill 工程流程。

Trace 不是 Skill

一次 Agent 运行可以表示为：

ts 复制代码

type RunTrace = {
  inputs: InputSnapshot[];
  actions: ToolCall[];
  decisions: DecisionRecord[];
  outputs: Artifact[];
  validations: CheckResult[];
  interventions: HumanIntervention[];
};

Trace 是事实记录，包含成功路径、试错和人工补洞。Skill 是从多条事实中抽出的规范：哪些条件必须满足、哪些动作可以执行、什么结果算完成、遇到什么情况必须停。

ts 复制代码

type SkillSpec<I, O> = {
  id: string;
  version: string;
  applicableWhen: (ctx: Context) => boolean;
  inputSchema: Schema<I>;
  execute: (input: I, env: Env) => Promise<O>;
  validate: (output: O, evidence: Evidence[]) => CheckResult[];
  approvalPolicy: ApprovalPolicy;
  failurePolicy: FailurePolicy;
};

如果一个"Skill"只有 execute，没有 schema、validate 和 failurePolicy，它仍然只是脚本化提示词。

五步提炼流程

1. 先标注人工介入

人工改过筛选条件、补过文件、替换过错误来源，就把它们标成 intervention。未被解释的人工动作不能直接删除，否则生产运行会缺少关键步骤。

2. 把判断改写成规则

例如：

ts 复制代码

if (report.generatedAt < cutoff.minus({ hours: 24 })) {
  return fail("STALE_INPUT");
}

无法写成确定规则的判断，保留为审批点：让 Agent 给出证据、建议和影响，由人选择，而不是让模型偷偷替代业务决策。

3. 冻结输入契约

输入契约至少包括来源、字段、作用域、新鲜度和权限。长期记忆可以保存偏好，却不能替代会变化的业务事实。重要决定必须重新读取当前源系统。

4. 定义输出与证据

输出不应只有一段自然语言。建议同时返回结构化结果和证据引用：

ts 复制代码

type SkillResult<T> = {
  data: T;
  evidence: Array<{ source: string; observedAt: string }>;
  checks: CheckResult[];
  status: "complete" | "partial" | "blocked";
};

5. 先测失败，再接调度

至少覆盖：缺数据、旧数据、字段变更、权限不足、工具超时和重复触发。故障测试通过后，Routine 才负责按时间或事件启动 Skill。

回放测试不要只比较文本

生成式输出不适合做逐字快照。更稳的方式是检查不变量：

ts 复制代码

expect(result.evidence.length).toBeGreaterThan(0);
expect(result.checks.every(x => x.passed)).toBe(true);
expect(result.status).not.toBe("complete")
  .when(sourceIsMissing);

文本可以变化，但来源不能丢、必填字段不能少、缺数据时不能假装完成、高影响动作不能越过审批边界。

版本与 Routine 绑定

Routine 应固定 Skill 的明确版本：

ts 复制代码

const routine = {
  schedule: "0 8 * * 1-5",
  skill: "account-health@2.1.0",
  onMissingSource: "stop",
};

输出格式或审批语义发生破坏性变化时升主版本，并重新跑回放与故障用例。网站、连接器和数据格式变化，也应触发重新验证，不能让旧 Routine 静默继续。

一份上线前检查表

输入是否来自当前权威源，并带采样时间？
关键分支是否有可解释规则？
输出是否有 schema 和证据？
缺失、过期与权限不足是否会停止？
发送、发布、删除、购买等动作是否需要审批？
Routine 是否固定了已验证的 Skill 版本？

Agent 的能力不会因为定时运行而自动变可靠。把成功轨迹压缩为 Skill，把 Skill 变成可回放、可验证、可版本化的契约，才是从 Demo 走向团队工程的关键一步。

Tipkay 会按岗位组合经验、流程、模型和工具；团队仍应把自己的输入契约、验证规则和关键操作确认加入每个具体流程。