搞懂 Hermes Skill.md
写在前面
刚开始接触 Hermes Agent 的时候，我对”写技能”这件事是有点怵的。
打开别人写的 SKILL.md，YAML 头一堆字段、正文几百行 Markdown、底下还挂着 references/ scripts/ 目录……第一反应是：这玩意是不是有一套很严格的规范？我随便写会不会被框架嫌弃？
折腾了几个技能下来才发现——我想多了。
Hermes Skill 的规矩，其实只有薄薄一层。今天就用大白话把它讲清楚，让你下次写技能的时候，心里有底，手上不慌。
一句话结论
元数据按格式来，内容随你浪。
就这一条。记住它，你已经会写 Hermes 技能的 80% 了。
为啥说元数据是”身份证”
我喜欢拿身份证打比方，因为它真的太像了。
你的身份证为啥每个字段都不能乱填？因为它不是给你自己看的，是给系统识别用的。姓名栏写”哈哈哈”、出生日期写”很久以前”，派出所的系统直接就不认了。
Hermes 的元数据（也就是 SKILL.md 顶部那段 YAML）是一模一样的逻辑：
graph LR
A[你写的 Skill] --> B{元数据<br/>身份证}
B -->|格式正确| C[skill_list 能找到 ✅]
B -->|格式正确| D[skill_view 能加载 ✅]
B -->|格式错误| E[框架直接装瞎 ❌]
A --> F[技能正文<br/>你的地盘]
F --> G[业务逻辑随便写]
F --> H[代码示例随便贴]
F --> I[Mermaid/表格随便画]
classDef hard fill:#EF4444,stroke:#DC2626,color:white
classDef free fill:#10B981,stroke:#059669,color:white
class B,C,D,E hard
class F,G,H,I free
红色那块（元数据）是框架的地盘，必须按规矩来；
绿色那块（正文）是你的地盘，怎么爽怎么写。
skill_list、skill_view 这些工具压根不关心你的技能是干嘛的，它们只认元数据里那几个固定字段。字段名错一个字、缩进多一个空格，工具就当这个技能不存在。
内容为啥能”完全自由”
因为框架根本不读你的正文。
skill_view 干的事，本质上就是把你写的 Markdown 原样吐出来给 Agent 看。它不解析、不校验、不限制。
所以你的 SKILL.md 正文里：
- 想写技术教程？随便。
- 想写一段故意搞笑的吐槽？也行。
- 想塞 200 行 Python 示例代码？没问题。
- 想嵌套五层 Mermaid 图？框架眨都不眨眼。
正文是写给 Agent（也就是未来的你或别人）看的，框架只是个传话的。
唯一的小坑：path 参数
讲完爽点，得提一个新人 100% 会踩的小坑——skill_view(name, path) 里那个 path 参数。
如果你的技能不只有 SKILL.md，还挂了 references/api.md、scripts/run.py 这些文件，想读它们的时候得这么调：
skill_view(name='my-skill', file_path='references/api.md')坑点在哪？
path必须是技能目录下真实存在的相对路径- 路径错一个字，直接报错”文件不存在”
- 这跟”内容自由”不冲突——文件内容你随便写，但文件名得对得上
简单说：内容自由，寻址不能错。
一份能直接抄的标准技能模板
光说不练假把式，给你一份最小可用、字段齐全的模板，复制改改就能用：
---
name: my-first-skill
description: 一句话说清这个技能是干嘛的，让人扫一眼就懂
version: 1.0.0
author: 你的名字
license: MIT
language: zh-CN
metadata:
hermes:
tags: [tag1, tag2, 标签3]
related_skills: [其他相关技能名]
---
# 我的第一个技能
## 概述
这里写技能的整体定位，2-3 句话讲清楚解决什么问题。
## 使用场景
- 场景 1：什么情况下该加载这个技能
- 场景 2：什么任务用它最合适
## 核心步骤
1. 第一步该干啥
2. 第二步该干啥
3. 验证结果的方法
## 注意事项 / 踩坑提醒
- ⚠️ 已知坑点 1
- ⚠️ 已知坑点 2
## 示例
（贴代码、贴命令、贴对话示例都行）字段拆解：
| 字段 | 必填 | 干啥用的 |
|---|---|---|
name | ✅ | 技能唯一标识，用小写+连字符 |
description | ✅ | Agent 决定要不要加载它的关键依据，写好这一句比啥都重要 |
version | ✅ | 版本号，方便追踪迭代 |
metadata.hermes.tags | 推荐 | 标签，帮 Agent 做关联匹配 |
metadata.hermes.related_skills | 推荐 | 相关技能，方便链式加载 |
其他像 author、license 这些，写上更规范，不写也不会报错。
总结
回到开头那句话：
元数据按格式来，内容随你浪。
- 元数据是给框架看的身份证 → 严格守规矩
- 正文是给 Agent 看的说明书 → 怎么舒服怎么写
- 唯一的小约束：附加文件的 path 别写错
理解了这个分层，你写 Hermes Skill 的心理负担瞬间就没了。框架其实比你想象的宽容得多，它只在自己必须管的地方坚持原则，剩下的全交给你发挥。
下次再打开一个空白的 SKILL.md，别再纠结”我这样写规不规范”了——把元数据填对，剩下的，写就完了。🚀