编写仓库内 SKILL.md:frontmatter、验证器、结构规范
概述
SKILL.md 可以放在两个位置:
- 用户本地:
~/.hermes/skills///SKILL.md — 个人、不共享。通过 skill_manage(action='create') 创建。
- 仓库内(本技能关注此情况):
/home/bb/hermes-agent/skills///SKILL.md — 提交、随包发布。使用 write_file + git add。
注意:
skill_manage(action='create') 不针对仓库树。
使用场景
- 用户要求在"这个分支/仓库/提交"中添加技能
- 你正在提交一个应该随 hermes-agent 发布的可复用工作流
- 你正在编辑
/home/bb/hermes-agent/skills/ 下的现有技能(小改动用 patch,重写用 write_file;skill_manage 的 patch 对仓库内技能有效,但 create 无效)
必需的 Frontmatter
真实来源:
tools/skill_manager_tool.py::_validate_frontmatter。
硬性要求:
- 以
--- 作为前几个字节开头(无前导空行)
- 在正文前以
n---n 闭合
- 解析为 YAML 映射
- 存在
name 字段
- 存在
description 字段,≤ 1024 字符(MAX_DESCRIPTION_LENGTH)
- 闭合
--- 后有非空正文
同伴匹配格式(
skills/software-development/ 下每个技能都使用):
---
name: my-skill-name # 小写、连字符、≤64 字符 (MAX_NAME_LENGTH)
description: Use when . .
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
hermes:
tags: [short, descriptive, tags]
related_skills: [other-skill, another-skill]
---
version /
author /
license /
metadata 不被验证器强制,但每个同伴都有——省略会让你的技能显得突兀。
大小限制
- Description:≤ 1024 字符(强制)
- 完整 SKILL.md:≤ 100,000 字符(强制为
MAX_SKILL_CONTENT_CHARS,约 36k tokens)
同伴技能在
software-development/ 下约 8-14k 字符。以此为目标。如果超过 20k,拆分到
references/*.md 并从 SKILL.md 引用。
同伴匹配结构
每个仓库内技能大致遵循:
#
Overview
一到两段:是什么和为什么。
When to Use
- 要点触发条件
- "Don't use for:" 反触发条件
##
- 快速参考表常见
- 精确命令的代码块
- Hermes 特定配方(通过 scripts/run_tests.sh 测试、ui-tui 路径等)
Common Pitfalls
错误及其修复的编号列表。
Verification Checklist
One-Shot Recipes (optional)
命名场景 → 具体命令序列。
并非每个章节都必需,但 Overview + When to Use + 可执行正文 + pitfalls 是技能感觉像同伴的最低要求。
目录放置
skills///SKILL.md
仓库中当前分类(用
ls skills/ 确认):
autonomous-ai-agents,
creative,
data-science,
devops,
dogfood,
email,
gaming,
github,
leisure,
mcp,
media,
mlops/*,
note-taking,
productivity,
red-teaming,
research,
smart-home,
social-media,
software-development
选择最接近的现有分类。不要随意发明新的顶级分类。
工作流程
1. 调查目标分类中的同伴:
ls skills//
2. 阅读 2-3 个同伴 SKILL.md 文件以匹配语气和结构
3. 如不确定,检查
tools/skill_manager_tool.py 中的验证器约束
4. 用
write_file 起草
skills///SKILL.md
5. 本地验证:
import yaml, re, pathlib
content = pathlib.Path("skills///SKILL.md").read_text()
assert content.startswith("---")
m = re.search(r'n---s*n', content[3:])
fm = yaml.safe_load(content[3:m.start()+3])
assert "name" in fm and "description" in fm
assert len(fm["description"]) <= 1024
assert len(content) <= 100_000
6. 在活动分支上
git add +
git commit
注意:当前会话的技能加载器已缓存——
skill_view /
skills_list 在新会话前看不到新技能。这是预期行为,不是 bug。
交叉引用其他技能
metadata.hermes.related_skills 在加载时合并两棵树(
skills/ 仓库内和
~/.hermes/skills/)。
你可以从仓库内技能引用用户本地技能,但其他用户全新克隆仓库时无法解析。
仓库内技能优先只引用仓库内技能。如果频繁引用的技能只存在于
~/.hermes/skills/,考虑提升到仓库。
编辑现有仓库内技能
- 小修复(错字、添加 pitfall、收紧触发条件):
skill_manage(action='patch', name=..., old_string=..., new_string=...) 对仓库内技能有效
- 重大重写:
write_file 整个 SKILL.md。skill_manage(action='edit') 也有效但需要提供完整新内容
- 添加支持文件:
write_file 到 skills///references/*.md、templates/ 或 scripts/。skill_manage(action='write_file') 也有效并强制 references/templates/scripts/assets 子目录白名单
始终提交编辑——仓库内技能是源码,不是运行时状态。
常见陷阱
- 用
skill_manage(action='create') 创建仓库内技能。它写入 ~/.hermes/skills/,不是仓库树。仓库内创建用 write_file。
--- 前有前导空白。验证器检查 content.startswith("---");任何前导空行或 BOM 会导致验证失败。
- Description 太泛。同伴描述以 "Use when ..." 开头并描述触发类,不是一个任务。"Use when debugging X" > "Debug X"。
- 忘记 author/license/metadata 块。不被验证器强制,但每个同伴都有;省略让技能看起来半成品。
- 写一个重复同伴的技能。创建前,
ls skills// 并打开 2-3 个同伴。优先扩展现有技能而非创建狭窄的兄弟。
- 期望当前会话看到新技能。不会。技能加载器在会话开始时初始化。在新会话中验证或通过确切路径用
skill_view。
- 链接仓库内不存在的技能。
related_skills: [some-user-local-skill] 对你有效但对其他克隆无效。优先只用仓库内链接。
验证清单
- [ ] 文件在
skills///SKILL.md(不在 ~/.hermes/skills/)
- [ ] Frontmatter 从字节 0 开始,以
--- 开头,以 n---n 闭合
- [ ]
name、description、version、author、license、metadata.hermes.{tags, related_skills} 都存在
- [ ] Name ≤ 64 字符,小写 + 连字符
- [ ] Description ≤ 1024 字符且以 "Use when ..." 开头
- [ ] 总文件 ≤ 100,000 字符(目标 8-15k)
- [ ] 结构:
# Title → ## Overview → ## When to Use → 正文 → ## Common Pitfalls → ## Verification Checklist
- [ ]
related_skills 引用在仓库内解析(或明确允许用户本地)
- [ ]
git add skills/// && git commit 在预期分支上完成
评论区