SuperAPI AI 工具集

skill-yaml-audit-fix

编程与开发

查看项目

更新于 10-16 08:19

技能介绍

用途

该技能用于审计 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 前存在空行
  • 元数据中存在制表符或错误缩进

使用方式

审计工作流:

  1. 枚举 Hermes 技能根目录下的所有 SKILL.md 文件。
  2. 仅解析 frontmatter;不要重写健康的文件。
  3. 将每个失败记录为:路径、失败类别、解析器错误。
  4. 进行最小化修复:对较长的 description 优先使用引号或折叠块标量;保留现有正文内容;避免对无关部分进行大范围重排。
  5. 编辑后重新运行全树验证。
  6. 若不再有失败,报告扫描数量与修复数量。

安全批量检查脚本:

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 块。
  • 不要为了统一风格而批量重写所有技能。
  • 不要使用带行号前缀的文本转储作为重写输入。
  • 如果用户要求全面扫描,不要只修复一个文件就停止。
  • 未在整个技能树上重新运行验证之前,不要声称成功。