如何用 book-to-skill 的 validate_skill.py 按指定主机规则审计一份 SKILL.md
【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill
book-to-skill 会把书籍转换成 Agent Skill，而同一份SKILL.md可能要在 Claude Code、GitHub Copilot CLI、Amp、Hermes Agent 等不同宿主里运行，各宿主对 frontmatter 字段和allowed-tools工具的接受程度并不相同。仓库自带的 tools/validate_skill.py 就是为这件事提供的审计工具：你指定一个“主机视角”（lens），它会按该宿主的规则检查一份SKILL.md，输出 ERROR / WARN 两类问题，并用退出码告诉你是否有会在该宿主上破坏 skill 的问题。这篇文章说明如何选择 lens、运行审计命令、判读输出。
选择 lens：四种主机规则
脚本通过--lens参数选择规则集，取值及默认值来自其入口定义：--lens claude|copilot|amp|hermes，不传时默认claude（CHANGELOG 1.1.0 说明claude保留为默认是出于 CI 向后兼容）。四个 lens 的差异在 tools/validate_skill.py 的LENSES定义中，要点如下：
| lens | 宿主 | 识别的工具名 | 额外识别的 frontmatter 键 | name 规则 | 未知工具名 |
|---|---|---|---|---|---|
claude（默认） | Claude Code | Bash、Read、Write、Edit、Glob、Grep、WebFetch、WebSearch、NotebookEdit、Task、TodoWrite | name、description、allowed-tools、license | 小写字母/数字/连字符，且不能含保留词anthropic、claude | 报 ERROR 路径处理 |
copilot | GitHub Copilot CLI | shell、bash、write | 同上 | 默认字符集 | 报 WARN（未知 token 可能是 MCP 服务器名，Copilot 接受） |
amp | Amp | Claude 工具集加shell_command | 多识别compatibility、argument-hint | 默认字符集 | 报 WARN |
hermes | Hermes Agent | 不强制执行allowed-tools（enforces_allowed_tools: False） | 多识别version、author、platforms、tags、category、prerequisites、compatibility、environments、setup、related_skills、metadata等 | 小写字母/数字/连字符/点/下划线，且须以字母或数字开头 | 报 WARN |
注意两点：SKILL.md格式本身遵循开放的 Agent Skills 标准，name和description是唯一通用必填字段，lens 之间的分歧主要在于哪些allowed-tools名被识别、哪些额外 frontmatter 键会被接受而非静默忽略；另外仓库 README.md 的目录结构注释里只列了claude|copilot|amp三个 lens，而脚本源码与 docs/architecture.md 的组件表都列出了四个，以脚本源码为准。
运行审计命令
前提是你在 book-to-skill 仓库内（或拿到了脚本与待审计文件），并有python3。该脚本只导入标准库模块（argparse、re、sys、pathlib），无需额外安装依赖。
基本用法（来自脚本 docstring 的 Usage 行）：
python3 tools/validate_skill.py [--lens claude|copilot|amp|hermes] [path/to/SKILL.md]- 不传路径时，默认审计当前目录下的
SKILL.md； - 不传
--lens时，默认按claude规则检查。
几个典型调用：
# 审计仓库自身的 SKILL.md，按默认的 Claude Code 规则 python3 tools/validate_skill.py SKILL.md # 审计某个生成产物，按 GitHub Copilot CLI 规则 python3 tools/validate_skill.py --lens copilot ~/.copilot/skills/<你的skill目录>/SKILL.md # 同一份文件按 Hermes Agent 规则再看一遍 python3 tools/validate_skill.py --lens hermes path/to/SKILL.md其中path/to/SKILL.md是你自己待审计文件的路径，按实际位置替换。
判读输出：ERROR、WARN 与退出码
脚本的严重级别定义（见其 docstring）：
ERROR—— 会破坏或降低该宿主上 skill 效果的问题，会 fail CI；WARN—— 该宿主会忽略它，或只是软性指南，不会 fail CI。
输出由三类行组成（以下格式来自源码中的打印语句，不是某次运行的实录）：
WARN <警告内容> ERROR <错误内容> ✓ <path> [<宿主label>]: no <宿主label>-breaking issues (<N> warning(s))退出码是最终判据：
- 有 ERROR：打印
✗ <path> [<label>]: <N> error(s), <M> warning(s)，并以sys.exit(1)结束，退出码 1； - 没有 ERROR（可能有 WARN）：打印
✓ ... no ...-breaking issues (...)，正常退出，退出码 0。
因此在脚本化流程中，只需检查命令退出码即可判断这份SKILL.md在所选宿主下是否存在破坏性问题。
具体检查哪些项
以下内容对应 tools/validate_skill.py 中audit()函数的实际逻辑：
- frontmatter 解析：文件必须以
---开头的 YAML frontmatter 块开始，否则只报一条no valid YAML frontmatter (--- block)错误并结束。读取使用utf-8-sig编码，带 UTF-8 BOM 保存的SKILL.md也能正确解析（这是 tests/test_validate_skill.py 专门覆盖过的行为）。 name：缺失报 ERROR（必填）；超过 64 字符报 ERROR；不匹配当前 lens 的字符集报 ERROR；Claude lens 下含anthropic或claude保留词报 ERROR。description：缺失报 ERROR（必填）；超过 1024 字符报 ERROR；Hermes lens 下有 60 字符的软上限，超过报 WARN（文档标注为 Hermes 的 house guideline，用于可靠路由）。allowed-tools：当正文包含```bash代码块或出现python3时，如果声明了工具限制却没有包含该 lens 认定的 shell 工具名（如Bash），报 ERROR——提示在该宿主下这些步骤会被拦截。列出的工具名不属于该 lens 已知工具时，claude lens 报 ERROR 相关路径，copilot/amp 报 WARN；hermes lens 不强制allowed-tools，仅给出 WARN。- 未识别的 frontmatter 键：顶层键不在该 lens 的
recognized_keys内时，每个都报一条 WARN，提示该键会被此宿主忽略。 - 正文长度：全文超过 500 行报 WARN，源码注释标明这是软性指南（soft guideline for optimal performance）。
检查在仓库流程中的位置
validate_skill.py不只是手动工具，也是项目质量门的一部分：
- CONTRIBUTING.md 要求提 PR 前运行与 CI 相同的检查，其中包括
python3 tools/validate_skill.py SKILL.md；CI 门禁本身也包含 “SKILL.md validation”（另有 lint 与 py3.10–3.13 测试矩阵）。 - AGENTS.md 把“如果改了
SKILL.md，就跑python3 tools/validate_skill.py SKILL.md”列为验证门之一。 - docs/architecture.md 的组件表将其职责描述为：checks a generated SKILL.md against host rules。
如果你的工作流是生成或修改 skill 后提交，按目标宿主选 lens 跑一遍、退出码为 0 再提交，就是文档规定的最短验证路径。
边界与注意事项
- 无 frontmatter 时审计提前结束，只剩那一条错误，其余规则不会继续跑。
hermeslens 的工具集为空且不强制allowed-tools，它检查的重点是更宽的 frontmatter 键集与 name 字符集，这与其它三个 lens 的侧重点不同。- 同一份
SKILL.md在不同 lens 下结论可能不同（例如某个工具名在 claude 下是 ERROR 级问题，在 copilot 下只是 WARN），这正是“按指定主机规则审计”的意义：以你实际要交付的那个宿主为准，必要时对每个目标宿主各跑一次。
【免费下载链接】book-to-skillTurn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.项目地址: https://gitcode.com/GitHub_Trending/bo/book-to-skill
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
