SKILL：把操作经验作为代码交付

SKILL 不仅仅是命令参考。它是 AI Agent 的操作指南：何时使用命令、哪个优先、哪些字段不应猜测、何时验证、何时回读。

仅有 CLI 是不够的

CLI 命令赋予了 Agent 执行力。

但没有判断力的执行会导致问题：

Agent 不仅仅需要命令。它们需要操作判断力。

什么是 SKILL？

SKILL 是为 AI Agent 编写的操作指南。

它不是：

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

它是：

SKILL 赋予了 Agent 操作判断力。

安装

SKILL 是 Apifox CLI 的配套组件：

# 为你的 AI Agent 安装 SKILLapifox skill install

这将安装 8 个配套 Skill，帮助 Agent 理解：

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

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

Agent 仍然需要知道如何将任务分解为跨业务的执行流。

这种经验不能：

• 全面写进工具描述（会消耗过多 Context）
• 散落在对话上下文中（会在会话间丢失）
• 由模型记忆（属于特定产品，而非通用知识）

隐藏的工作流和“业务陷阱”需要明确的指导。

示例：测试场景维护

考虑维护一个复杂的测试场景。

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

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

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

SKILL 不仅仅是说“有一个 test-scenario update 命令”。

它会说：

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

SKILL 指导背后的命令

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

# 步骤 1：从接口导入步骤apifox test-scenario import-steps <scenarioId> --project <projectId> --source endpoint --ids <endpointIds> --sync manual# 步骤 2：回读详细信息apifox test-scenario get <scenarioId> --project <projectId> --with-case-detail# 步骤 3：更新特定部分（Agent 生成更新 JSON）# 步骤 4：更新前验证apifox cli-schema validate test-scenario-update --file ./scenario-update.json# 步骤 5：执行更新apifox test-scenario update <scenarioId> --project <projectId> --file ./scenario-update.json# 步骤 6：运行验证apifox run --project <projectId> --test-scenario <scenarioId>

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

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

SKILL 强调：

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

为什么这很重要：

| 没有 get --with-case-detail | 有 get --with-case-detail | | :--- | :--- | | 步骤仅显示 ID | 步骤显示完整的用例结构 | | Agent 不知道内部格式 | Agent 看到实际的断言/提取器格式 | | Agent 猜测字段名称 | Agent 基于真实示例工作 |

获取真实结构可以防止基于想象的更新。

可进化性：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
• 识别任务类型时加载 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 负担

下载 Apifox，在一个工作区内完成 API 的设计、Mock、测试和文档_。了解更多关于用于命令行 API 测试、CI 自动化和 AI Agent 工作流的 _Apifox CLI_ 的信息。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。