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

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

仅有 CLI 是不够的

CLI 命令赋予了 Agent 执行力。

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

CLI 能力	缺乏判断力的风险
创建测试用例	在错误的项目中创建
更新测试场景	未回读即更新
导入步骤	未检查现有结构即导入
运行测试	未验证变更即运行

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

什么是 SKILL？

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

它不是：

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

它是：

SKILL 内容	目的
何时使用命令	任务类型 → 命令映射
哪个命令优先	顺序指导
哪些字段不应猜测	安全边界
何时验证	质量门禁设置
何时回读	验证时机
何时运行测试	确认工作流

SKILL 赋予了 Agent 操作判断力。

安装

SKILL 是 Apifox CLI 的配套组件：

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

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

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

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

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

这种经验不能：

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

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

示例：测试场景维护

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

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

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

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

步骤	原因
1. 从接口或用例导入现有步骤	不要手写复杂的结构
2. 回读完整结构	查看实际导入的格式
3. 进行本地修改	基于准确的基础进行操作
4. 更新前验证	在本地捕获错误
5. 运行场景	验证行为

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 获取真实结构，而不是凭空想象步骤内部的用例。”

为什么这很重要：

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

可进化性：SKILL 可以改变

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

为什么这很重要

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

它是如何工作的

Agent 被授予了对 SKILL 的写权限。

如果 SKILL 滞后或变得难以使用：

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

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

兼容层

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

发现的问题：

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

根本原因：

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

解决方案：

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

约束的含义被分层放入了 SKILL 中：

SKILL 告诉 Agent 使用正确的命令。CLI 处理这些命令背后的产品语义。Agent 不需要理解内部标记。

按需加载

SKILL 遵循与 cli-schema 相同的原则：

复杂度应由执行和文档吸收，而不是完全暴露给模型。

替代方案	问题
将所有 SKILL 加载到 Context 中	Token 负担
将所有规则放入 `--help`	分散注意力
写进 Prompt	无法更新

SKILL 的方法：

Agent 按需预热 SKILL
识别任务类型时加载 SKILL
只有相关的工作流指导会进入 Context

SKILL vs. 文档

文档	SKILL
供人类阅读	供 Agent 执行
解释命令的作用	解释何时使用它们
静态参考	动态工作流
全面	聚焦任务
独立于 Agent	与 Agent 集成

8 个配套 Skill

Apifox 提供了 8 个配套 Skill：

SKILL	覆盖范围
项目管理	项目、元数据、资源
API 设计	接口、Schema、定义
环境管理	环境、变量
测试用例创建	单接口测试、断言
测试场景管理	多步骤测试、导入、更新
测试套件组织	分组、执行
导入/导出工作流	数据迁移、备份
CI/CD 集成	流水线命令、报告

每个 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

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

获取专属报价与部署方案

详细的私有化部署系统架构与安全白皮书

针对您公司规模的专属报价单

免费的 1v1 专属产品演示 (Demo) 机会

获取部署方案

* 提交后，我们的客户经理将在 1 个工作日内与您联系

林俊锋企业微信

@Apifox 专属顾问

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