如何创建自定义 Hermes Agent 技能

技能是你在不修改源代码的情况下，能够教会 Hermes Agent 的最小行为单元。它只需一个文件夹、一个 Markdown 文件和一段简短的 YAML 头部。Nous Research 官方文档将该格式描述为"因简单而可移植"，只要掌握其结构，编写一个自定义技能不超过五分钟。

本教程将带你完整走过这一流程：技能在磁盘上的存储位置、SKILL.md 头部必须包含哪些字段、智能体在运行时实际读取哪些章节、如何通过 required_environment_variables 注入密钥，以及如何验证技能已正确加载。完成后，你将拥有一个可以直接放入 ~/.hermes/skills/ 并当天投入使用的技能。

技能的存储位置与 Hermes 的发现机制

Hermes 将技能以普通文件夹的形式存放在 ~/.hermes/skills/ 目录下。内置技能在安装时会被复制到此处，你添加的任何自定义技能都会在下次重启后自动注册。目录结构是扁平的：

~/.hermes/skills/
├── backup-check/
│   └── SKILL.md
├── invoice-followup/
│   └── SKILL.md
└── stripe-mrr-digest/
    ├── SKILL.md
    └── helper.py

文件夹名即技能 ID。Hermes 在启动时会自动发现每个文件夹并读取其中的 SKILL.md。YAML 前置元数据中的 description 字段是智能体在运行时用来匹配你消息的依据，因此要面向智能体而非人类读者来撰写。如果描述未能清晰描述触发条件，技能就不会在你预期的时机被激活。

技能文件夹中可以包含额外文件，如 Python 辅助脚本、SQL 模板或清单文本文件。Hermes 不会自动执行它们，它们是供智能体在执行流程时读取或调用的资源。

三个技能文件夹位于 ~/.hermes/skills/ 目录下的示意图，每个文件夹包含一个 SKILL.md 文件，箭头指向正在运行的 Hermes Agent 进程

SKILL.md 文件格式

每个技能只有一个 Markdown 文件。顶部的 YAML 头部是元数据块，Markdown 正文是指令集。以下是一个可直接复用的最简骨架：

---
name: backup-check
description: Verify nightly backup archives exist, are non-empty, and pass a quick checksum spot-check on the latest file.
version: 0.1.0
author: [email protected]
required_environment_variables: []
required_credential_files: []
---

第一天需要关注的字段：

name — 与文件夹名保持一致，使用短横线命名法，不含空格。
description — 一句话描述，Hermes 据此判断何时加载该技能。请明确说明触发条件（"当用户询问 X 时"、"在执行 Y 之前"）。
version — 格式自由，但建议遵循语义化版本规范，以便在迭代时递增。
required_environment_variables — 技能运行前必须设置的密钥名称数组。首次激活时，智能体会提示你输入每个值并将其写入 .env。
required_credential_files — 需要挂载到沙箱中的 OAuth 令牌或服务账号 JSON 文件路径。

值得了解的可选字段：platforms（当技能仅适用于部分系统时，传入 macos、linux、windows 的数组）；requires_toolsets 用于仅在加载特定工具集时显示该技能；fallback_for_toolsets 则相反。技能级配置位于 metadata.hermes.config，非密钥偏好（如路径或域名设置）最终会写入 config.yaml 的 skills.config 下。

智能体实际读取的五个章节

前置元数据之后，Markdown 正文是散文内容。Hermes 不强制要求特定章节，但一种五部分结构已从 Nous Research 官方的"使用技能"指南以及 dev.to 和 glukhov.org 的创作文章中自然涌现出来。智能体偏好这一结构，因为每个部分回答的是不同的运行时问题。

使用场景

一段简短的段落，用于区分本技能与智能体可能选择的其他技能。如果你同时有 invoice-followup 和 client-update 两个技能，"使用场景"正是防止智能体激活错误技能的关键。

快速参考

以要点列出流程所依赖的命令、路径或常量。智能体在执行流程之前会先读取这一部分以加载上下文。请在此列出文件路径、S3 存储桶名称、环境变量名称、目标 Telegram 聊天 ID 等信息。

执行流程

智能体应遵循的编号步骤。以祈使句形式编写（"运行 X"、"如果响应包含 Y，执行 Z"）。智能体将此章节视为操作手册，并在执行过程中逐步引用或转述各步骤。

注意事项

你已知的陷阱：速率限制、静默失败、时区错误，以及某个数据结构异常的客户。智能体将这些内容视为防护栏，当检测到相应条件时会拒绝操作或发出警告。

验证

智能体如何确认操作正确完成：一条 grep、一次 curl、一个校验和，或"显示最后一行"。验证步骤是让技能可以无人值守运行的关键。

注入密钥与凭证

如果你的技能需要调用 API，请在 required_environment_variables 中声明密钥：

required_environment_variables:
  - STRIPE_RESTRICTED_KEY
  - SLACK_WEBHOOK_URL

技能首次激活时，智能体会逐一提示你输入每个值，并将其写入项目的 .env 文件。这些密钥随后会自动传入沙箱（Docker、Modal、临时运行器）。切勿将密钥硬编码在正文中，智能体在执行时会将其回显，从而将密钥暴露在日志中。

对于 OAuth 令牌或服务账号 JSON 文件，请使用 required_credential_files：

required_credential_files:
  - ~/.config/gcloud/application_default_credentials.json

这些文件会以只读卷的形式挂载到沙箱中。智能体不会解析它们，只会在流程运行前确认它们的存在。

Hermes 如何从对话中自动提取技能

你也可以让 Hermes 替你编写技能。在一次涉及五个或更多工具调用的复杂任务完成后，skill_manage 工具会捕获成功的执行模式，并将一个可复用的技能写入 ~/.hermes/skills/。智能体会分析对话内容，提取可复用的工作流，并生成一个 SKILL.md，其执行流程与它实际执行的步骤一一对应。

正是这一机制让 Hermes 用起来越来越顺手。持久化记忆层记住了你聊过的内容；自动提取的技能则记住了它解决问题的方式。关于这两个层次，我们在 Hermes Agent 记忆与技能一文中有更深入的介绍。

最初自动提取的技能通常有八成符合预期，两成有所偏差。打开 SKILL.md，收紧描述，删除那些智能体只是"顺带"执行的步骤，然后递增版本号。你就得到了一个经过手工打磨、触发可靠的技能。

端到端测试技能

SKILL.md 就位后，重启 Hermes（如果你的版本支持，也可运行 hermes skill reload）。然后执行三项检查：

让 Hermes 列出其所有技能。新技能应以你编写的名称和描述出现。
发送一条符合触发条件的消息。智能体在执行任何操作之前，应先宣告它正在使用该技能。
手动执行验证步骤。如果你的技能会写入文件，检查该文件；如果会向 Webhook 发送数据，检查 Webhook。

如果技能未能加载，通常是 YAML 的问题。一个多余的制表符或一个未加引号的冒号，都会静默地破坏前置元数据解析器。Hermes 在启动时会记录解析错误；首次重载后请检查智能体的标准错误输出。

一位开发者的终端场景，显示一个 Hermes Agent 会话正在加载自定义技能，绿色提示符，背景灯光昏暗

用托管服务跳过繁琐的搭建工作

自定义技能只是一个 Markdown 文件，但运行 Hermes 本身则截然不同。你需要一台主机、一个模型服务商 API 密钥、一个 Telegram 机器人或 Web UI、一套技能目录的备份方案，以及一种在不影响线上智能体的情况下测试变更的方法。

Hermify 是 Hermes Agent 的托管服务，帮你搞定上述一切。你的技能目录在重启后持久保留，模型密钥以加密静态存储，你还可以将这里编写的自定义技能与 Hermes 已原生支持的 MCP 集成结合使用。立即开始使用 Hermify，你的第一个自定义技能最快五分钟内即可在真实智能体上运行。