validate-skills

验证技能

验证 skills/ 中所有技能是否符合 agentskills.io 规范和 Claude Code 最佳实践。

验证清单

对于每个技能目录，检查：

规范合规性 (agentskills.io)

检查项	规则
name 格式	1-64 个字符，小写字母数字加连字符，无前导/尾随/连续连字符
name 匹配目录	目录名称必须等于 name 字段
description 长度	1-1024 个字符，非空
可选字段有效	如果存在 license、metadata、compatibility 则需有效

最佳实践 (Claude Code)

检查项	规则
描述格式	第三人称，描述做什么 + 何时使用
正文长度	不超过 500 行
加载深度为一层	SKILL.md 是唯一的渐进式披露入口点：每个引用文件必须能从 SKILL.md 到达。引用之间可以相互交叉链接以方便导航（见下方注释）。
链接为 Markdown	使用 [text](path) 而非裸文件名
无冗余	不要在正文中重复描述
简洁	只添加 Claude 尚未拥有的上下文

一层深度 vs. 交叉链接。 一层深度规则针对的是渐进式披露加载链——一个只有先加载另一个引用才能发现的引用（SKILL.md → a.md → b.md，其中 b.md 未从 SKILL.md 链接）。这是缺陷：它会向加载器隐藏内容。

它不禁止导航性交叉链接。根据 AGENTS.md，引用文件以“相关技能”页脚结束，链接同级引用，这是必需的。只要两个端点也能直接从 SKILL.md 到达，交叉链接就是允许的。仅标记那些仅能通过另一个引用到达的引用。

如何运行

1. 查找所有技能目录：

   fd -t d -d 1 . skills/
   

2. 对于每个技能，读取 SKILL.md 并根据上述规则检查

3. 按以下格式报告问题：

   ## 验证结果
   
   ### skills/example-skill
   - [通过] name 格式有效
   - [失败] name "example" 与目录 "example-skill" 不匹配
   - [通过] description 长度正常（156 字符）
   

参考

• agentskills.io 规范
• Claude Code 最佳实践