1. 为什么你的 Hermes Agent 总是“答非所问”很多人第一次用 Hermes Agent 时都会遇到一个很典型的场景你让它帮你画一张 Excalidraw 架构图它却回你一句“我不太了解 Excalidraw 的格式”你让它按 TDD 方式写一个字符串反转函数它上来就把实现代码全写完测试一个没写。问题不在模型本身而在于它没有加载对应的技能Skill。Hermes Agent 的技能系统本质上就是给 Agent 装上一本“可插拔的专业手册”。这本手册不是一次性全部塞进上下文而是通过SKILL.md文件定义触发条件、知识内容和执行流程再配合**渐进式披露Progressive Disclosure**机制按需加载不同层级的信息。这样既不会浪费 Token又能让 Agent 在需要时瞬间变成某个领域的“专家”。这篇文章面向的是刚接触 Hermes Agent 技能系统的开发者、运维工程师和技术爱好者。我会从零开始带你搭建第一个自定义技能的 SKILL.md 骨架配置好config.toml和settings.json并用hermes skills系列命令验证技能注册与调用链路。同时我会把模型调用的 Key 统一收敛到 TaoToken 上避免你在多个平台之间来回切换 Key 的麻烦。整套流程在本地就能跑通不需要复杂的云端环境。2. TaoToken 前置把 Key 统一收口在跑通技能系统之前先把模型调用的入口统一。Hermes Agent 支持通过 OpenAI 兼容协议接入外部模型服务TaoToken 提供的 API 正好符合这个要求。你只需要一个 Key就能在 Hermes 里调用多种模型不用为每个模型单独维护一套凭证。2.1 获取 API Key打开 TaoToken 官网注册并登录后进入控制台在 API Keys 页面创建一个新的 Key。建议给这个 Key 起一个能识别用途的名字比如hermes-agent-local方便后续排查问题时定位。创建完成后把 Key 复制出来格式通常是一串以sk-开头的字符串。这个 Key 只会完整显示一次建议先存到本地密码管理器里。2.2 确认接入地址TaoToken 的 API 基础地址是https://taotoken.net/api注意这里不要加任何多余的路径后缀Hermes 的 OpenAI 兼容层会自动拼接/v1/chat/completions这类端点。如果你在配置里写成了带/v1的地址反而容易出现 404。2.3 环境变量方式注入为了避免把 Key 硬编码进配置文件推荐用环境变量的方式注入。在~/.bashrc或~/.zshrc里加一行export TAOTOKEN_API_KEYsk-你的实际Key然后执行source ~/.bashrc让变量生效。后面在config.toml里就可以用${TAOTOKEN_API_KEY}这种占位符来引用既安全又方便切换。3. 可复制配置config.toml 与 settings.jsonHermes Agent 的配置分两层config.toml负责模型接入和全局行为settings.json负责技能系统的加载策略。两者配合才能让 SKILL.md 的渐进式披露真正生效。3.1 config.toml 模型接入片段在 Hermes 的配置目录下通常是~/.hermes/config.toml加入下面这段[model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model_name claude-sonnet-4-20250514 max_tokens 8192 temperature 0.3 [model.fallback] enabled true model_name gpt-4o-mini这里有几个参数值得说明。base_url指向 TaoToken 的 API 地址api_key用环境变量占位符引用避免明文泄露。model_name可以换成你实际想用的模型标识TaoToken 控制台的模型列表里能看到当前可用的名称。temperature设成 0.3 是因为技能调用场景更偏向确定性输出太高的随机性会让 Agent 不按 SKILL.md 里的流程走。3.2 settings.json 技能加载策略settings.json通常位于~/.hermes/settings.json重点配置技能目录和渐进式披露的层级阈值{ skills: { enabled: true, root_dir: ~/.hermes/skills, progressive_disclosure: { enabled: true, description_max_chars: 80, body_max_chars: 4000, reference_load_threshold: 0.75 }, auto_reload: true }, context: { max_skill_tokens: 6000 } }description_max_chars控制第一层技能描述的字符上限默认 80 字左右Agent 靠这段描述判断“要不要用这个技能”。body_max_chars是第二层 SKILL.md 主体的加载上限超过这个长度会被截断所以写 SKILL.md 时要精炼。reference_load_threshold表示当主体内容被使用到 75% 时才触发第三层references/目录的加载。3.3 目录结构约定技能目录的命名和层级直接影响hermes skills命令的识别结果。推荐按下面这种结构组织~/.hermes/skills/ └── software-development/ └── my-first-skill/ ├── SKILL.md ├── references/ │ └── api-spec.md ├── templates/ │ └── example.py └── scripts/ └── validate.shsoftware-development是分类目录my-first-skill是技能名。SKILL.md 必须放在技能根目录下文件名大小写敏感写成skill.md会导致注册失败。4. 从零写一个 SKILL.md 骨架SKILL.md 是整个技能系统的核心。它用 YAML front matter 定义元信息用 Markdown 正文承载知识内容。下面是一个可以直接复制的最小骨架--- name: my-first-skill description: 演示技能系统的最小可用示例包含触发条件和执行步骤 triggers: - 演示技能 - my first skill version: 1.0.0 author: your-name --- # My First Skill ## 适用场景 当用户提到“演示技能”或“my first skill”时加载本技能。 ## 执行步骤 1. 确认用户的具体需求复述一遍需求确保理解正确。 2. 按照 references/api-spec.md 中的规范生成输出。 3. 输出完成后附上一句简短的验证建议。 ## 注意事项 - 不要跳过需求复述步骤。 - 如果用户需求超出本技能范围明确告知并建议其他技能。front matter 里的triggers是渐进式披露第一层的匹配依据。Agent 在每轮对话开始时会扫描所有已安装技能的description和triggers只有匹配上的技能才会进入第二层加载。所以description要写得精准别用“万能助手”这种模糊描述。4.1 渐进式披露的三层加载顺序理解加载顺序才能写出高效的 SKILL.md。整个机制分三层第一层是技能描述始终驻留在上下文里大约 50 到 80 字。Agent 靠这一层判断“当前问题是否和某个技能相关”。这一层的内容来自 front matter 的description和triggers。第二层是SKILL.md 主体匹配成功后才加载大约 2000 到 4000 字。这一层包含核心方法论、执行步骤和关键约束。写的时候要把最重要的流程放在前面因为超过body_max_chars的部分会被截断。第三层是references/ 目录下的文件只有在主体内容被使用到一定比例后才按需加载。这一层适合放详细的 API 文档、配置参考、长表格这类“查得到但不用背”的内容。这种设计就像人类专家的工作方式你知道有哪些领域的手册第一层遇到问题时翻开对应手册的目录和核心章节第二层需要查具体参数时才翻到附录第三层。而不是把整本手册背下来。4.2 用 hermes skills 验证注册写完 SKILL.md 后先确认技能被正确识别hermes skills list如果输出里能看到my-first-skill说明注册成功。如果没看到检查三个地方SKILL.md 是否在技能根目录、front matter 的 YAML 格式是否正确、settings.json里的root_dir是否指向了正确的路径。接着用搜索命令验证触发词匹配hermes skills search 演示技能正常情况下会返回my-first-skill以及它的 description。如果返回空说明triggers里的词和搜索词没有对上检查一下是否有拼写差异或大小写问题。5. 验证请求跑通第一个技能调用配置和骨架都就绪后用实际对话验证整条链路。启动 Hermes 时预加载技能hermes -s my-first-skill启动后输入 帮我演示技能生成一个简单的配置示例如果一切正常Hermes 会先复述你的需求然后按照 SKILL.md 里的步骤生成输出最后附上验证建议。这个过程说明第一层描述匹配成功、第二层主体加载成功。5.1 验证第三层按需加载要验证references/的按需加载可以在 SKILL.md 主体里加一句“详细规范见 references/api-spec.md”然后在references/api-spec.md里写一段独特的内容比如一个特定的参数名custom_field_xyz。再次对话时如果 Agent 的输出里出现了custom_field_xyz说明第三层被正确加载了。也可以用hermes skills inspect命令预览技能内容hermes skills inspect my-first-skill这个命令会显示技能的三层结构概览包括描述、主体字数和 references 文件列表方便你确认加载策略是否符合预期。5.2 会话中动态加载如果不想重启 Hermes可以在对话中直接加载技能 /skill my-first-skill加载成功后会返回一行确认信息。之后当前会话就拥有了该技能的知识。这种方式适合在调试 SKILL.md 时快速迭代改完文件后用/reload-skills重新扫描即可。6. 本篇常见错排查技能系统入门阶段最容易踩的坑集中在配置路径、YAML 格式和加载顺序上。下面这几个是我实际遇到过的典型问题。6.1 技能列表为空执行hermes skills list没有任何输出最常见的原因是settings.json里的root_dir用了相对路径。Hermes 不会自动把相对路径解析到配置目录必须写成绝对路径或者用~开头的家目录路径。另一个原因是技能目录层级不对比如把 SKILL.md 直接放在了~/.hermes/skills/下而没有分类目录某些版本会跳过这种结构。6.2 YAML front matter 解析失败如果hermes skills list报错说“invalid front matter”检查 front matter 是否用---包裹冒号后面是否有空格以及triggers列表的缩进是否一致。YAML 对缩进极其敏感用 Tab 代替空格是最常见的错误。建议统一用两个空格缩进。6.3 技能加载了但 Agent 不按流程走这种情况通常是第二层主体被截断了。body_max_chars默认 4000如果你的 SKILL.md 正文超过这个长度后面的步骤会被丢弃。解决办法是把详细内容移到references/目录主体只保留核心流程。另外temperature设得太高也会让 Agent 忽略流程约束建议保持在 0.3 以下。6.4 模型调用返回 401如果 Hermes 启动时报 401 错误先确认TAOTOKEN_API_KEY环境变量是否在当前 shell 会话里生效。用echo $TAOTOKEN_API_KEY检查一下。如果变量存在但仍然是 401检查config.toml里的base_url是否写成了https://taotoken.net/api/v1多出来的/v1会导致鉴权路径不匹配。正确的写法就是https://taotoken.net/api。6.5 修改 SKILL.md 后不生效Hermes 默认会缓存已加载的技能。改完文件后要么用/reload-skills命令重新扫描要么重启 Hermes。如果settings.json里auto_reload设成了false那就只能手动重载。建议开发阶段把auto_reload打开省去反复重启的麻烦。整套流程跑通后你就拥有了一个可扩展的技能系统底座。后续要加新技能只需要在~/.hermes/skills/下新建目录、写 SKILL.md、用hermes skills list确认注册即可。模型调用这边Key 统一走 TaoToken 的 API Keys 管理接入文档里有完整的参数说明和错误码对照表遇到鉴权或模型名问题时可以直接查。如果你更习惯在图形界面里验证模型输出模型对话页面可以快速对比不同模型对同一段 SKILL.md 的理解差异。长期做编码类技能开发的话Coding Plan 能把多个技能的调用额度统一管理省去逐个配置的重复劳动。
1. 为什么你的 Hermes Agent 总是“答非所问”很多人第一次用 Hermes Agent 时都会遇到一个很典型的场景你让它帮你画一张 Excalidraw 架构图它却回你一句“我不太了解 Excalidraw 的格式”你让它按 TDD 方式写一个字符串反转函数它上来就把实现代码全写完测试一个没写。问题不在模型本身而在于它没有加载对应的技能Skill。Hermes Agent 的技能系统本质上就是给 Agent 装上一本“可插拔的专业手册”。这本手册不是一次性全部塞进上下文而是通过SKILL.md文件定义触发条件、知识内容和执行流程再配合**渐进式披露Progressive Disclosure**机制按需加载不同层级的信息。这样既不会浪费 Token又能让 Agent 在需要时瞬间变成某个领域的“专家”。这篇文章面向的是刚接触 Hermes Agent 技能系统的开发者、运维工程师和技术爱好者。我会从零开始带你搭建第一个自定义技能的 SKILL.md 骨架配置好config.toml和settings.json并用hermes skills系列命令验证技能注册与调用链路。同时我会把模型调用的 Key 统一收敛到 TaoToken 上避免你在多个平台之间来回切换 Key 的麻烦。整套流程在本地就能跑通不需要复杂的云端环境。2. TaoToken 前置把 Key 统一收口在跑通技能系统之前先把模型调用的入口统一。Hermes Agent 支持通过 OpenAI 兼容协议接入外部模型服务TaoToken 提供的 API 正好符合这个要求。你只需要一个 Key就能在 Hermes 里调用多种模型不用为每个模型单独维护一套凭证。2.1 获取 API Key打开 TaoToken 官网注册并登录后进入控制台在 API Keys 页面创建一个新的 Key。建议给这个 Key 起一个能识别用途的名字比如hermes-agent-local方便后续排查问题时定位。创建完成后把 Key 复制出来格式通常是一串以sk-开头的字符串。这个 Key 只会完整显示一次建议先存到本地密码管理器里。2.2 确认接入地址TaoToken 的 API 基础地址是https://taotoken.net/api注意这里不要加任何多余的路径后缀Hermes 的 OpenAI 兼容层会自动拼接/v1/chat/completions这类端点。如果你在配置里写成了带/v1的地址反而容易出现 404。2.3 环境变量方式注入为了避免把 Key 硬编码进配置文件推荐用环境变量的方式注入。在~/.bashrc或~/.zshrc里加一行export TAOTOKEN_API_KEYsk-你的实际Key然后执行source ~/.bashrc让变量生效。后面在config.toml里就可以用${TAOTOKEN_API_KEY}这种占位符来引用既安全又方便切换。3. 可复制配置config.toml 与 settings.jsonHermes Agent 的配置分两层config.toml负责模型接入和全局行为settings.json负责技能系统的加载策略。两者配合才能让 SKILL.md 的渐进式披露真正生效。3.1 config.toml 模型接入片段在 Hermes 的配置目录下通常是~/.hermes/config.toml加入下面这段[model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model_name claude-sonnet-4-20250514 max_tokens 8192 temperature 0.3 [model.fallback] enabled true model_name gpt-4o-mini这里有几个参数值得说明。base_url指向 TaoToken 的 API 地址api_key用环境变量占位符引用避免明文泄露。model_name可以换成你实际想用的模型标识TaoToken 控制台的模型列表里能看到当前可用的名称。temperature设成 0.3 是因为技能调用场景更偏向确定性输出太高的随机性会让 Agent 不按 SKILL.md 里的流程走。3.2 settings.json 技能加载策略settings.json通常位于~/.hermes/settings.json重点配置技能目录和渐进式披露的层级阈值{ skills: { enabled: true, root_dir: ~/.hermes/skills, progressive_disclosure: { enabled: true, description_max_chars: 80, body_max_chars: 4000, reference_load_threshold: 0.75 }, auto_reload: true }, context: { max_skill_tokens: 6000 } }description_max_chars控制第一层技能描述的字符上限默认 80 字左右Agent 靠这段描述判断“要不要用这个技能”。body_max_chars是第二层 SKILL.md 主体的加载上限超过这个长度会被截断所以写 SKILL.md 时要精炼。reference_load_threshold表示当主体内容被使用到 75% 时才触发第三层references/目录的加载。3.3 目录结构约定技能目录的命名和层级直接影响hermes skills命令的识别结果。推荐按下面这种结构组织~/.hermes/skills/ └── software-development/ └── my-first-skill/ ├── SKILL.md ├── references/ │ └── api-spec.md ├── templates/ │ └── example.py └── scripts/ └── validate.shsoftware-development是分类目录my-first-skill是技能名。SKILL.md 必须放在技能根目录下文件名大小写敏感写成skill.md会导致注册失败。4. 从零写一个 SKILL.md 骨架SKILL.md 是整个技能系统的核心。它用 YAML front matter 定义元信息用 Markdown 正文承载知识内容。下面是一个可以直接复制的最小骨架--- name: my-first-skill description: 演示技能系统的最小可用示例包含触发条件和执行步骤 triggers: - 演示技能 - my first skill version: 1.0.0 author: your-name --- # My First Skill ## 适用场景 当用户提到“演示技能”或“my first skill”时加载本技能。 ## 执行步骤 1. 确认用户的具体需求复述一遍需求确保理解正确。 2. 按照 references/api-spec.md 中的规范生成输出。 3. 输出完成后附上一句简短的验证建议。 ## 注意事项 - 不要跳过需求复述步骤。 - 如果用户需求超出本技能范围明确告知并建议其他技能。front matter 里的triggers是渐进式披露第一层的匹配依据。Agent 在每轮对话开始时会扫描所有已安装技能的description和triggers只有匹配上的技能才会进入第二层加载。所以description要写得精准别用“万能助手”这种模糊描述。4.1 渐进式披露的三层加载顺序理解加载顺序才能写出高效的 SKILL.md。整个机制分三层第一层是技能描述始终驻留在上下文里大约 50 到 80 字。Agent 靠这一层判断“当前问题是否和某个技能相关”。这一层的内容来自 front matter 的description和triggers。第二层是SKILL.md 主体匹配成功后才加载大约 2000 到 4000 字。这一层包含核心方法论、执行步骤和关键约束。写的时候要把最重要的流程放在前面因为超过body_max_chars的部分会被截断。第三层是references/ 目录下的文件只有在主体内容被使用到一定比例后才按需加载。这一层适合放详细的 API 文档、配置参考、长表格这类“查得到但不用背”的内容。这种设计就像人类专家的工作方式你知道有哪些领域的手册第一层遇到问题时翻开对应手册的目录和核心章节第二层需要查具体参数时才翻到附录第三层。而不是把整本手册背下来。4.2 用 hermes skills 验证注册写完 SKILL.md 后先确认技能被正确识别hermes skills list如果输出里能看到my-first-skill说明注册成功。如果没看到检查三个地方SKILL.md 是否在技能根目录、front matter 的 YAML 格式是否正确、settings.json里的root_dir是否指向了正确的路径。接着用搜索命令验证触发词匹配hermes skills search 演示技能正常情况下会返回my-first-skill以及它的 description。如果返回空说明triggers里的词和搜索词没有对上检查一下是否有拼写差异或大小写问题。5. 验证请求跑通第一个技能调用配置和骨架都就绪后用实际对话验证整条链路。启动 Hermes 时预加载技能hermes -s my-first-skill启动后输入 帮我演示技能生成一个简单的配置示例如果一切正常Hermes 会先复述你的需求然后按照 SKILL.md 里的步骤生成输出最后附上验证建议。这个过程说明第一层描述匹配成功、第二层主体加载成功。5.1 验证第三层按需加载要验证references/的按需加载可以在 SKILL.md 主体里加一句“详细规范见 references/api-spec.md”然后在references/api-spec.md里写一段独特的内容比如一个特定的参数名custom_field_xyz。再次对话时如果 Agent 的输出里出现了custom_field_xyz说明第三层被正确加载了。也可以用hermes skills inspect命令预览技能内容hermes skills inspect my-first-skill这个命令会显示技能的三层结构概览包括描述、主体字数和 references 文件列表方便你确认加载策略是否符合预期。5.2 会话中动态加载如果不想重启 Hermes可以在对话中直接加载技能 /skill my-first-skill加载成功后会返回一行确认信息。之后当前会话就拥有了该技能的知识。这种方式适合在调试 SKILL.md 时快速迭代改完文件后用/reload-skills重新扫描即可。6. 本篇常见错排查技能系统入门阶段最容易踩的坑集中在配置路径、YAML 格式和加载顺序上。下面这几个是我实际遇到过的典型问题。6.1 技能列表为空执行hermes skills list没有任何输出最常见的原因是settings.json里的root_dir用了相对路径。Hermes 不会自动把相对路径解析到配置目录必须写成绝对路径或者用~开头的家目录路径。另一个原因是技能目录层级不对比如把 SKILL.md 直接放在了~/.hermes/skills/下而没有分类目录某些版本会跳过这种结构。6.2 YAML front matter 解析失败如果hermes skills list报错说“invalid front matter”检查 front matter 是否用---包裹冒号后面是否有空格以及triggers列表的缩进是否一致。YAML 对缩进极其敏感用 Tab 代替空格是最常见的错误。建议统一用两个空格缩进。6.3 技能加载了但 Agent 不按流程走这种情况通常是第二层主体被截断了。body_max_chars默认 4000如果你的 SKILL.md 正文超过这个长度后面的步骤会被丢弃。解决办法是把详细内容移到references/目录主体只保留核心流程。另外temperature设得太高也会让 Agent 忽略流程约束建议保持在 0.3 以下。6.4 模型调用返回 401如果 Hermes 启动时报 401 错误先确认TAOTOKEN_API_KEY环境变量是否在当前 shell 会话里生效。用echo $TAOTOKEN_API_KEY检查一下。如果变量存在但仍然是 401检查config.toml里的base_url是否写成了https://taotoken.net/api/v1多出来的/v1会导致鉴权路径不匹配。正确的写法就是https://taotoken.net/api。6.5 修改 SKILL.md 后不生效Hermes 默认会缓存已加载的技能。改完文件后要么用/reload-skills命令重新扫描要么重启 Hermes。如果settings.json里auto_reload设成了false那就只能手动重载。建议开发阶段把auto_reload打开省去反复重启的麻烦。整套流程跑通后你就拥有了一个可扩展的技能系统底座。后续要加新技能只需要在~/.hermes/skills/下新建目录、写 SKILL.md、用hermes skills list确认注册即可。模型调用这边Key 统一走 TaoToken 的 API Keys 管理接入文档里有完整的参数说明和错误码对照表遇到鉴权或模型名问题时可以直接查。如果你更习惯在图形界面里验证模型输出模型对话页面可以快速对比不同模型对同一段 SKILL.md 的理解差异。长期做编码类技能开发的话Coding Plan 能把多个技能的调用额度统一管理省去逐个配置的重复劳动。
