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 还需要知道如何将任务拆解为跨业务的执行流程。这类经验既不能全部塞入工具描述（上下文无法承受），也不能零散地放置在对话上下文里（更换会话即丢失），更不能指望模型硬记（这是产品专属知识，而非通用常识）。
这些隐藏的工作流和“业务陷阱”必须有明确的指导。
示例：测试场景维护
以维护一个复杂的测试场景为例。
错误的做法（Agent 从零手写）：
Agent: "我将手动创建测试场景结构"
Agent: 编写包含断言、提取器、处理器的完整步骤数组
结果: 字段错误、比较器错误、缺少必填字段
CLI: 拒绝写入或创建了不完整的场景正确的做法（编码在 SKILL 中）：
| 步骤 | 原因 |
|---|---|
| 1. 从接口或用例导入现有步骤 | 避免手写复杂结构 |
| 2. 回读完整结构 | 查看实际导入的格式 |
| 3. 进行本地修改 | 基于准确的基础操作 |
| 4. 更新前验证 | 在本地捕获错误 |
| 5. 运行场景 | 验证行为是否正常 |
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 获取真实结构，而不是凭空想象步骤内部的用例。”
为什么这很重要：
没有 get --with-case-detail | 有 get --with-case-detail |
|---|---|
| 步骤仅显示 ID | 步骤显示完整的用例结构 |
| Agent 不知道内部格式 | Agent 看到实际的断言/提取器格式 |
| Agent 猜测字段名称 | Agent 基于真实示例工作 |
获取真实结构，才能避免凭空想象的更新。
可进化性：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，识别到任务类型时再加载，只有相关的工作流指导会进入 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 负担
