用途
该技能用于审计 Hermes 的 SKILL.md 文件,检查其 YAML frontmatter 是否损坏,并在大规模场景下安全地修复无效的 frontmatter。当技能加载器报告 YAML 无效、某个 SKILL.md 解析失败、用户希望扫描本地全部 Hermes 技能的 frontmatter 问题,或大批量编辑技能包后可能出现 frontmatter 漂移时,适合使用本技能。
主要能力
- 枚举 Hermes 技能根目录下的所有 SKILL.md 文件。
- 仅解析 frontmatter,不重写健康的文件。
- 记录每个失败项,包括路径、失败类别和解析器错误。
- 进行最小化修复:对较长的 description 优先使用引号或折叠块标量;保留现有正文内容;避免对无关部分进行大范围重排。
- 编辑后重新运行全树验证;若无失败,则报告扫描数量与修复数量。
验证规则
有效的 SKILL.md 必须满足:
- 从字节 0 开始即为
--- - 在正文之前有闭合的
---分隔符 - frontmatter 可解析为 YAML 映射
- 至少包含
name和description - 正文非空
常见失败模式:
- 未加引号的单行 description 中包含
: - 折叠文本被粘贴到一行,且带有 YAML 敏感标点
- 缺少闭合分隔符
- frontmatter 前存在空行
- 元数据中存在制表符或错误缩进
使用方式
审计工作流:
- 枚举 Hermes 技能根目录下的所有 SKILL.md 文件。
- 仅解析 frontmatter;不要重写健康的文件。
- 将每个失败记录为:路径、失败类别、解析器错误。
- 进行最小化修复:对较长的 description 优先使用引号或折叠块标量;保留现有正文内容;避免对无关部分进行大范围重排。
- 编辑后重新运行全树验证。
- 若不再有失败,报告扫描数量与修复数量。
安全批量检查脚本:
python - <<'PY'
import yaml, pathlib
root = pathlib.Path('~/.hermes/skills').expanduser()
bad = []
for path in sorted(root.rglob('SKILL.md')):
text = path.read_text(encoding='utf-8')
if not text.startswith('---\n'):
bad.append((path, 'frontmatter_start', 'does not start with ---'))
continue
parts = text.split('\n---\n', 1)
if len(parts) < 2:
bad.append((path, 'frontmatter_close', 'missing closing --- delimiter'))
continue
fm = parts[0][4:]
try:
data = yaml.safe_load(fm)
if not isinstance(data, dict):
bad.append((path, 'frontmatter_type', type(data).__name__))
except Exception as e:
bad.append((path, 'yaml', str(e)))
for item in bad:
print('\t'.join(map(str, item)))
PY
修复规则:
- 如果单行 description 中包含未转义的冒号,将其转换为带引号的标量,或使用
>-的折叠块。 - 对较长的散文式 description 优先使用
>-。 - 保持合理的行宽,并优先使用 ASCII,除非文件本身已使用非 ASCII 字符。
- 不要为了修复仅 frontmatter 的问题而重写整个技能正文。
示例修复:
错误:
description: Long summary with a colon: and more prose that YAML misreads.
正确:
description: >-
Long summary with a colon: and more prose that YAML now treats
as folded text.
验证清单:
- 已在本地重新验证被编辑的文件
- 已重新运行全树 YAML/frontmatter 审计
- 确认仅损坏的技能被修改
- 除非正文也需要修复,否则正文内容保持不变
- 已报告扫描数量与修复数量
适用场景
- 技能加载器报告 YAML 无效。
- 某个特定的 SKILL.md 无法解析。
- 用户希望对本地全部 Hermes 技能进行 frontmatter 问题扫描。
- 大批量编辑技能包后,frontmatter 可能出现漂移。
限制与注意事项
- 不要假设解析器报错行是唯一有问题的行;应阅读整个 frontmatter 块。
- 不要为了统一风格而批量重写所有技能。
- 不要使用带行号前缀的文本转储作为重写输入。
- 如果用户要求全面扫描,不要只修复一个文件就停止。
- 未在整个技能树上重新运行验证之前,不要声称成功。