将操作经验封装为代码并交付的完整步骤

SKILL 不仅是命令参考手册，更是 AI Agent 的操作指南：它明确指示何时使用哪些命令、各命令的优先级、哪些字段不可随意猜测、何时需要验证以及何时需要回读。

仅有 CLI 是不够的

CLI 命令为 Agent 提供了执行能力，但若缺少判断力，执行反而容易引发问题：

Agent 仅靠命令是不够的，更需要具备操作判断力。

什么是 SKILL？

SKILL 是为 AI Agent 量身打造的操作指南。

它不是：

• 简单的命令罗列
• 参考手册
• 帮助页面

它实际上是：

归根结底，SKILL 赋予了 Agent 操作判断力。

安装

SKILL 是 Apifox CLI 的配套组件：

# 为你的 AI Agent 安装 SKILL
apifox skill install

此步骤会安装 8 个配套 Skill，帮助 Agent 理解：

• CLI 命令的语义
• 资源结构
• 任务工作流
• 错误处理
• 验证模式

为什么 SKILL 至关重要：隐藏的工作流

Agent 还需要知道如何将任务拆解为跨业务的执行流程。这类经验既不能全部塞入工具描述（上下文无法承受），也不能零散地放置在对话上下文里（更换会话即丢失），更不能指望模型硬记（这是产品专属知识，而非通用常识）。

这些隐藏的工作流和“业务陷阱”必须有明确的指导。

示例：测试场景维护

以维护一个复杂的测试场景为例。

错误的做法（Agent 从零手写）：

Agent: "我将手动创建测试场景结构"
Agent: 编写包含断言、提取器、处理器的完整步骤数组
结果: 字段错误、比较器错误、缺少必填字段
CLI: 拒绝写入或创建了不完整的场景

正确的做法（编码在 SKILL 中）：

SKILL 并非简单地说“有一个 test-scenario update 命令”就结束。它会告诉你：

“复杂的场景不适合从零开始手写完整结构。更稳妥的路径是先导入现有的接口或用例步骤，然后回读完整结构，最后进行本地修改。”

SKILL 指导背后的命令

以下是 SKILL 指导 Agent 实际使用的命令：

# 步骤 1：从接口导入步骤
apifox test-scenario import-steps  --project  --source endpoint --ids  --sync manual

# 步骤 2：回读详细信息
apifox test-scenario get  --project  --with-case-detail

# 步骤 3：更新特定部分（Agent 生成更新 JSON）

# 步骤 4：更新前验证
apifox cli-schema validate test-scenario-update --file ./scenario-update.json

# 步骤 5：执行更新
apifox test-scenario update  --project  --file ./scenario-update.json

# 步骤 6：运行验证
apifox run --project  --test-scenario 

SKILL 负责告诉 Agent 何时使用哪个命令以及为什么使用。

关键洞察：get --with-case-detail

SKILL 特别强调：

“使用 get --with-case-detail 获取真实结构，而不是凭空想象步骤内部的用例。”

为什么这很重要：

获取真实结构，才能避免凭空想象的更新。

可进化性：SKILL 可以改变

Apifox SKILL 是可进化且可版本化的操作经验。

为什么这很重要

它是如何工作的

Agent 被授予了对 SKILL 的写权限。如果 SKILL 滞后或变得难以使用：

• Agent 可以修改它
• Agent 可以建议改进
• SKILL 通过使用不断进化

SKILL 不是冻结的文档，而是鲜活的操作代码。

兼容层

我们从真实的 Bug 中学到了这一点：

发现的问题：

某些场景步骤在进行二次更新时，外部步骤更新成功，但内部 HTTP 用例未正确更新。

根本原因：

• 内部用例更新标记需要特殊处理
• Agent 不知道这些标记
• 产品语义需要特定的 Flag

解决方案：

• 将兼容逻辑放入 CLI
• CLI 自动处理内部标记
• 用户和 Agent 不需要了解内部细节

约束的含义被分层放入了 SKILL 中：SKILL 告诉 Agent 使用正确的命令，CLI 处理这些命令背后的产品语义。Agent 无需理解那些内部标记。

按需加载

SKILL 遵循与 cli-schema 相同的原则：复杂度应由执行和文档吸收，而不是完全暴露给模型。

SKILL 的做法是：Agent 按需预热 SKILL，识别到任务类型时再加载，只有相关的工作流指导会进入 Context。

SKILL vs. 文档

8 个配套 Skill

Apifox 提供了 8 个配套 Skill：

每个 SKILL 包含：

• 任务类型识别
• 命令顺序指导
• 字段安全边界
• 验证检查点
• 验证模式

下一步

现在我们已经建立了所有三个核心组件：

• cli-schema validate —— 质量门禁
• agentHints —— 下一步导航
• SKILL —— 工作流判断

接下来的问题是：

这真的有效吗？数据如何？

在第 6 部分《数据不会撒谎：工具调用减少 30%，Token 减少 25%》中，我们将分享内部对比的定量结果，并解释节省的来源。

关键要点

• CLI 赋予执行力；SKILL 赋予操作判断力
• SKILL 是操作指南，而非命令参考
• 隐藏的工作流需要明确的指导
• “导入步骤 → 回读 → 本地更新”比手写更安全
• --with-case-detail 防止基于想象的更新
• SKILL 是可进化的——Agent 可以修改它
• CLI 吸收产品语义，SKILL 指导工作流
• 按需加载防止 Context 负担