hermes-agent-skill-authoring

编写 Hermes-Agent 技能（仓库内）

概述

SKILL.md 可以放在两个位置：

1. 用户本地： ~/.hermes/skills/<maybe-category>/<name>/SKILL.md — 个人使用，不共享。通过 skill_manage(action='create') 创建。
2. 仓库内（本技能介绍的情况）： hermes-agent 仓库中的 skills/<category>/<name>/SKILL.md 或 optional-skills/<category>/<name>/SKILL.md — 提交并随软件包一同发布。使用 write_file + git add。skill_manage(action='create') 不会操作此目录树。

仓库内技能必须符合仓库的严格编写标准（参见 AGENTS.md 中的“Skill authoring standards (HARDLINE)”——该章节是权威标准；本技能是实际操作指南）。违反标准的 PR 会被审核者拒绝，因此一开始就达标，比之后返工更省力。

适用场景

• 用户要求你“在此分支／仓库／提交中”添加技能
• 你要提交一个可复用的工作流，随 hermes-agent 一同发布
• 你要编辑 skills/ 或 optional-skills/ 下的现有技能（小幅修改使用 patch，重写使用 write_file；skill_manage 仍可用于修改仓库内技能，但不能用于创建）
• 不适用于：~/.hermes/skills/ 下的个人技能（直接使用 skill_manage）

先确定层级：捆绑还是可选

• 捆绑（skills/<category>/） — 日常使用的功能，适用于多种用户类型，占用空间小。门槛很高：你必须能坦然地说“用户每月会在 5 次以上会话中加载此技能”。
• 可选（optional-skills/<category>/） — 小众、针对特定领域（区块链、游戏、金融、某个应用）、重复性工作／任务类技能，或任何体量较大的技能。通过 hermes skills install official/<category>/<skill> 安装。

拿不准时，选可选。 之后提升层级很容易；降级则会带来维护负担。“对任何有此需求的人都有用”是选择可选层级的理由，而不是捆绑层级的理由。

根据工具的实际用途选择类别，而不是它给人的感觉（AI Agent 命令行工具应放在 autonomous-ai-agents/，即使它“感觉像生产力工具”）。使用 search_files(pattern='*', target='files', path='skills') 确认已有类别，不要轻易创建新的顶层类别。

不要创建路由器／索引／中心技能。 核心内容是指向同级技能的路由表的技能，会增加一次跳转，并重复同级技能自身的“适用场景”触发条件。如果某个技能离开“改为加载技能 X”之类的指引就没有实际内容，那就不要编写；目录和各同级技能的触发条件已经能完成这项工作。

必需的 Frontmatter

验证器的权威依据：tools/skill_manager_tool.py::_validate_frontmatter。验证器的硬性要求：

• 首字节必须是 ---（前面不能有空行）。
• 正文前必须以 \n---\n 结束。
• 解析结果必须是 YAML 映射。
• 必须包含 name 字段。
• 必须包含 description 字段（验证器上限为 1024 个字符——但请参见下方更严格的仓库标准）。
• 结束的 --- 后必须有非空正文。

符合仓库标准的格式（所有字段均应包含，即使验证器没有强制要求）：

---
name: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
description: Concise capability statement, under sixty chars.
version: 0.1.0                    # semver; new skills start at 0.1.0
author: Real Name (github-handle), Hermes Agent
license: MIT
platforms: [linux, macos, windows]   # audit, don't guess — see Platform Gating
metadata:
  hermes:
    tags: [Short, Descriptive, Tags]
    related_skills: [other-in-repo-skill]
---

description 规则（HARDLINE——验证器的 1024 并非标准）

• ≤ 60 个字符。 一个句子，以句号结尾。
• 说明功能，而非实现方式；不要重复技能名称或类别名称（索引会在技能上方显示类别）。
• 不得使用营销用语（“强大”“全面”“无缝”“先进”）。
• 系统提示词中的技能索引显示的宽度为 60；skill_manage 会拒绝超过此长度的新描述或修改后的描述，并会在单词边界处截断更长的旧描述。
• 如果描述中包含 :，请用双引号将其括起来，否则 YAML 会将其解析为映射，导致文档生成器崩溃。引号不计入 60 个字符。

合适：Track named companies for material news with cited digests. 不合适：Use when a user asks to monitor named competitors or companies for product launches, pricing changes, funding, ...（240 个字符——审核时会被拒绝）

author 规则

• 先注明人类作者，再将 “Hermes Agent” 作为次要协作者：Ben Barclay (benbarclay), Hermes Agent。
• 对于贡献的技能，绝不可只写 author: Hermes Agent——应注明人类作者，而非工具，即使（尤其是）文本由 Agent 起草也一样。
• 维护者编写的技能：Teknium (teknium1), Hermes Agent。

related_skills 规则

• 每个条目都必须指向 PR 所处同一仓库状态中实际存在于仓库内的技能。不要引用仅计划编写、位于其他 PR 中，或仅存在于 ~/.hermes/skills/ 的技能。
• 验证每个条目：search_files(pattern='<name>', target='files', path='skills')（以及 optional-skills/）。

平台限制：审查，不要盲信

platforms: 会根据宿主操作系统限制加载。应根据技能的正文和脚本实际调用的内容设置：

技能仅使用……	platforms:
Hermes 工具 + Python 标准库 + 跨平台 CLI	[linux, macos, windows]
bash 管道、grep/awk/sed 链、here-doc	[linux, macos]
osascript、defaults、pmset	[macos]
apt/systemctl//proc	[linux]

在 scripts/ 中搜索仅限 POSIX 平台的信号：fcntl、termios、pty、os.fork、os.killpg、signal.SIGKILL、os.kill(pid, 0) 存活检查、硬编码的 /tmp /proc /etc。默认原则：优先修复跨平台兼容性（tempfile.gettempdir()、pathlib.Path、psutil.pid_exists）；只有依赖确实受平台限制时才限制平台，并在 ## Pitfalls 中说明原因。

大小限制

• 完整的 SKILL.md：上限为 100,000 个字符（由 MAX_SKILL_CONTENT_CHARS 强制执行），但目标应为简单技能约 100 行，复杂技能约 200 行。同类技能的长度为 8-14k 个字符。
• 冗长或仅适用于特定分支的材料应放在 references/*.md、templates/ 或 scripts/ 中，并在 SKILL.md 中指向它们，而不是内联。
• 不要指望模型每次调用都能内联编写解析器或非平凡逻辑——应提供辅助脚本放在 scripts/ 中，并引用其路径。

正文结构（现代章节顺序）

# <Skill> Skill
2-3 sentence intro: what it does, what it doesn't do, dependency stance.

## When to Use          — bulleted triggers (+ "Don't use for:" counter-triggers)
## Prerequisites        — exact env vars, installs, API key sourcing
## How to Run           — canonical invocation through the `terminal` tool
## Quick Reference      — flat command list, no narration
## Procedure            — numbered steps, each with a checkable completion criterion
## Pitfalls             — known limits, things that look broken but aren't
## Verification         — how to prove the skill worked

并非每个技能都适用所有章节（纯流程型任务技能可能没有 Quick Reference），但 When to Use + 可执行的正文内容 + Pitfalls + Verification 是最低要求。删除营销式引言、“Setup Check”空操作，以及对 Prerequisites 中已说明的环境变量的重复解释。

引用 Hermes 工具，而非原始 shell 命令

当技能需要某项能力时，应使用反引号标注正确的 Hermes 工具：terminal、read_file、write_file、patch、search_files、web_search、web_extract、browser_exec、vision_analyze、delegate_task、cronjob。不要提及 Agent 已封装的 shell 工具（grep → search_files、cat → read_file、sed/awk → patch、find/ls → search_files target='files'）。CLI 封装技能应将调用写为 terminal(command="{tool} ...", timeout=...)——仅用 shell 描述（“运行 foo --version”）属于不符合规范，会阻碍审核。如果技能依赖 MCP 服务，应注明该服务，并在 Prerequisites 中说明设置方法。

绝不使用本机路径

使用仓库相对路径（skills/...、tools/skill_manager_tool.py）。将 /home/<you>/... 路径写入已提交的 skill，会导致其他用户无法使用，也会立即引起审查警觉。

写作质量原则

Skill 的作用是让 Agent 的流程更可预测，确保 Agent 始终遵循同一套有用的规范。

1. 优化流程的可预测性。 如果某一行不会改变行为，就删掉。
2. 选择合适的上下文加载量。 每轮都会为描述付出成本；详细内容放在正文或链接的参考资料中。
3. 为步骤设定完成标准。 标准应可检查，并在必要时涵盖所有情况：“已核对每个修改过的文件”胜过“总结变更”。
4. 将规则放在它们所约束的概念旁边。
5. 使用有力的引导词（“紧密迭代”“根本原因”“回归测试”），不要反复长篇解释。
6. 删除重复内容和无效指令。 “仔细一点”和“采用最佳实践”不会改变模型行为，应替换为可检查的标准，或直接删除。

测试与文档（仓库内 Skill 必需）

1. 测试放在 tests/skills/test_<skill>_skill.py 中——仅使用标准库、pytest 和 unittest.mock，不得访问实时网络。通过 scripts/run_tests.sh tests/skills/test_<skill>_skill.py -q 运行。（通用测试 tests/tools/test_skill_manager_tool.py 通过并不能证明你的 Skill 没有问题。）
2. **重新生成文档：**运行 python website/scripts/generate-skill-docs.py，然后控制变更范围——生成器会重写所有自动生成的页面。对不属于你的文件运行 git checkout --；最终差异只能包含你的 SKILL.md、你自己的单页 Skill 文档、目录中的一行，以及 website/sidebars.ts 中的一行插入（通过 search_files(pattern='<your-slug>', path='website/sidebars.ts') 验证——必须恰好命中一次，否则该页面就是孤立页面）。
3. .env.example（仅当 Skill 需要新增环境变量时）：添加一个边界清晰、带注释的代码块；不要改动文件中的其他内容。

工作流

1. **调研同类 Skill：**使用 search_files(target='files') 查找目标类别中的同类项目，并阅读 2 至 3 个同类 SKILL.md 文件，以保持语气和结构一致。优先扩展现有 Skill，而不是创建范围狭窄的同类 Skill。
2. 确定层级和类别（见上文）。拿不准时，选择可选类别——先询问，再推送，不要默认处理。
3. **起草：**使用 write_file 写入 skills/<category>/<name>/SKILL.md（或 optional-skills/...）。
4. 在本地验证：

   import re, pathlib
   from ruamel.yaml import YAML
   content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
   assert content.startswith("---")
   m = re.search(r'\n---\s*\n', content[3:])
   fm = YAML(typ="safe").load(content[3:m.start()+3])
   assert "name" in fm and "description" in fm
   assert len(fm["description"]) <= 60, f"description {len(fm['description'])} chars — hardline is 60"
   assert fm["description"].endswith(".")
   assert "platforms" in fm
   assert len(content) <= 100_000
   

   另外，确认每个 related_skills 条目都在仓库中存在。
5. 添加测试并重新生成文档（见上一节）。
6. 在当前分支上运行 Git add 并提交；然后创建 PR。
7. **注意：**当前会话的 Skill 加载器使用的是缓存——在新会话开始之前，skill_view / skills_list 都看不到新 Skill。这是预期行为，不是错误。

编辑仓库内现有 Skill

• 小幅修复：skill_manage(action='patch', ...) 和 patch 都可用于仓库内的 Skill。
• **重大重写：**使用 write_file 重写整个 SKILL.md。
• **辅助文件：**使用 write_file 将文件写入 Skill 目录下的 references/、templates/ 或 scripts/。
• 务必提交——仓库内的 Skill 是源代码，不是运行时状态。若 frontmatter 有变更，请重新运行文档生成器。

常见陷阱

1. 对仓库内技能使用 skill_manage(action='create')。 它会写入 ~/.hermes/skills/，而不是仓库目录树。请使用 write_file。
2. 把校验器的限制当作标准。 校验器允许描述长达 1024 个字符；审查会拒绝超过 60 个字符的描述。校验器不会检查 platforms:、作者格式、测试或文档——审查会检查。
3. 为贡献的技能设置 author: Hermes Agent。 应先署名人类贡献者。
4. 在 --- 前留有前导空白。 只要存在任何前导空行或 BOM，验证就会失败。
5. 描述过于笼统，或触发条件被埋在第 57 个字符之后。
6. related_skills 指向仓库内不存在的技能（用户本地、计划中或位于其他 PR 中）。
7. 重复创建同类技能。 先查看该类别；应扩展现有技能，而不是创建同级技能。
8. 跳过文档生成器，或推送无关的漂移改动。 两个方向都不对：不重新生成会导致技能孤立且没有文档页面；盲目重新生成会导致差异膨胀，并充斥着其他技能的漂移改动。
9. 指望当前会话能看到新技能。 加载器在会话开始时初始化。
10. 任由技能不断积累陈旧内容。 添加规则时，应删除被其取代的旧表述。

验证清单

• 有意识地确定层级（内置技能的门槛：每月 5+ 次会话；否则放入 optional-skills/）
• 文件位于 skills/<category>/<name>/SKILL.md 或 optional-skills/<category>/<name>/SKILL.md
• 前置元数据从第 0 个字节开始，以 \n---\n 闭合
• name、description、version、author、license、platforms、metadata.hermes.{tags, related_skills} 均存在
• 描述 ≤ 60 个字符，为单句，以句号结尾，且不含营销用语
• author 首先署名人类贡献者
• 根据实际正文/脚本审核 platforms:，而不是从同类技能复制
• 每个 related_skills 条目都能在仓库内找到对应技能
• 正文遵循现代章节顺序；命令通过 Hermes 工具呈现
• 文件中任何位置均无机器本地路径
• 每个有序步骤都有可核验的完成标准
• tests/skills/test_<skill>_skill.py 中的测试在 scripts/run_tests.sh 下通过
• 严格限定范围并重新生成文档；侧边栏中该 slug 恰有一个条目
• 在目标分支上执行 git add + commit；创建 PR