如何为SearchCLI编写自定义Skill：从SKILL.md到安装校验的完整开发者指南

SearchCLI 是集成 AI 搜索、推荐与对话检索的开源命令行工具（CLI 命令为 vs）。本文是一份面向新手开发者的完整指南：教你如何用 skill init 一键生成脚手架、逐字段读懂 SKILL.md 的 frontmatter 元数据，并顺利通过 skill validate 校验与 skill install 安装，把自定义 Skill 发布给 Codex、Agents、Trae 等各类 AI Agent 客户端。

一、什么是 SearchCLI 的 Skill？

Skill 本质上是一个"写给 Agent 看的操作手册"：一个目录 + 一份 SKILL.md 文件，用来告诉外部 Agent 什么时候该用、用什么命令、按什么流程执行 SearchCLI 的能力。

仓库内置了 13 个官方 Skill（如 vs-search、vs-search-tuning、vs-shared），你可以在 skills/ 目录中逐个查看，例如：

• 搜索场景调试手册：skills/vs-search/SKILL.md
• 首次环境配置手册：skills/vs-shared/SKILL.md
• 全量 Skill 清单与文件映射：skills/manifest.json

自定义 Skill 的典型价值：

场景	说明
团队内部流程沉淀	把"如何给应用绑定数据集"等 SOP 固化成 Agent 可执行步骤
Agent 精准调用 CLI	通过 commands 字段声明该 Skill 依赖哪些 vs 命令，避免 Agent 乱猜参数
多客户端分发	同一份 Skill 可安装到 Codex、Agents、Trae 等客户端的 skills 目录

二、准备工作：克隆仓库与命令速览

在宿主机真实终端中克隆仓库（不要放进沙箱执行）：

git clone https://gitcode.com/gh_mirrors/se/SearchCLI

安装并确认 CLI 可用后，与 Skill 开发相关的命令共 6 条（完整清单见 docs/COMMANDS.md）：

vs skill list                          # 查看可用 Skill
vs skill show --name vs-search         # 查看某个 Skill 的完整元数据
vs skill search --query "search debug" # 按关键词搜索 Skill
vs skill init <skill-name>             # 生成新 Skill 脚手架
vs skill validate                      # 校验 skills 目录
vs skill install <name|all>            # 安装到 Agent 客户端

💡 提示：skill init / validate 支持 --root <dir> 参数，可以在仓库外的任意目录开发 Skill，不必改动仓库本身。

三、第一步：用 skill init 生成 Skill 脚手架

vs skill init 会创建一个目录和一份带 TODO 占位符的 SKILL.md，并立即执行一次校验。Skill 命名只允许小写字母、数字和连字符（校验逻辑见 src/skills/repo-skills.ts），例如 my-data-export 合法，My_Data 不合法。

最简用法：

vs skill init my-data-export --root /tmp/skill-dev

带上元数据一次到位：

vs skill init my-data-export \
  --root /tmp/skill-dev \
  --category data \
  --keywords "data export,dataset get" \
  --commands "dataset get,dataset list,skill list"

关键参数说明（定义见 src/commands/skill/init.ts）：

参数	作用	默认值
--root	脚手架写入的 skills 根目录	仓库内置 skills/ 目录
--category	分类	workflow
--keywords	帮助 Agent 发现该 Skill 的逗号分隔关键词	Skill 名 + 分类 + 命令列表
--commands	该 Skill 引用的 SearchCLI 命令（逗号分隔）	skill list, skill show
--requires-cli	最低 CLI 版本要求	>=0.1.0
--force	目录已存在时覆盖	关闭

⚠️ 注意：--commands 里的每一项都会被真实校验，写一个不存在的命令（比如 data upload）脚手架会直接报错，这正是它帮你"早发现早修正"的机制。

四、第二步：解剖 SKILL.md 的 frontmatter

生成的 SKILL.md 头部是一段 YAML frontmatter，全部字段均为必填项，解析与校验逻辑位于 src/skills/repo-skills.ts：

---
name: my-data-export
description: "Describe when external agents should use my-data-export."
category: data
applies_to: codex, agents, external-agent
requires_cli: ">=0.1.0"
keywords: data export, dataset get
commands: dataset get, dataset list
---

各字段规则一览：

字段	规则	常见错误
name	必须与目录名完全一致	directory name must match skill name
description	一句话说明触发时机	frontmatter missing description
category	七选一：shared app data search recommend chat workflow	unsupported category
applies_to	三选多：codex agents external-agent	unsupported applies_to target
requires_cli	必须形如 >=x.y.z	requires_cli must look like >=0.1.0
keywords	至少一个，逗号分隔	frontmatter missing keywords
commands	每项必须是真实存在的 vs 命令	unknown command in commands

requires_cli 的意义在于安装时的版本兼容性检查：若你本机 CLI 版本低于 Skill 声明的最低版本，skill install 会直接拒绝安装并提示升级（见 src/skills/repo-skills.ts）。

五、正文五个必备章节怎么写

frontmatter 之后是 Markdown 正文。SearchCLI 要求必须包含以下 5 个二级标题（常量定义见 src/skills/repo-skills.ts）：

# My Data Export

## When to Use
说明 Agent 在什么场景下应选用本 Skill（1~3 句即可）。

## Preconditions
- 前提条件用无序列表，例如：已配置 `vs auth status` 可用
- 需要一个可用的 dataset-id

## Commands
- `dataset get`: 获取数据集详情与 Schema
- `dataset list`: 列出全部数据集

## Workflow
1. 先用 `dataset list` 找到目标数据集
2. 用 `dataset get` 拉取 Schema
3. ……

## Constraints
- 只使用公开 `vs` 命令，不要绕过 CLI 直接调底层 API
- 写入类操作前必须先向用户确认

写作建议（参照官方 skills/vs-search/SKILL.md 的风格）：

1. Commands 章节写成 `命令`: 说明 的格式——CLI 会解析成结构化摘要展示给 Agent（解析逻辑见 src/skills/repo-skills.ts）；
2. Workflow 用有序列表，每一步对应一条具体命令，Agent 会逐步执行；
3. Constraints 写"红线"：什么不能做、失败时怎么办，比写"该做什么"更能降低 Agent 出错率。

六、第三步：用 skill validate 完成安装前校验

修改完 SKILL.md 后，运行校验命令：

vs skill validate --root /tmp/skill-dev

它会扫描根目录下每个 Skill，逐项检查 frontmatter 完整性、目录名一致性、重复命名、commands 是否真实存在、五个必备标题是否齐全，输出形如：

ok: true
count: 1
errors: []

只要 errors 非空，skill install 会整体拒绝安装并逐条列出问题（见 src/skills/repo-skills.ts），所以养成"改完必校验"的习惯能省很多排查时间。

仓库维护者还可以用 Node 脚本做 CI 校验，规则与 CLI 完全一致：

node scripts/validate-skills.mjs

脚本见 scripts/validate-skills.mjs。

七、第四步：skill install 把 Skill 交给 Agent

校验通过后即可安装。安装目标由 --target 决定（参数定义见 src/commands/skill/install.ts）：

取值	写入目录
global（默认）	本机已存在的全部 agent skills 目录（~/.codex/skills、~/.agents/skills、~/.claude/skills 等 30+ 个）
codex	~/.codex/skills
agents	~/.agents/skills
trae / trae-cn	~/.trae/skills / ~/.trae-cn/skills
--dest <dir>	显式指定任意目录（优先级高于 --target）

只装给自己在用的客户端，避免污染其他目录：

vs skill install my-data-export --root /tmp/skill-dev --target trae-cn

目录已存在时加 --force 覆盖；加 --json 可输出结构化结果便于脚本处理：

vs skill install my-data-export --root /tmp/skill-dev --target codex --force --json

安装成功后，对应的 my-data-export/SKILL.md 会出现在目标客户端的 skills 目录下，Agent 在会话中即可按 When to Use 的语义自动发现并引用它。

八、常见报错速查

报错信息	原因与解法
Invalid skill name	名称含大写/下划线，改为小写字母+数字+连字符
Unknown command in skill template	commands 里写了不存在的命令，用 vs --help 核对后修正
Repo skills validation failed	存在校验错误，先看 vs skill validate 输出的 errors 列表
Skill destination already exists	目标目录已存在同名 Skill，确认无误后加 --force
Skill version compatibility check failed	本机 CLI 版本低于 requires_cli，升级 CLI 或调低声明版本
No existing skill installation target	global 模式没检测到任何 agent 目录，改用 --target codex 或 --dest <dir> 显式指定

九、完整流程回顾

1. vs skill init <name> --root <dir> 生成脚手架；
2. 补齐 frontmatter 七个字段 + 五个必备章节；
3. vs skill validate --root <dir> 确认 errors: []；
4. vs skill install <name> --target <client> 分发到目标 Agent；
5. 用 vs skill show --name <name> 复核最终生效的元数据。

更多 Skill 设计细节可参考官方实现：skills/vs-search-tuning/SKILL.md、skills/vs-item-onboarding/references/worked-example.md，以及 Skill 命令域的整体调度实现 src/app/skill-commands.ts。掌握"脚手架 → 元数据 → 校验 → 安装"这条主线，你就能把团队的任何运维经验沉淀为 Agent 可直接执行的 SearchCLI 自定义 Skill。