用途:指导在 hermes-agent 仓库内(/home/bb/hermes-agent/skills/<category>/<name>/SKILL.md)编写随包发布的技能文件,区别于写入 ~/.hermes/skills/ 的用户本地技能。
主要能力与要求:SKILL.md 必须以 --- 开头并紧跟换行,正文前以 --- 闭合,可被解析为 YAML 映射;必须包含 name 与 description;description ≤1024 字符;闭合 --- 后须有非空正文;全文 ≤100000 字符。validator 不强制 version、author、license、metadata,但同类技能均含,建议保留。name 需小写加连字符、≤64 字符。
结构与放置:目录为 skills/<category>/<name>/SKILL.md,选取仓库已有最接近的分类,不随意新建顶层分类。建议结构为标题、Overview、When to Use(含 Don't use for 反触发)、具体主题正文(可用速查表与精确命令)、Common Pitfalls、Verification Checklist,可选 One-Shot Recipes。同类技能约 8k–14k 字符,超过 20k 宜拆分到 references/*.md 并在 SKILL.md 中引用。
用法:新建用 write_file,不要用 skill_manage(action='create');小改可用 skill_manage(action='patch', name=..., old_string=..., new_string=...);整体重写用 write_file 或 skill_manage(action='edit') 提供完整新内容;支撑文件写入 references/、templates/、scripts/、assets/。完成后执行 git add 并提交。
限制与注意:当前会话的技能加载器已缓存,skill_view / skills_list 在新会话前看不到新技能,属预期行为。related_skills 合并两类来源,但跨仓库引用对他人克隆无效,优先只引用仓内技能。
常见错误:对仓内技能误用 create;--- 前有空白或 BOM 导致校验失败;description 过于笼统而非以 Use when 描述触发类;遗漏 author/license/metadata;重复已有同类技能;期待当前会话立即生效;引用仓内不存在的技能。校验清单涵盖路径、frontmatter 边界、字段齐备、命名与描述长度、文件总长度、结构顺序、related_skills 可解析及已提交。