核心功能#

Frontmatter 硬约束#

tools/skill_manager_tool.py::_validate_frontmatter 是真相之源：

• 文件第一字节必须是 ---，禁止前导空行或 BOM
• 闭包必须是 \n---\n
• 解析后必须是合法 YAML mapping
• 必须含 name 和 description
• description 长度 ≤ 1024 字符（MAX_DESCRIPTION_LENGTH）
• 闭包之后必须还有正文（不能只写 frontmatter）

Frontmatter 软约定#

以下字段不被 validator 强制，但仓库里每个 peer skill 都有：

1
---
2
name: my-skill-name               # 小写、连字符、≤64 字符
3
description: Use when <trigger>. <one-line behavior>.
4
version: 1.1.0
5
author: Hermes Agent
6
license: MIT
7
metadata:
8
  hermes:
9
    tags: [short, descriptive, tags]
10
    related_skills: [other-skill, another-skill]
11
---

version / author / license / metadata 一旦缺失，skill 会显得”半成品”——这是隐性的同侪压力。

写作质量八原则#

1. 优化过程的可预测性：每句话问一句”加载这份 skill 后，模型行为应当改变什么？“答不上来就删。
2. 选对上下文载荷：description 每次都会被模型读，贵。要的是触发场景，不是任务细节。
3. 建立信息层级：必读的放 SKILL.md，分支细节扔 references/ / templates/ / scripts/，按需指针引用。
4. 每一步写完成判据：好判据 = 可勾选 + 在意时穷举。"每个被改的文件都对得上" 比 "总结改动" 强得多。
5. 规则紧贴概念：定义、例外、例子、验证就近放，不要散到全文。
6. 用强引导词：让模型更熟悉、tight loop / tracer bullet / root cause / regression test 比长篇解释省 token 也更稳。
7. 删重复 + 删 no-op：每个意思只留一处。句子级别问一句”这句不改模型默认行为吗？“——那就删。
8. 警惕过早完成：如果模型老想跳步，先把当前这一步的判据写尖锐，别急着拆步骤。

标准骨架#

1
# 标题
2

3
## Overview
4
一两段：是什么、为什么。
5

6
## When to Use
7
- 触发场景列表
8
- "Don't use for:" 反向触发
9

10
## 主体
11
- Quick-reference 表格
12
- 精确命令的代码块
13
- Hermes 特定配方（如 scripts/run_tests.sh、UI-TUI 路径）
14

15
## Common Pitfalls
16
编号列表：错在哪 + 怎么修。
17

18
## Verification Checklist
19
- [ ] 可勾选的验证项

不是每个 section 都强制，但 Overview + When to Use + 主体 + Pitfalls 是下限。

目录放置#

1
skills/<category>/<skill-name>/SKILL.md

现有 category：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。不要随手发明新顶层分类。

本地校验脚本#

写完后，跑一次这个最小校验，5 秒内发现格式问题：

1
import yaml, re, pathlib
2
content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
3
assert content.startswith("---")
4
m = re.search(r'\n---\s*\n', content[3:])
5
fm = yaml.safe_load(content[3:m.start()+3])
6
assert "name" in fm and "description" in fm
7
assert len(fm["description"]) <= 1024
8
assert len(content) <= 100_000
9
print("ok")

常见坑位#

1. 用 skill_manage(action='create') 创建仓库内 skill：它写到 ~/.hermes/skills/，不在仓库里。仓库内创建请用 write_file。
2. frontmatter 前面有空行 / BOM：validator 检 startswith("---")，一点前导空白就 fail。
3. description 太通用：“Debug X” 不如 “Use when debugging X”——前者描述任务，后者描述触发类。
4. 忘写 author/license/metadata：validator 不拦，但每个 peer 都有，少了就是显眼的不专业。
5. 写了和 peer 重复的 skill：开写前 ls skills/<category>/ 看 2-3 个 peer，能扩展就别造新窄兄弟。
6. 期望当前会话立刻看到新 skill：不会的。skill loader 在 session 开始时初始化。需要新会话或重启。
7. 让 skill 累积”沉积层”：加规则就把旧的覆盖掉，别堆叠。skill 应当越维护越精炼。
8. 写 no-op 散文：“be careful” / “be thorough” / “use best practices” 几乎不改模型行为。换成可勾选的判据或强引导词。
9. 引用仓库里不存在的 skill：related_skills: [some-user-local-skill] 自己能用，但别人 clone 后会断链。只引用仓库内。

我为什么推荐它#

它是一份少见的”反完美主义”指南：

• 不教你写得更好，教你删掉没用的。
• 不教你用什么花哨结构，教你匹配同侪。
• 不教你打造”最强 skill”，教你让它通过 validator + review。

对一个长期维护 Hermes 工作流的人来说，这套约束能直接把”我写的 skill 怎么总不像官方”的不爽解决掉——先遵守硬约束，再用八原则自检，最后按骨架对齐，三步就到位。

🐦 咕咕觉得：很多 skill 作者的问题不是写得太差，而是写得太多。八原则第 7 条 “删 no-op” 几乎能独立解决一半问题。

信息卡#