Skills 系统#
Skills 是 agent 在需要时可以加载的按需知识文档。它们遵循渐进式披露(progressive disclosure)模式以最小化 token 用量,并兼容 agentskills.io 开放标准。所有 skills 存放在 ~/.hermes/skills/ 中——这是主目录和唯一可信来源。全新安装时,捆绑的 skills 会从仓库复制过来。通过 Hub 安装和 agent 创建的 skills 也存放在此处。agent 可以修改或删除任何 skill。你也可以让 Hermes 指向外部 skill 目录——与本地目录一起扫描的额外文件夹。参见下方的外部 Skill 目录。使用 Skills#
每个已安装的 skill 都会自动作为斜杠命令可用:捆绑的 plan skill 是一个很好的示例。运行 /plan [request] 会加载该 skill 的指令,告知 Hermes 在需要时检查上下文、编写 markdown 实现计划而非直接执行任务,并将结果保存在相对于当前工作区/后端工作目录的 .hermes/plans/ 下。渐进式披露#
Skills 使用一种节省 token 的加载模式:Level 0: skills_list() → [{name, description, category}, ...] (~3k tokens)
Level 1: skill_view(name) → Full content + metadata (varies)
Level 2: skill_view(name, path) → Specific reference file (varies)
agent 只在真正需要时才加载完整的 skill 内容。SKILL.md 格式#
平台特定 Skills#
Skills 可以使用 platforms 字段将自身限制在特定操作系统上:| 值 | 匹配 |
|---|
macos | macOS(Darwin) |
linux | Linux |
windows | Windows |
设置后,该 skill 会在不兼容的平台上自动从系统提示词、skills_list() 和斜杠命令中隐藏。若省略,则在所有平台上加载。Skill 输出与媒体传递#
当 skill 响应(或任何 agent 响应)包含指向媒体文件的裸绝对路径时——例如 /home/user/screenshots/diagram.png——gateway 会自动检测到它,将其从可见文本中剥离,并以原生方式将文件传递给用户的聊天界面(Telegram 图片、Discord 附件等),而不是在消息中留下原始路径。对于音频,[[audio_as_voice]] 指令会将音频文件提升为在支持该功能的平台(Telegram、WhatsApp)上的原生语音消息气泡。强制文档式传递:[[as_document]]#
有时你需要与内联预览相反的效果:你希望文件作为可下载附件传递,而不是经过重新压缩的图片气泡。典型示例是高分辨率截图或图表——Telegram 的 sendPhoto 会将其重新压缩至约 200 KB、1280 px,严重影响可读性。通过 sendDocument 发送的 1-2 MB PNG 则保留原始字节完整无损。如果响应(或其中任何文本——通常是最后一行)包含字面指令 [[as_document]],则从该响应中提取的每个媒体路径都会作为文档/文件附件传递,而不是图片气泡:Here is your rendered chart:
/home/user/.hermes/cache/chart-q4-2025.png
[[as_document]]
该指令在传递前会被剥离,用 户不会看到它。粒度有意设计为每个响应全有或全无:发出一次 [[as_document]],同一响应中的每个图片路径都会作为文档传递。这与 [[audio_as_voice]] 的作用范围一致。你生成了用户需要作为文件的截图或图表(用于在其他工具中编辑、存档、完整分享)。
默认的有损预览会遮蔽细节(小字体、像素精确的图表、对颜色敏感的渲染)。
没有单独文档路径的平台(如 SMS)会回退到其支持的任何附件机制。条件激活(Fallback Skills)#
Skills 可以根据当前会话中可用的工具自动显示或隐藏自身。这对于fallback skills(回退 skills)最为有用——仅在高级工具不可用时才应出现的免费或本地替代方案。| 字段 | 行为 |
|---|
fallback_for_toolsets | 当列出的 toolsets 可用时,skill 隐藏。不可用时显示。 |
fallback_for_tools | 同上,但检查单个工具而非 toolsets。 |
requires_toolsets | 当列出的 toolsets 不可用时,skill 隐藏。可用时显示。 |
requires_tools | 同上,但检查单个工具。 |
示例: 内置的 duckduckgo-search skill 使用 fallback_for_toolsets: [web]。当你设置了 FIRECRAWL_API_KEY 时,web toolset 可用,agent 使用 web_search——DuckDuckGo skill 保持隐藏。如果 API key 缺失,web toolset 不可用,DuckDuckGo skill 会自动作为 fallback 出现。没有任何条件字段的 skills 行为与之前完全相同——始终显示。加载时的安全设置#
Skills 可以声明所需的环境变量,而不会从发现列表中消失:当遇到缺失的值时,Hermes 仅在本地 CLI 中实际加载 skill 时才会安全地请求输入。你可以跳过设置并继续使用该 skill。消息平台不会在聊天中请求密钥——它们会告诉你改用本地的 hermes setup 或 ~/.hermes/.env。一旦设置,声明的环境变量会自动传递到 execute_code 和 terminal 沙箱——skill 的脚本可以直接使用 $TENOR_API_KEY。对于非 skill 的环境变量, 使用 terminal.env_passthrough 配置选项。详情参见环境变量传递。Skill 配置设置#
Skills 还可以声明存储在 config.yaml 中的非密钥配置设置(路径、偏好项):设置存储在 config.yaml 的 skills.config 下。hermes config migrate 会提示配置未设置的项,hermes config show 会显示它们。当 skill 加载时,其解析后的配置值会注入到上下文中,agent 会自动知晓已配置的值。Skill 目录结构#
~/.hermes/skills/ # Single source of truth
├── mlops/ # Category directory
│ ├── axolotl/
│ │ ├── SKILL.md # Main instructions (required)
│ │ ├── references/ # Additional docs
│ │ ├── templates/ # Output formats
│ │ ├── scripts/ # Helper scripts callable from the skill
│ │ └── assets/ # Supplementary files
│ └── vllm/
│ └── SKILL.md
├── devops/
│ └── deploy-k8s/ # Agent-created skill
│ ├── SKILL.md
│ └── references/
├── .hub/ # Skills Hub state
│ ├── lock.json
│ ├── quarantine/
│ └── audit.log
└── .bundled_manifest # Tracks seeded bundled skills
外部 Skill 目录#
如果你在 Hermes 之外维护 skills——例如,供多个 AI 工具使用的共享 ~/.agents/skills/ 目录——你可以告诉 Hermes 也扫描这些目录。在 ~/.hermes/config.yaml 的 skills 部分下添加 external_dirs:路径支持 ~ 展开和 ${VAR} 环境变量替换。工作原理#
本地创建,就地更新:新的 agent 创建的 skills 写入 ~/.hermes/skills/。现有 skills 在找到的位置被修改,包括 external_dirs 下的 skills,当 agent 使用 skill_manage 操作(如 patch、edit、write_file、remove_file 或 delete)时。
外部目录不是写保护边界:如果外部 skill 目录对 Hermes 进程可写,agent 管理的 skill 更新可以修改该目录中的文件。如果共享的外部 skills 必须保持只读,请使用文件系统权限或单独的 profile/toolset 设置。
本地优先:如果同一 skill 名称同时存在于本地目录和外部目录中,本地版本优 先。
完整集成:外部 skills 出现在系统提示词索引、skills_list、skill_view 以及 /skill-name 斜杠命令中——与本地 skills 无异。
不存在的路径会被静默跳过:如果配置的目录不存在,Hermes 会忽略它而不报错。适用于可能不在每台机器上都存在的可选共享目录。
~/.hermes/skills/ # Local (primary, read-write)
├── devops/deploy-k8s/
│ └── SKILL.md
└── mlops/axolotl/
└── SKILL.md
~/.agents/skills/ # External (shared, mutable if writable)
├── my-custom-workflow/
│ └── SKILL.md
└── team-conventions/
└── SKILL.md
所有四个 skills 都出现在你的 skill 索引中。如果你在本地创建一个名为 my-custom-workflow 的新 skill,它会遮蔽外部版本。Skill 捆绑包#
Skill 捆绑包是将多个 skills 归组在单个斜杠命令下的小型 YAML 文件。当你运行 /<bundle-name> 时,捆绑包中列出的每个 skill 都会同时加载——当某个特定任务总是受益于同一组 skills 时非常有用。快速示例#
/backend-dev refactor the auth middleware
agent 接收到所有三个 skills 加载到一条用户消息中,斜杠命令后的任何文本都作为用户指令附加。YAML 模式#
捆绑包存放在 ~/.hermes/skill-bundles/<slug>.yaml 中,格式如下:name(可选——默认为文件名主干)——捆绑包的显示名称。规范化为连字符 slug 用于斜杠命令(Backend Dev → /backend-dev)。
description(可选)——在 /bundles 和 hermes bundles list 中显示的简短文本。
skills(必填,非空列表)——skill 名称或相对于你的 skills 目录的路径。使用与 /<skill-name> 相同的标识符。
instruction(可选)——附加在加载的 skill 内容前的额外指导。适用于固化"我们总是这样一起使用这些 skills"的方式。
管理捆绑包#
在聊天会话中,/bundles 会列出每个已安装的捆绑包及其 skills。当 slug 冲突时,捆绑包优先于单个 skills。 如果你将捆绑包命名为 research,同时也有一个名为 research 的 skill,/research 会调用捆绑包。这是有意为之——你通过命名选择了捆绑包。
缺失的 skills 会被跳过,而不是致命错误。 如果捆绑包列出了 skill-foo 但你未安装它,捆绑包仍会加载能解析的 skills,agent 会收到一条列出跳过内容的说明。
捆绑包在每个界面都有效——交互式 CLI、TUI、仪表板聊天以及每个 gateway 平台(Telegram、Discord、Slack……)——因为调度与单个 skill 命令集中在同一位置。
捆绑包不会使 prompt 缓存失效。 它们在调用时生成一条新的用户消息,与 /<skill-name> 的方式相同——不修改系统提示词。
捆绑包优于逐个手动安装 skill 的场景#
你总是为某个重复任务配对相同的 skills(/backend-dev、/release-prep、/incident-response)。
你想要比依次输入多个 /skill 调用更简洁的心智模型。
你想通过将捆绑包 YAML 提交到共享 dotfiles 仓库并符号链接到 ~/.hermes/skill-bundles/ 来发布团队范围的"任务配置文件"。
捆绑包只是一个 YAML 别名——它不会为你安装 skills。Skills 本身必须已经存在(在 ~/.hermes/skills/ 或外部 skill 目录中)。否则捆绑包调用只会跳过缺失的 skills。Agent 管理的 Skills(skill_manage 工具)#
agent 可以通过 skill_manage 工具创建、更新和删除自己的 skills。这是 agent 的程序性记忆——当它找到一个非平凡的工作流时,它会将该方法保存为 skill 以供将来复用。Agent 创建 Skills 的时机#
| 操作 | 用途 | 关键参数 |
|---|
create | 从头创建新 skill | name、content(完整 SKILL.md)、可选 category |
patch | 针对性修复(首选) | name、old_string、new_string |
edit | 重大结构性重写 | name、content(完整 SKILL.md 替换) |
delete | 完全删除一个 skill | name |
write_file | 添加/更新支持文件 | name、file_path、file_content |
remove_file | 删除支持文件 | name、file_path |
patch 操作是更新的首选方式——它比 edit 更节省 token,因为工具调用中只出现变更的文本。
Skills Hub#
从在线注册表、skills.sh、直接的知名 skill 端点以及官方可选 skills 中浏览、搜索、安装和管理 skills。常用命令#
支持的 hub 来源#
| 来源 | 示例 | 说明 |
|---|
official | official/security/1password | Hermes 随附的可选 skills。 |
skills-sh | skills-sh/vercel-labs/agent-skills/vercel-react-best-practices | 可通过 hermes skills search <query> --source skills-sh 搜索。当 skills.sh slug 与仓库文件夹不同时,Hermes 会解析别名式 skills。 |
well-known | well-known:https://mintlify.com/docs/.well-known/skills/mintlify | 直接从网站的 /.well-known/skills/index.json 提供的 skills。使用站点或文档 URL 搜索。 |
url | https://sharethis.chat/SKILL.md | 指向单文件 SKILL.md 的直接 HTTP(S) URL。名称解析顺序:frontmatter → URL slug → 交互式提示 → --name 标志。 |
github | openai/skills/k8s | 直接从 GitHub 仓库/路径安装以及基于 GitHub 的自定义 tap。 |
clawhub、lobehub、browse-sh、claude-marketplace | 来源特定标识符 | 社区或市场集成。 |
集成的 hub 和注册表#
Hermes 目前与以下 skills 生态系统和发现来源集成:1. 官方可选 skills(official)#
这些 skills 在 Hermes 仓库中维护,以内置信任级别安装。2. skills.sh(skills-sh)#
这是 Vercel 的公共 skills 目录。Hermes 可以直接搜索它、查看 skill 详情页、解析别名式 slug,并从底 层源仓库安装。3. Well-known skill 端点(well-known)#
这是基于 URL 的发现机制,来自发布 /.well-known/skills/index.json 的站点。它不是单一的集中式 hub——它是一种 Web 发现约定。4. 直接 GitHub skills(github)#
Hermes 可以直接从 GitHub 仓库和基于 GitHub 的 tap 安装。当你已知仓库/路径或想添加自己的自定义源仓库时非常有用。NVIDIA/skills — NVIDIA 官方验证的技能(带签名 skill.oms.sig 与治理用 skill-card.md) 5. ClawHub(clawhub)#
6. Claude 市场式仓库(claude-marketplace)#
Hermes 支持发布 Claude 兼容插件/市场清单的市场仓库。Hermes 来源 id:claude-marketplace7. LobeHub(lobehub)#
Hermes 可以从 LobeHub 的公共目录中搜索并将 agent 条目转换为可安装的 Hermes skills。8. browse.sh(browse-sh)#
Hermes 与 browse.sh 集成,这是 Browserbase 的目录,包含 200+ 个针对特定站点的浏览器自动化 SKILL.md 文件(Airbnb、Amazon、arXiv、12306.cn、Etsy、Xero 等)。每个 skill 描述如何端到端驱动一个网站,适合与 Hermes 的浏览器工具以及你已安装的任何浏览器自动化 skills 配合使用。目录 API:https://browse.sh/api/skills
标识符使用 browse-sh/<hostname>/<task-id> 的形式,与 browse.sh 目录公开的 slug 匹配。内容通过每个 skill 的详情端点(/api/skills/<slug> → skillMdUrl)解析,而不是通过目录的 GitHub sourceUrl。9. 直接 URL(url)#
直接从任何 HTTP(S) URL 安装单文件 SKILL.md——当作者在自己的站点上托管 skill 时非常有用(无 hub 列表,无需输入 GitHub 路径)。Hermes 获取 URL,解析 YAML frontmatter,进行安全扫描并安装。范围:仅限单文件 SKILL.md。包含 references/ 或 scripts/ 的多文件 skills 需要清单,应通过上述其他来源之一发布。
1.
SKILL.md YAML frontmatter 中的 name: 字段(推荐——每个格式良好的 skill 都有)。
2.
URL 路径中的父目录名称(例如 .../my-skill/SKILL.md → my-skill,或 .../my-skill.md → my-skill),当它是有效标识符(^[a-z][a-z0-9_-]*$)时。
4.
在非交互式界面(TUI 内的 /skills install 斜杠命令、gateway 平台、脚本)上,给出指向 --name 覆盖的清晰错误。
信任级别始终为 community——与所有其他来源一样运行相同的安全扫描。URL 作为安装标识符存储,因此当你想刷新时,hermes skills update 会自动从同一 URL 重新获取。安全扫描与 --force#
所有通过 hub 安装的 skills 都经过安全扫描器检查,检测数据泄露、prompt 注入、破坏性命令、供应链信号及其他威胁。hermes skills inspect ... 现在还会在可用时显示上游元数据:当你已审查第三方 skill 并希望覆盖非危险性策略阻止时,使用 --force:--force 可以覆盖谨慎/警告类发现的策略阻止。
--force 不能覆盖 dangerous 扫描结论。
官方可选 skills(official/...)被视为内置信任,不显示第三方警告面板。
信任级别#
| 级别 | 来源 | 策略 |
|---|
builtin | 随 Hermes 附带 | 始终受信任 |
official | 仓库中的 optional-skills/ | 内置信任,无第三方警告 |
trusted | 受信任的注册表/仓库,如 openai/skills、anthropics/skills、huggingface/skills、NVIDIA/skills | 比社区来源更宽松的策略 |
community | 其他所有来源(skills.sh、well-known 端点、自定义 GitHub 仓库、大多数市场) | 非危险性发现可用 --force 覆盖;dangerous 结论保持阻止 |
更新生命周期#
hub 现在跟踪足够的来源信息以重新检查已安装 skills 的上游副本:这使用存储的来源标识符加上当前上游捆绑包内容哈希来检测漂移。Skills hub 操作使用 GitHub API,未认证用户的速率限制为每小时 60 次请求。如果在安装或搜索时看到速率限制错误,请在 .env 文件中设置 GITHUB_TOKEN 以将限制提高到每小时 5,000 次请求。发生此情况时,错误消息会包含可操作的提示。
发布自定义 skill tap#
如果你想分享一组精选的 skills——为你的团队、组织或公开分享——你可以将它们发布为 tap:其他 Hermes 用户通过 hermes skills tap add <owner/repo> 添加的 GitHub 仓库。无需服务器,无需注册表注册,无需发布流水线。只需一个包含 SKILL.md 文件的目录。仓库布局#
tap 是任何 GitHub 仓库(公开或私有——私有仓库需要 GITHUB_TOKEN),布局如下:owner/repo
├── skills/ # default path; configurable per-tap
│ ├── my-workflow/
│ │ ├── SKILL.md # required
│ │ ├── references/ # optional supporting files
│ │ ├── templates/
│ │ └── scripts/
│ ├── another-skill/
│ │ └── SKILL.md
│ └── third-skill/
│ └── SKILL.md
└── README.md # optional but helpful
每个 skill 存放在 tap 根路径(默认 skills/)下的独立目录中。
每个 skill 目录必须包含一个带有标准 SKILL.md frontmatter 的 SKILL.md(name、description,以及可选的 metadata.hermes.tags、version、author、platforms、metadata.hermes.config)。 references/、templates/、scripts/、assets/ 等子目录在安装时与 SKILL.md 一起下载。
目录名以 . 或 _ 开头的 skills 会被忽略。
Hermes 通过列出 tap 路径的每个子目录并探测每个目录中的 SKILL.md 来发现 skills。最小 tap 示例#
my-org/hermes-skills
└── skills/
└── deploy-runbook/
└── SKILL.md
skills/deploy-runbook/SKILL.md:将其推送到 GitHub 后,任何 Hermes 用户都可以订阅并安装:非默认路径#
如果你的 skills 不在 skills/ 下(当你向现有项目添加 skills/ 子树时很常见),请编辑 ~/.hermes/.hub/taps.json 中的 tap 条目:{
"taps": [
{"repo": "my-org/platform-docs", "path": "internal/skills/"}
]
}
hermes skills tap add CLI 默认将新 tap 的 path 设为 "skills/";如果需要不同路径,请直接编辑该文件。hermes skills tap list 显示每个 tap 的有效路径。直接安装单个 skills(无需添加 tap)#
用户也可以从任何公开 GitHub 仓库安装单个 skill,而无需将整个仓库添加为 tap:当你想分享一个 skill 而不要求用户订阅你的整个注册表时非常有用。tap 的信任级别#
新 tap 默认分配 community 信任级别。从中安装的 skills 经过标准安全扫描,首次安装时显示第三方警告面板。如果你的组织或广泛受信任的来源应获得更高信任,请将其仓库添加到 tools/skills_hub.py 中的 TRUSTED_REPOS(需要 Hermes 核心 PR)。Tap 管理#
/skills tap list
/skills tap add myorg/skills-repo
/skills tap remove myorg/skills-repo
Tap 存储在 ~/.hermes/.hub/taps.json 中(按需创建)。捆绑 skill 更新(hermes skills reset)#
Hermes 在仓库的 skills/ 中附带一组捆绑 skills。在安装时以及每次 hermes update 时,同步过程会将这些 skills 复制到 ~/.hermes/skills/ 中,并在 ~/.hermes/skills/.bundled_manifest 记录一个清单,将每个 skill 名称映射到同步时的内容哈希(origin hash)。每次同步时,Hermes 重新计算本地副本的哈希并与 origin hash 比较:未更改 → 可以安全拉取上游变更,复制新的捆绑版本,记录新的 origin hash。
已更改 → 视为用户修改并永久跳过,因此你的编辑不会被覆盖。
这种保护机制很好,但有一个棘手的边缘情况。如果你编辑了一个捆绑 skill,后来想通过从 ~/.hermes/hermes-agent/skills/ 复制粘贴来放弃更改并回到捆绑版本,清单仍然保存着上次成功同步时的旧 origin hash。你新复制粘贴的内容(当前捆绑哈希)与那个过时的 origin hash 不匹配,因此同步继续将其标记为用户修改。hermes skills reset 是解决此问题的方法:/skills reset google-workspace
/skills reset google-workspace --restore
每个 profile 在其自己的 HERMES_HOME 下有自己的 .bundled_manifest,因此 hermes -p coder skills reset <name> 只影响该 profile。
斜杠命令(在聊天中)#
/skills browse
/skills search react --source skills-sh
/skills search https://mintlify.com/docs --source well-known
/skills inspect skills-sh/vercel-labs/json-render/json-render-react
/skills install openai/skills/skill-creator --force
/skills check
/skills update
/skills reset google-workspace
/skills list
官方可选 skills 仍使用 official/security/1password 和 official/migration/openclaw-migration 等标识符。