技能验证工具

要解决什么问题

手写过 SKILL.md 的人大概都有类似经历：frontmatter 少了个字段、缩进用错了制表符，或者 description 写得含糊，本地看着没问题，丢到运行环境里却加载失败或直接不触发。这类问题靠肉眼排查很费时间，因为错误往往藏在细节里，而且一个技能目录里往往有多个文件，彼此间的引用关系也不一定记得清。

skillcheck 就是为这件事准备的。它把「技能文件是否合规」这件事变成一个可重复执行的命令行检查，让你在提交或安装前先跑一遍。

核心能力与关键步骤

默认情况下，skillcheck 执行的是符号层面的检查，覆盖 frontmatter 结构、字段格式、文件引用等可静态验证的内容。报告会分成三个级别：

• errors：必须修复的问题，对应退出码 1
• warnings：建议关注但不阻塞的问题
• info：提示性信息

退出码的设计可以直接接入 CI。0 代表干净通过，1 代表存在错误，或者在 --strict 模式下存在警告，或者在 --fail-on-regression 模式下出现回归。2 说明命令本身用错了，参数或输入有问题。3 比较有意思：符号层面全部通过，但接入的 agent critique 发现了语义层面的问题，比如 description 和实际功能对不上。

针对语义自检，skillcheck 支持发出提示词并把返回的 JSON 结果纳入校验流程。能力图相关的工作也有专门的接口可用。配置文件 skillcheck.toml 则用来固化 CLI 默认值和 frontmatter 扩展字段，避免每次手动传参。

适用边界与注意点

符号检查能覆盖的主要是结构合规性，语义层面的判断依然依赖 agent critique，这不是万能的。如果你的技能 description 用词本身就不准确，critique 可能会漏掉，或者产生误报。另外，--strict 会把 warning 升级为失败，意味着一些风格性建议也会阻断流程，按需开启。