Skill 文件编写的必要字段规范

写 skill 时，最容易犯的错误不是“不会写内容”，而是把必须字段和补充字段混在一起，结果导致 skill 触发不稳定、结构不统一，后面维护也越来越乱。

这篇文章只讲一个问题：一个 skill 最少必须写哪些字段，分别应该怎么写。

一、一个 skill 至少要有什么

从结构上看，一个 skill 至少需要：

1. 一个独立目录
2. 一个 SKILL.md

也就是说，真正的必要文件只有 SKILL.md。

像下面这种结构，才算一个完整且最小可用的 skill：

skills/
└── vuepress-playground-frame/
    └── SKILL.md

其他目录例如：

• agents/
• references/
• scripts/
• assets/

都不是“必须有”，而是根据复杂度按需补充。

二、SKILL.md 里真正必须的字段

SKILL.md 里真正必须的只有两部分：

1. YAML frontmatter
2. 正文说明

其中 frontmatter 里真正必须的字段只有两个：

• name
• description

例如：

---
name: api-doc-writer
description: 编写和维护接口文档，适用于接口字段说明、请求响应示例、错误码整理等场景。
---

这两个字段缺任何一个，这个 skill 都是不完整的。

三、name 字段怎么写

name 是 skill 的唯一标识，主要作用是：

• 标识这个 skill 是什么
• 给系统和其他 agent 一个稳定引用名
• 作为目录名和 skill 名保持一致

规范建议

name 最好遵守这几个规则：

1. 全小写
2. 单词之间用 - 连接
3. 不要用空格
4. 不要写得太长
5. 目录名和 name 保持一致

例如：

name: vuepress-playground-frame

不推荐这种：

name: VuePress Playground Frame
name: vuepress_playground_frame
name: my skill for vuepress iframe and playground

前两种会让命名风格不统一，后一种则太长，后面引用和识别都不干净。

四、description 字段怎么写

description 是 skill 最重要的字段。

它不只是“介绍这个 skill 是干什么的”，更关键的是：它决定这个 skill 在什么场景下会被触发。

所以 description 不能只写一句模糊介绍，比如：

description: 处理 VuePress 组件

这种写法问题很大：

• 任务边界不清楚
• 触发条件太模糊
• 看不出这个 skill 具体解决什么问题

正确写法

description 最好同时写清楚两件事：

1. skill 做什么
2. 在什么情况下用它

例如下面这种写法就更合理：

description: 为 VuePress 博客添加或维护 PlaygroundFrame 组件，并把本地 playground 文件接入 VuePress 静态构建流程。适用于这些场景：(1) 把 Markdown 里的原生 iframe 嵌入替换为统一组件；(2) 给示例增加刷新、新开、源码入口；(3) 把 playground/ 目录下选定的 HTML 示例发布到 docs/.vuepress/public/playground；(4) 维护基于 manifest 的示例同步脚本；(5) 把已失效的外部 iframe 链接迁移为站内静态路径。

这个版本就同时回答了：

• 它处理什么问题
• 什么时候应该用
• 涉及哪些关键动作

这才是一个合格的 description。

五、正文是不是必须写

是的，正文也是必须写的。

虽然从“字段”角度看，frontmatter 只要求 name 和 description，但如果正文空着，这个 skill 实际上就没有可执行价值。

一个最低可用的正文，至少应该包含：

• skill 解决的问题
• 使用时的基本流程
• 关键文件或关键约定
• 验证方式

例如一个最小正文结构可以是：

# Skill 名称

## 概览

说明 skill 解决什么问题。

## 使用流程

说明执行时应该先看什么、改什么、最后怎么验证。

## 验证

说明改完要跑什么命令确认结果。

也就是说：

• name、description 决定 skill 能不能被识别
• 正文决定 skill 有没有实际价值

六、常见可选项

1. agents/openai.yaml

这个文件常用来补充：

• display_name
• short_description
• default_prompt

这个文件更适合在需要补充 UI 展示信息时加入。

2. references/

当 skill 比较复杂时，可以把长文档拆到 references/ 下。

例如：

• 工作流说明
• API 说明
• 规范文档

当正文已经足够短、信息也不复杂时，可以不拆这个目录。

3. scripts/

只有当某些动作需要稳定复用时，才值得把逻辑抽成脚本。

例如：

• 预构建同步脚本
• 批量处理脚本
• 数据抽取脚本

只有在动作需要稳定复用时，再补这一层最合适。

4. assets/

只有在 skill 需要模板、素材、图标、样板文件时才需要。

如果 skill 本身更偏规范说明型，就不一定需要这一类内容。

七、推荐的最小规范

如果你想让团队里的 skill 都保持统一，我建议至少遵守下面这套最小规范：

必须项

• skill 目录名使用 kebab-case
• 必须有 SKILL.md
• SKILL.md frontmatter 必须有 name
• SKILL.md frontmatter 必须有 description
• name 与目录名保持一致
• 正文必须至少包含“概览”和“验证”

推荐项

• 正文增加“快速开始”或“使用流程”
• 复杂 skill 拆出 references/
• 有 UI 展示需求时增加 agents/openai.yaml
• 有稳定重复动作时增加 scripts/

八、看一个完整示例

例如一个 skill 可以组织成这样：

skills/vuepress-playground-frame/
├── SKILL.md
├── agents/openai.yaml
└── references/workflow.md

这里面：

• SKILL.md 是核心文件
• agents/openai.yaml 负责补充 UI 元数据
• references/workflow.md 负责承载较长的工作流说明

其中真正决定这个 skill 是否完整可用的，还是 SKILL.md 里的：

• name
• description
• 正文流程说明

其他内容更适合作为扩展层，按需要补充即可。

总结

Skill 文件的必要字段其实很少，核心就三件事：

1. 必须有 SKILL.md
2. frontmatter 里必须有 name 和 description
3. 正文必须写清楚流程，否则 skill 只是空壳

如果再往前走一步，可以把规范压缩成一句话：

一个合格的 skill，最小要求不是“文件多”，而是“name 清晰、description 可触发、正文可执行”。

这才是 skill 编写时最重要的结构规范。