【Python大语言模型系列】在 Hermes Agent 中创建自定义 Custom Skills：从 skill.yaml 到 SKILL.md 的配置骨架与验证（案例分析）

1. 为什么要在 Hermes Agent 里折腾 Custom SkillsHermes Agent 是一个开源的 AI 助手框架它最吸引我的地方不是聊天而是「技能积累」——你教会它一次它就能把这件事沉淀成一个可复用的 Skill下次直接调用。Custom Skills 说白了就是给 Agent 写一份「操作手册」用skill.yaml或SKILL.md描述这个技能叫什么、什么时候触发、需要哪些工具、执行步骤是什么Agent 在 Function Calling 调度时就会按这份手册去干活。它适合谁适合已经用过 Hermes 基础对话、想让 Agent 接管重复性任务的人。比如每天要查一次服务状态、要按固定格式整理日志、要跑一段数据清洗脚本这些都能封装成 Skill。相比直接改源码写 ToolSkill 的优势是无需动核心代码、可以热加载、还能分享给社区。但落地时有两个高频卡点一是skill.yaml和SKILL.md到底谁说了算、字段怎么写二是模型调用通道怎么统一不然每个 Skill 里塞一个 Key维护起来很痛苦。这篇就围绕这两点给出可复制的目录骨架、配置骨架以及用 TaoToken 统一 Key/API 通道后的完整验证流程。你跟着做能跑通一次可复现的 Skill 调用。2. 前置准备目录结构与 TaoToken 通道2.1 先分清代码目录和数据目录Hermes 安装后有两套目录很多人第一次会搞混。代码目录是 Python 源码随版本更新替换数据目录是运行时数据配置、记忆、会话、技能都在这里持久保留。自定义 Skill 必须放在数据目录的skills/下也就是~/.hermes/skills/这是用户空间安全且不会被升级覆盖。# 查看你的数据目录 ls -la ~/.hermes/ # 典型结构 # ~/.hermes/ # ├── config.yaml # 主配置模型、终端、压缩、安全 # ├── .env # API Key 与密钥禁止提交 git # ├── SOUL.md # Agent 人格定义 # ├── MEMORY.md # 自动维护的事实记忆 # ├── skills/ # 自定义 Skill 放这里 # └── logs/ # 日志黄金规则记一下API Key 放~/.hermes/.env行为配置放~/.hermes/config.yaml人格风格放SOUL.md。配置优先级是 CLI 参数 config.yaml.env 内置默认值。2.2 用 TaoToken 统一 Key 与 API 通道Skill 里如果直接写死某个厂商的 Key换模型时就得逐个改。更省事的做法是把模型调用统一走 TaoToken 的 API 通道Key 只配一次Skill 里只引用环境变量。TaoToken 官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。先去控制台创建一个 Key然后写进~/.hermes/.env# ~/.hermes/.env TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api接着在~/.hermes/config.yaml里把模型提供商指向这个通道。不同版本字段名略有差异核心是base_url和api_key_env两项# ~/.hermes/config.yaml model: provider: openai-compatible base_url: https://taotoken.net/api api_key_env: TAOTOKEN_API_KEY name: claude-sonnet-4-20250514这样 Skill 内部调用模型时读的是同一个环境变量换模型只改name一行。如果你还没建 Key去 https://taotoken.net/api-keys 生成接入细节可以对照 https://taotoken.net/doc 的说明。3. 可复制配置skill.yaml 与 SKILL.md 骨架3.1 创建技能目录一个标准 Skill 遵循 agentskills.io 开放标准目录结构如下mkdir -p ~/.hermes/skills/weather-query/{scripts,references,assets} cd ~/.hermes/skills/weather-queryweather-query/ ├── skill.yaml # 元数据与触发条件 ├── SKILL.md # 技能说明与操作步骤 ├── scripts/ # 实现代码 ├── references/ # 参考文档 └── assets/ # 资源文件3.2 skill.yaml元数据与触发条件skill.yaml负责「这个技能是什么、什么时候用」。字段不用全填但name、description、metadata.hermes.tags建议写全否则技能搜索时命中率很低。# ~/.hermes/skills/weather-query/skill.yaml name: weather-query description: 查询指定城市的实时天气返回温度、湿度和天气状况 version: 1.0.0 author: your-name license: MIT platforms: [macos, linux] metadata: hermes: tags: [Weather, Query, API] related_skills: [] requires_toolsets: [web] requires_tools: [web_search] config: - key: weather.default_city description: 未指定城市时使用的默认城市 default: 北京 prompt: 请输入默认城市 required_environment_variables: - name: TAOTOKEN_API_KEY prompt: 请输入 TaoToken API Key help: 在 https://taotoken.net/api-keys 获取 required_for: 模型调用几个容易踩的点requires_toolsets和requires_tools是「仅当这些工具激活时才显示该技能」写错了技能会隐身fallback_for_toolsets则是「当这些工具激活时隐藏」用于做降级方案。required_environment_variables会在首次加载时提示你填 Key正好把 TaoToken 的 Key 接进来。3.3 SKILL.md给 Agent 看的操作手册SKILL.md分两部分YAML Frontmatter 放元数据Markdown 正文放步骤说明。Frontmatter 和skill.yaml有重叠时以SKILL.md为准新版 Hermes 推荐单文件写法。--- name: weather-query description: 查询指定城市的实时天气 version: 1.0.0 metadata: hermes: tags: [Weather, Query] requires_toolsets: [web] --- # 天气查询技能 根据城市名查询实时天气返回温度、湿度、天气状况。 ## 何时使用 当用户询问「某城市天气」「今天冷不冷」「要不要带伞」时加载本技能。 ## 快速参考 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | city | string | 否 | 城市名默认取 config 中的 default_city | ## 操作步骤 1. 从用户输入提取城市名未提供则读取 weather.default_city。 2. 调用 scripts/main.py 中的 query_weather(city)。 3. 将返回的 JSON 格式化为自然语言回复。 ## 常见陷阱 - 城市名含空格时需 URL 编码否则请求 400。 - 接口超时默认 5 秒慢网络下建议重试一次。 ## 验证方式 返回结果包含 temperature、humidity、condition 三个字段即为成功。3.4 scripts/main.py功能实现# ~/.hermes/skills/weather-query/scripts/main.py import os import json import urllib.parse import urllib.request def query_weather(city: str) - dict: 查询城市天气模型调用通道走 TaoToken 统一配置。 base os.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api) key os.environ.get(TAOTOKEN_API_KEY) if not key: raise RuntimeError(TAOTOKEN_API_KEY 未配置请检查 ~/.hermes/.env) # 这里以调用模型做天气意图解析为例实际天气数据可换任意数据源 payload { model: claude-sonnet-4-20250514, messages: [ {role: user, content: f用 JSON 返回{city}的天气字段 temperature/humidity/condition} ], } req urllib.request.Request( f{base}/v1/chat/completions, datajson.dumps(payload).encode(), headers{ Authorization: fBearer {key}, Content-Type: application/json, }, ) with urllib.request.urlopen(req, timeout10) as resp: return json.loads(resp.read().decode())注意base和key都从环境变量读Skill 本身不持有任何密钥这样多个 Skill 共用一套通道换 Key 只改.env一处。4. 验证请求从 skills list 到一次真实调用4.1 注册与列表检查技能放进目录后不需要手动注册Hermes 启动时会扫描~/.hermes/skills/。先确认它被识别hermes skills list如果列表里没有weather-query八成是skill.yaml的 YAML 缩进错了或者name字段缺失。可以用hermes doctor做一次健康检查它会提示技能目录的扫描结果。4.2 搜索与查看技能# 搜索技能 hermes skills search weather # 查看技能详情确认 frontmatter 解析正确 hermes skills list --verbose4.3 发起一次可复现的调用启动交互式会话直接问一个会触发该技能的问题hermes chat -q 帮我查一下上海的天气预期结果是 Agent 加载weather-query读取TAOTOKEN_API_KEY通过https://taotoken.net/api发起请求最后返回包含温度、湿度、天气状况的自然语言回复。如果返回的是「未找到相关技能」说明触发条件没匹配上回去检查SKILL.md的「何时使用」描述是否覆盖了你的问法。想单独验证模型通道是否通可以先用模型对话页面测一下 Key 是否有效https://taotoken.net/model-chat 。通道没问题再回来调 Skill能省不少排查时间。5. 本篇常见错排查报错一TAOTOKEN_API_KEY 未配置。说明.env没被加载。Hermes 读取的是~/.hermes/.env不是项目根目录的.env。确认文件存在且没有多余空格然后重启hermes。报错二技能列表为空。最常见是 YAML 缩进用了 Tab。skill.yaml必须用空格缩进metadata.hermes下的字段要严格对齐。另一个原因是目录层级错了技能必须直接位于~/.hermes/skills/skill-name/不能多套一层。报错三请求返回 401。Key 无效或过期。去 https://taotoken.net/api-keys 重新生成更新.env后重启。注意Authorization头是Bearer key别漏了Bearer。报错四请求返回 404。base_url写成了带路径的形式。正确写法是https://taotoken.net/api代码里再拼/v1/chat/completions。如果直接把完整路径写进base_url就会重复拼接。报错五技能被识别但不触发。检查requires_toolsets是否写了当前未激活的 toolset。比如写了requires_toolsets: [web]但你没启用 web 工具集技能就会隐身。临时排查可以先把这行注释掉。报错六外部目录技能不生效。如果你在config.yaml里配了external_dirs注意外部目录是只读的Agent 创建或编辑技能时始终写入~/.hermes/skills/。同名技能本地优先外部版本会被覆盖。路径支持~展开和${VAR}替换不存在的路径会被静默跳过。6. 把通道固定下来再谈技能积累Skill 写多了你会发现真正难维护的不是步骤描述而是每个技能背后的模型调用。把 Key 和 base_url 统一收敛到.env加config.yamlSkill 里只读环境变量后面加十个技能也不用重复配通道。TaoToken 在这里扮演的就是那个统一入口一个 Key 覆盖多个模型换模型只改一行配置。如果你打算长期跑编码类或 Agent 类任务可以看看 Coding Plan 的额度方案https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 控制台在 https://taotoken.net/console 。先把weather-query这个最小骨架跑通再照着同样的结构复制出你自己的技能比一上来就写复杂逻辑稳得多。