1. Hermes 自定义技能到底解决什么问题Hermes 的 Agent 默认只会用内置工具遇到你团队内部的部署流程、日志规范、数据清洗套路它每次都要你从头讲一遍。自定义技能Skill就是把这个讲一遍变成一次性的资产写一份 SKILL.mdAgent 在合适的时机自动加载并调用不用你反复提示。SKILL.md 是什么简单说它是给 Agent 看的操作手册 触发说明书。文件头部的 frontmatter 定义技能名、描述、版本、标签正文写清楚这个技能在什么场景下用、具体步骤是什么、有哪些坑。Agent 读到 description 和 tags判断当前任务是否匹配匹配就加载正文执行。能做什么我试过把发布前端到测试环境这套流程写成技能Agent 收到帮我发个测试环境就直接走完构建、上传、通知三步不再问我用哪个命令。适合谁三类人最需要一是团队里有固定 SOP 的工程同学二是想让 Agent 记住自己偏好的个人开发者三是想把技能沉淀成团队共享资产、发布到 Skills Hub 的人。这篇按全链路走先写 SKILL.md再用 skill_manage 注册调试最后发布到 Skills Hub 让别的 Agent 复用。每一步都给可复制的命令和配置你跟着敲就能跑通。2. 前置准备TaoToken 接入与 Hermes 环境在写技能之前得先让 Hermes 能正常调用模型。技能本身不产生推理它只是给 Agent 提供上下文真正干活的是背后的模型。所以第一步是把模型接入配好。TaoToken 在这里的角色是模型接入层。它提供 OpenAI 兼容的 API 端点Hermes 通过标准的 Base URL API Key 就能连上不用改 Hermes 源码。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。接入需要三件套Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/api API Key 在控制台生成Model ID 按你选的模型填。这三样在 Hermes 的 config.yaml 里对应 provider、api_key、model 三个字段。先去控制台拿 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 生成后复制保存。然后配置 Hermes# 把 TaoToken 的 Key 存入 Hermes 的 .env自动管理避免明文写进 config hermes config set TAOTOKEN_API_KEY sk-你的key # 验证凭据是否被识别 hermes config check接着在 config.yaml 里配置 provider。TaoToken 是 OpenAI 兼容端点用 custom provider 类型model: provider: custom default: claude-sonnet-4-6 # 换成你在 TaoToken 控制台选的 Model ID base_url: https://taotoken.net/api key_env: TAOTOKEN_API_KEY这里 key_env 填的是环境变量名不是 Key 本身Hermes 运行时从环境读取。配完跑一条消息验证hermes 你好确认一下模型是否正常能正常回复就说明接入通了。如果报 401检查 Key 是否复制完整如果报连接失败检查 base_url 是否漏了 /api 后缀。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到问题可以对照。环境通了之后技能系统才有意义——Agent 有模型推理能力技能给它提供领域知识。3. 可复制配置SKILL.md 模板与 skill_manage 注册这一节是核心。先给一份能直接用的 SKILL.md 模板再讲怎么用 skill_manage 把它注册进 Hermes。3.1 SKILL.md 的 frontmatter 结构SKILL.md 分两部分frontmatterYAML 头和正文Markdown。frontmatter 定义元数据正文写操作步骤。模板如下--- name: deploy-runbook description: 团队前端项目发布到测试环境的完整流程包含构建、上传、通知三步 version: 1.0.0 author: My Org Platform Team metadata: hermes: tags: [deployment, runbook, internal, frontend] --- # 前端测试环境发布 ## 触发条件 当用户说发测试环境部署到 test发布前端时使用本技能。 ## 前置检查 1. 确认当前分支是 main 或 release/* 2. 确认 package.json 里的 version 已更新 3. 确认没有未提交的改动git status 干净 ## 执行步骤 1. 运行构建npm run build:test 2. 上传产物./scripts/upload.sh dist/ test 3. 通知群组./scripts/notify.sh 前端已发布到测试环境 ## 常见问题 - 构建失败先看 node 版本是否为 18 - 上传 403 检查 scripts/upload.sh 里的 token 是否过期frontmatter 里 name 是技能唯一标识description 是 Agent 判断是否加载的关键——写清楚什么场景用不要写成功能罗列。tags 帮助检索version 用于更新管理。3.2 用 skill_manage 注册技能skill_manage 是 Hermes 的技能管理工具Agent 自己也能调用它创建技能。手动注册用 create 动作# 在 Hermes 会话内或通过 CLI 调用 skill_manage skill_manage(actioncreate, namedeploy-runbook, contentSKILL.md 完整内容)实际使用时content 参数传的是整个 SKILL.md 文本。更推荐的做法是把 SKILL.md 写到文件再让 skill_manage 读取# 先创建技能目录 mkdir -p ~/.hermes/skills/deploy-runbook # 写入 SKILL.md cat ~/.hermes/skills/deploy-runbook/SKILL.md EOF --- name: deploy-runbook description: 团队前端项目发布到测试环境的完整流程 version: 1.0.0 metadata: hermes: tags: [deployment, frontend] --- # 前端测试环境发布 ...正文 EOF注册后验证# 列出所有已注册技能 hermes skills list # 查看某个技能的详情 hermes skills inspect deploy-runbook3.3 定点修复用 patch大改用 edit技能写完后经常要微调。skill_manage 提供两种修改方式# 定点修复只改一小段推荐 skill_manage(actionpatch, namedeploy-runbook, old_stringnpm run build:test, new_stringnpm run build:test -- --modestaging) # 大型重写整个 SKILL.md 替换 skill_manage(actionedit, namedeploy-runbook, content新的完整内容) # 删除技能 skill_manage(actiondelete, namedeploy-runbook) # 添加支持文件脚本、模板等 skill_manage(actionwrite_file, namedeploy-runbook, file_pathscripts/upload.sh, file_content#!/bin/bash\n...)patch 只传 old_string 和 new_string适合改命令、改参数edit 要传完整内容适合重构。日常优先用 patch改动小、出错概率低。3.4 写入审批门控如果担心 Agent 自动创建低质量技能开启审批skills: write_approval: true # true Agent 创建的技能需人工审批开启后Agent 通过 skill_manage 创建的技能会进入暂存区用这些命令处理/skills pending # 列出暂存写入 /skills diff id # 查看完整 unified diff /skills approve id # 应用 /skills reject id # 拒绝默认 write_approval 是 falseAgent 可以自由写入。团队协作建议开 true个人用可以关。4. 验证请求确认 Agent 真的会调用技能写完技能不等于 Agent 会用。这一节讲怎么验证技能被正确触发。4.1 本地验证流程启动 Hermes 会话用自然语言触发技能hermes 帮我把前端发到测试环境预期行为Agent 识别到发测试环境匹配 deploy-runbook 的触发条件加载技能正文按步骤执行。观察输出里是否有技能加载的日志以及是否走了你定义的构建、上传、通知三步。如果 Agent 没触发检查三件事description 是否写清楚了触发场景、tags 是否包含相关关键词、技能是否真的注册成功hermes skills list 能看到。4.2 用 skill_manage 查看调用记录# 查看技能被调用的历史 hermes skills log deploy-runbook # 查看技能当前状态 hermes skills status deploy-runbook4.3 强制加载测试想确认技能内容本身没问题可以强制加载# 在会话内直接引用技能 用 deploy-runbook 技能告诉我执行步骤Agent 会输出技能正文里的步骤说明内容被正确读取。这一步能区分技能没注册和技能注册了但没触发两种问题。4.4 验证成功的结果长什么样成功的验证有三个标志一是 Agent 输出里出现技能名或技能步骤二是执行过程符合 SKILL.md 定义三是没有报技能未找到或加载失败。如果三步都符合技能就生效了。5. 本篇常见错排查技能开发踩的坑集中在几类逐个对照。5.1 401 认证失败报错401 Unauthorized或invalid api key。原因通常是 TaoToken 的 Key 没配对或者 key_env 指向的环境变量名写错。检查# 确认环境变量存在 echo $TAOTOKEN_API_KEY # 确认 config.yaml 里 key_env 拼写一致 hermes config get model.key_env如果 Key 正确但仍 401检查 base_url 是否漏了 /api。TaoToken 的端点是 https://taotoken.net/api 不是根域名。5.2 local proxy failed报错local proxy failed或connection refused。这类错误一般是本地网络或端点配置问题。检查 base_url 是否可达curl -I https://taotoken.net/api如果 curl 也失败说明网络层有问题不是 Hermes 配置问题。如果 curl 成功但 Hermes 失败检查 config.yaml 里 base_url 是否有多余空格或换行。5.3 reading choices 报错报错error reading choices或unexpected response format。这通常是模型返回格式不符合预期。检查 Model ID 是否填对——TaoToken 控制台里选的模型名要和 config.yaml 的 default 字段完全一致。如果模型名带版本号别漏。5.4 OAuth 相关报错报错OAuth token expired或refresh failed。如果你用的是 OAuth 类 provider不是 API Keytoken 过期会报这个。TaoToken 走 API Key 模式正常不会遇到。如果混用了其他 provider检查对应凭据是否过期。5.5 技能注册了但不触发这是最常见的软错误。技能在 hermes skills list 里能看到但 Agent 就是不用。原因通常是 description 写得太泛比如处理部署相关任务Agent 判断不出具体场景。改成当用户说发测试环境、部署到 test 时使用触发率会明显提升。另一个原因是 tags 和用户措辞不匹配。用户说发布前端tags 里只有 deployment检索不到。把常见同义词都加进 tags。5.6 patch 报 old_string not found用 skill_manage patch 时old_string 必须和文件里的内容完全一致包括空格和换行。如果报找不到先 inspect 看当前内容hermes skills inspect deploy-runbook复制准确的内容再 patch。如果改动大直接用 edit 整体替换更省事。6. 发布到 Skills Hub 与后续维护技能在本地跑通后可以发布到 Skills Hub 让其他 Agent 复用。6.1 仓库布局Skills Hub 的技能按仓库组织标准布局owner/repo ├── skills/ │ ├── my-workflow/ │ │ ├── SKILL.md # 必需 │ │ ├── references/ # 可选支持文件 │ │ └── templates/ │ └── another-skill/ │ └── SKILL.md每个技能一个目录SKILL.md 必需其他文件可选。6.2 发布自定义 TapTap 是技能来源的标识。把你的仓库注册为 Tap# 添加 Tap hermes skills tap add my-org/hermes-skills # 列出所有 Tap hermes skills tap list # 移除 Tap hermes skills tap remove my-org/hermes-skills注册后其他 Agent 就能从你的 Tap 安装技能# 浏览所有 hub 技能 hermes skills browse # 搜索 hermes skills search kubernetes # 安装前预览 hermes skills inspect my-org/hermes-skills/deploy-runbook # 安装带安全扫描 hermes skills install my-org/hermes-skills/deploy-runbook # 列出 hub 安装的技能 hermes skills list --source hub # 检查上游更新 hermes skills check # 重装有更新的技能 hermes skills update # 卸载 hermes skills uninstall deploy-runbook6.3 信任等级Skills Hub 的技能分四个信任等级等级策略builtin始终信任official内置信任trusted较宽松策略communitydangerous 判定不可覆盖community 等级的技能安装时会跑安全扫描标记为 dangerous 的操作不能覆盖安装除非加 --force。发布自己的技能时如果涉及敏感操作建议在 SKILL.md 里明确标注方便使用者判断。6.4 Curator 后台维护技能多了之后需要维护。Curator 是 Hermes 的后台技能维护组件curator: enabled: true interval_hours: 168 # 7 天跑一次 stale_after_days: 30 # 30 天没用标记为 stale archive_after_days: 90 # 90 天没用归档 prune_builtins: true相关命令hermes curator status # 查看状态 hermes curator run --dry-run # 试运行不实际改动 hermes curator pin skill # 固定技能防止自动归档 hermes curator prune # 清理过期技能6.5 技能迭代的实用建议技能不是写完就完事。我的经验是每次 Agent 用技能时如果走了弯路就回来 patch 一下 SKILL.md把弯路写进常见问题。这样技能会越用越准。另外技能正文别写太长。Agent 加载技能会占用上下文正文控制在 500 行以内超出的部分拆成 references 文件按需读取。tags 也别堆砌5 到 8 个精准的关键词比 20 个泛词更有效。发布到 Hub 之前先在本地用不同措辞触发几次确认 description 覆盖了常见说法。这一步能省掉使用者大量的为什么我的 Agent 不触发的困惑。最后技能是团队资产建议在仓库里配一份 README 说明每个技能的用途和触发方式方便新成员上手。Skills Hub 的 browse 和 search 命令能帮使用者快速找到需要的技能但前提是你的 description 写得足够清楚。