SKILL.md 校验器：检查 Agent Skills 规范与 frontmatter

SKILL.md 文件是 Agent Skills 规范里的一种技能说明书。它通常放在一个独立文件夹中，文件名为 SKILL.md，文件顶部是一段 YAML frontmatter，下方是正文 Markdown 指令。智能体在决定调用哪个技能时，先读取 name 和 description 字段，只有匹配任务时才会加载正文。因此，这个文件不是给普通用户照着读的，而是给 Claude Code 或其他支持 Agent Skills 的智能体做检索和上下文注入用的。

你可以把 SKILL.md 想成技能的入口清单：前页提供元数据，正文提供步骤、命令、约束和示例。一个最小技能只需要名字、描述和几段正文，就能被识别；但要让智能体在正确时机调用，还需要把描述写清楚。SKILL.md 校验器的作用就是在这个文件被发布或调试前，检查结构和规范问题。它会解析 YAML frontmatter，并报告错误、警告和备注三类发现。

SKILL.md 校验器会按照 Agent Skills 规范逐项检查 frontmatter。最核心的两个必填字段是 name 和 description。name 不能超过 64 个字符，只能包含小写字母、数字和单个连字符，不能使用大写、下划线或连续连字符；如果校验时填写了可选文件夹名，名字还要与文件夹名一致。description 不能超过 1,024 个字符，也不能为空。

可选字段中，compatibility 不能超过 500 个字符，license、metadata 等可以按需填写。一个容易出错的地方是 metadata 下可以放自定义键，但顶层出现未知字段会被记为警告。allowed-tools 目前是实验性字段，规范要求使用空格分隔的字符串，而不是 YAML 列表。

下表汇总了校验器重点检查的字段：

如果 frontmatter 缺失、未闭合或 YAML 解析失败，校验器会直接报错。复杂 metadata 可以先借助 JSON 转 YAML 或 YAML 转 JSON 检查结构，避免键值嵌套出错。

description 是技能被调用的触发器。智能体通常不会打开全部技能正文，而是根据任务和描述做匹配。最常被忽略的问题是描述太短或太泛，例如「处理数据」「帮助用户」这类写法几乎等于没有描述。SKILL.md 校验器对少于 60 个字符的描述给出警告，并不判为错误，但这是一个很有用的提醒。

好的描述应该同时包含两层信息：技能做什么，以及什么时候使用。可以用一个短句说明用途，再补一句触发条件。比如「当用户需要把 CSV 按日期汇总成周报时使用，读取本地文件并输出 Markdown 表格」，就比「数据统计技能」明确得多。规范也建议避免只写「用于……」而不说明场景。

如果你不确定是否写到位，可以看校验报告的备注：当描述缺少「when to use」类措辞时，工具会提示。这个提示不是格式错误，而是帮助你提高技能被自动选中的概率。调试「技能从不被调用」的问题时，先把描述改清楚，往往比反复调整正文更有效。

Agent Skills 规范对 SKILL.md 正文没有硬性字数上限，但建议控制在 500 行以内，以及约 5,000 个估算 token 以内。SKILL.md 校验器按每 4 个字符约等于 1 个 token 来估算；对于中文等非拉丁文字，真实 token 数可能偏差更大，所以这个数字更适合作为相对参考。

正文过长会让智能体在每次激活时读入大量上下文，拖慢响应，也更容易把关键步骤淹没在细节里。推荐的做法是：SKILL.md 正文只保留核心流程、简短命令和必要的判断规则；更长的参考手册、示例数据、边角情况说明放到同目录的 references/ 子目录中，通过相对链接引用。

结构上，清晰的标题能让智能体快速定位，但标题层级不要过度嵌套。文件链接应当使用相对路径，且尽量保持一层深度，避免绝对路径和过深嵌套。校验器会对超过 500 行或约 5,000 个 token 的正文给出警告，也会标记绝对路径、过深文件链接以及 TODO、lorem ipsum 这类占位符。发布前删掉占位内容，并把长文拆到 references/，通常能让报告干净很多。

同一个 SKILL.md 文件可能在不同智能体中运行。Agent Skills 规范定义了一组可移植字段，Claude Code 还支持一些扩展字段。SKILL.md 校验器会区分这两类：规范内的字段按规则检查，Claude Code 专有字段出现在顶层时不会报错，只会作为备注说明，因为这些字段在其他智能体中会被忽略。

model、hooks 这类字段就属于 Claude Code 扩展。它们对 Claude Code 有效，但对只实现基础 Agent Skills 规范的工具没有意义。如果你希望技能跨平台分发，最稳妥的方法是把环境相关配置放到 metadata 下，或者接受这个技能主要给 Claude Code 使用的定位。

另一个容易混用的是 allowed-tools。它在某些智能体中用于限制工具调用，但目前仍属于实验性字段，并且规范建议使用空格分隔的字符串，例如 allowed-tools: Read Write，而不是 YAML 列表。如果写成列表，校验器会给出警告。顶层出现未知字段时，同样会提示：这些键不会被所有智能体识别，放入 metadata 更安全。规范字段保证可移植，扩展字段则要清楚边界。

SKILL.md 校验器的报告把发现分成三种严重级别。错误是规范违反，例如 frontmatter 缺失、未闭合、YAML 无效、name 或 description 缺失或超限、正文为空。只要存在错误，文件就不能算有效。警告是偏离规范建议但不阻止加载，例如描述少于 60 个字符、正文超过 500 行或约 5,000 个 token、存在未知字段、allowed-tools 写成列表、正文少于 20 个词，以及出现占位符。备注通常是非阻塞信息，例如 Claude Code 专有字段或实验性字段说明。

有效只表示零错误，不代表内容质量高。校验器不会判断指令是否清晰、步骤是否合理，也不会检查文件链接是否真实存在。报告顶部会显示结论和文件统计，包括字段数、正文行数、估算 token 数等。你可以用 CSV 导出发现，方便在团队流程中存档。

整个校验在浏览器本地完成，不需要注册，也不会把技能内容上传到服务器。对于包含内部流程或敏感命令的技能文件，这一点尤其重要。

当智能体从不调用某个技能时，通常不是文件太复杂，而是触发条件没写好。最常见的静默失败原因是 description 太笼统，缺少「何时使用」的措辞。智能体在任务与技能之间做匹配时，能依赖的信息主要就是这个名字和这一句描述。可以先把描述改成「当用户需要 X 时，使用本技能做 Y」的形式，再运行 SKILL.md 校验器查看备注。

第二类问题是格式错误。比如 frontmatter 没有正确闭合、name 包含大写字母或下划线，或者顶层 name 与文件夹名不一致。这些都会让技能无法进入正常的加载流程。校验器会直接把这些标为错误，修复到零错误即可。

第三类问题是文件超出规模或链接不规范。正文过长不会必然阻止加载，但会让智能体读到的上下文变慢，间接降低被正确使用的概率。把细节拆到 references/，保留简短入口，通常能改善体验。

SKILL.md 校验器免费、无需登录、不上传内容，适合在提交到共享仓库或市场前做一次快速检查。它一次检查一个粘贴的文件，不扫描整个文件夹；如果需要批量检查，可以配合命令行工具使用。