如何开发一个 Skill，什么是 Skills，如何检查

什么是 Skill

Skill 是给 AI Agent 使用的一份“可复用能力包”。它把某类任务的触发条件、操作步骤、工具命令、示例和验收标准写在一起，让 Agent 在遇到相似任务时按固定方法执行，而不是每次自由发挥。

一个 Skill 通常包含：

SKILL.md：入口文件，包含名称、描述、适用场景、步骤、示例和检查方法。
scripts/：可执行脚本，例如数据采集、格式转换、校验。
references/：参考文档、模板、规则。
assets/：图片、配置模板等静态资源。

Skill 不是普通代码库，它更接近“带工具的操作手册”：核心是让 Agent 知道什么时候用、按什么顺序做、怎么验证做对了。

Skill 的组成

一个最小 SKILL.md 示例：

---
name: api-test-generator
description: 根据 OpenAPI 文档生成接口测试用例。适用于新增接口、接口回归、契约测试等场景。
---

# API Test Generator

## 何时使用

- 有 OpenAPI/Swagger 文档
- 需要生成正向、异常、边界和鉴权用例

## 步骤

1. 读取 OpenAPI 文档，提取路径、方法、参数和响应结构。
2. 按业务模块分组。
3. 为每个接口生成：正常、缺参、类型错误、越权、边界值用例。
4. 输出 pytest 测试文件并运行。
5. 校验失败用例，区分用例问题和接口问题。

## 验收

- 每个接口至少有 5 类用例
- 生成文件可执行
- 失败用例有明确原因

如何开发一个 Skill

1. 先定义触发边界

描述要具体，包含任务关键词、输入形态和典型场景。描述太泛会导致 Skill 被错误触发，太窄又不会被选中。

好的描述：

根据 OpenAPI 文档生成 pytest 接口测试用例，适用于新增接口、契约测试和回归测试。

不好的描述：

帮助测试。

2. 明确输入、输出和前置条件

写清楚需要什么输入（文件、URL、环境、账号）、产出什么（测试文件、报告、清单）、依赖什么工具。缺少前置条件时，Agent 应该先询问或停止，而不是猜。

3. 把流程拆成可执行步骤

每一步都要能落地：

用哪个命令
读哪个文件
产出什么中间结果
失败时怎么处理

避免“分析一下”“优化一下”这种没有验收标准的步骤。

4. 加脚本和模板

重复、易错、需要精确格式的操作，尽量固化成脚本。例如：

解析 OpenAPI
生成测试骨架
校验链接和资源
汇总报告

脚本要支持参数、错误退出码和幂等执行。

5. 写验收和自检

每个 Skill 都要有“怎么证明做对了”：

文件是否生成
命令是否成功
用例是否通过
输出是否符合模板
是否有残留关键词或敏感信息

6. 测试触发和流程

至少测三类：

该触发：任务描述匹配时，Agent 是否加载 Skill。
不该触发：相似但不相关的任务，是否不会误用。
执行正确：按 Skill 跑一遍，产出是否符合验收标准。

7. 版本和维护

记录变更和废弃说明
保持脚本可重复执行
定期清理过时步骤
对破坏性操作加确认和回滚说明

如何检查一个 Skill

可以用下面的清单：

检查项	关注点
结构	`SKILL.md`、frontmatter、脚本、引用路径是否完整
触发	description 是否具体，能否被正确匹配
步骤	是否可执行、顺序清晰、有失败处理
工具	命令、参数、权限、退出码是否明确
安全	是否有删除、覆盖、密钥泄露风险
验收	是否有可验证的完成标准
可维护	是否幂等、可重复、易更新
回归	修改后是否重新测试触发和执行

在 ZCode 中搭建和检测 Skill（/ 菜单）

先看懂 `/` 菜单

在 ZCode 输入框里输入 /，会打开命令面板，底部提示是“输入内容以搜索命令、技能或子智能体”。面板里通常分为：

命令：例如 /init，用于执行一个固定动作。
计划模式：切换到计划模式。
技能：以 $ 开头，例如 $brainstorming、$computer-use、$control-browser。
子智能体：可以委派任务的角色。

技能后面的来源标签很重要：

用户：来自用户级 skills 目录，你自己安装或编写的。
插件：来自已安装插件的 skills 目录，由插件提供。

所以检查“当前用了什么 skill”，最直接的方法就是输入 /，看“技能”分组里有哪些 $name，以及它们的来源和描述。

如何搭建一个 Skill

创建目录和入口文件

用户级：

C:\Users\<你的用户名>\.agents\skills\<skill-name>\SKILL.md

插件级：

<插件缓存目录>\skills\<skill-name>\SKILL.md

写 frontmatter

---
name: my-skill
description: 当用户需要做 XXX 时使用；包含关键词 A、B、C，并说明适用场景。
---

description 是触发入口，要写清楚“什么时候用”，不要只写“帮助测试”。

写执行步骤
包括输入、输出、前置条件、命令、失败处理和验收标准。重复操作尽量固化成脚本。
重新加载或重启 ZCode
重新加载后输入 /，在“技能”分组里确认出现 $my-skill，来源显示为“用户”或“插件”。
测试调用
可以直接输入 $my-skill，也可以描述一个匹配的任务，观察 Agent 是否加载并按步骤执行。

如何检测 Skill 是否生效

检查项	方法
是否被发现	输入 `/`，看“技能”分组是否有 `$skill-name`
来源是否正确	看标签是“用户”还是“插件”
描述是否匹配	选中技能查看 description，确认触发条件
文件是否完整	检查 `SKILL.md`、frontmatter、脚本路径
是否能执行	用 `$skill-name` 或匹配任务实际跑一遍
是否误触发	用不相关任务测试，确认不会被错误加载
是否按步骤执行	检查输出是否符合 Skill 的验收标准

如果 / 里看不到：

检查目录名、文件名是否是 SKILL.md（大小写敏感）。
检查 frontmatter 是否是合法 YAML，name 和 description 是否存在。
检查插件是否启用、是否需要重启 ZCode。
检查文件是否在正确的 skills 根目录下。

Skill、MCP、Command 的区别

类型	入口	用途
Skill	`/` → 技能 → `$name`	可复用的操作流程和知识包
MCP	工具调用 `mcp__<server>__<tool>`	连接外部系统、数据和工具
Command	`/name`	固定快捷动作或工作流

/ 菜单主要展示命令、技能和子智能体；MCP 工具通常不在 / 里逐条列出，而是以工具名出现在 Agent 可调用的工具列表中。下一题会详细讲 MCP 的搭建和检测。

常见问题

描述太泛：Agent 经常误触发或根本不触发。
只有原则没有命令：Agent 知道要做什么，但不知道怎么执行。
没有验收：做完无法判断对错。
硬编码路径和账号：换环境就失败。
破坏性操作没有确认：容易误删或覆盖。
脚本不幂等：重复执行产生重复数据。

面试回答模板

Skill 是给 Agent 的可复用能力包，核心是触发描述、执行步骤、工具脚本和验收标准。开发时先定义适用边界，再把流程拆成可执行步骤，把重复操作固化成脚本，最后用“该触发、不该触发、执行正确”三类测试验证。检查时重点看结构、触发准确性、步骤可执行性、安全性、验收标准和可维护性。