技能系统

技能（Skills）是 Agent 在需要时可以加载的按需知识文档。它们遵循渐进式披露模式以最小化 token 使用，并兼容 agentskills.io 开放标准。

所有技能位于 ~/.hermes/skills/ ——这是主目录和唯一可信来源。初次安装时，内置技能从仓库复制过来。通过 Hub 安装和 Agent 创建的技能也放在这里。Agent 可以修改或删除任何技能。

你还可以将 Hermes 指向外部技能目录——与本地目录一起扫描的额外文件夹。参见下方的外部技能目录。

另请参阅：

• 内置技能目录
• 官方可选技能目录

使用技能

每个已安装的技能都自动作为斜杠命令可用：

# 在 CLI 或任何消息平台中：
/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/plan design a rollout for migrating our auth provider

# 只输入技能名称即可加载它，让 Agent 询问你需要什么：
/excalidraw

内置的 plan 技能是个好例子。运行 /plan [请求] 会加载该技能的指令，告诉 Hermes 在需要时检查上下文，写一个 Markdown 实现计划而不是直接执行任务，并将结果保存在活跃工作区/后端工作目录下的 .hermes/plans/ 中。

你也可以通过自然对话与技能互动：

hermes chat --toolsets skills -q "What skills do you have?"
hermes chat --toolsets skills -q "Show me the axolotl skill"

渐进式披露

技能使用一种高效的 token 加载模式：

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → 完整内容 + 元数据       (不定)
Level 2: skill_view(name, path)  → 特定参考文件       (不定)

Agent 只在真正需要时才加载完整的技能内容。

SKILL.md 格式

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]     # 可选——限制到特定操作系统平台
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]    # 可选——条件激活（见下文）
    requires_toolsets: [terminal]   # 可选——条件激活（见下文）
    config:                          # 可选——config.yaml 设置
      - key: my.setting
        description: "This controls what"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

平台特定技能

技能可以使用 platforms 字段将自己限制到特定操作系统：

值	匹配平台
macos	macOS（Darwin）
linux	Linux
windows	Windows

platforms: [macos]            # 仅 macOS（例如 iMessage、Apple Reminders、FindMy）
platforms: [macos, linux]     # macOS 和 Linux

设置后，该技能会在不兼容的平台上自动从系统提示、skills_list() 和斜杠命令中隐藏。如果省略，技能在所有平台上加载。

条件激活（备用技能）

技能可以根据当前会话中哪些工具可用来自动显示或隐藏自己。这对于备用技能最有用——只有在高级工具不可用时才应出现的免费或本地替代方案。

metadata:
  hermes:
    fallback_for_toolsets: [web]      # 仅当这些工具集不可用时显示
    requires_toolsets: [terminal]     # 仅当这些工具集可用时显示
    fallback_for_tools: [web_search]  # 仅当这些特定工具不可用时显示
    requires_tools: [terminal]        # 仅当这些特定工具可用时显示

字段	行为
fallback_for_toolsets	当列出的工具集可用时，技能被隐藏。不可用时显示。
fallback_for_tools	相同，但检查单个工具而非工具集。
requires_toolsets	当列出的工具集不可用时，技能被隐藏。可用时显示。
requires_tools	相同，但检查单个工具。

示例： 内置的 duckduckgo-search 技能使用 fallback_for_toolsets: [web]。当你设置了 FIRECRAWL_API_KEY 时，web 工具集可用，Agent 使用 web_search——DuckDuckGo 技能保持隐藏。如果 API 密钥缺失，web 工具集不可用，DuckDuckGo 技能会自动作为备用出现。

没有任何条件字段的技能行为与之前完全相同——它们始终显示。

加载时的安全设置

技能可以声明所需的环境变量而不从发现中消失：

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.google.com/tenor
    required_for: full functionality

当遇到缺失的值时，Hermes 只在技能实际加载于本地 CLI 时才安全地询问。你可以跳过设置并继续使用技能。消息平台永远不会在聊天中询问密钥——它们会告诉你改用 hermes setup 或 ~/.hermes/.env 在本地设置。

一旦设置，声明的环境变量会自动传递给 execute_code 和 terminal 沙箱——技能的脚本可以直接使用 $TENOR_API_KEY。对于非技能环境变量，使用 terminal.env_passthrough 配置选项。详情参见环境变量透传。

技能配置设置

技能还可以声明存储在 config.yaml 中的非密钥配置设置（路径、偏好）：

metadata:
  hermes:
    config:
      - key: myplugin.path
        description: Path to the plugin data directory
        default: "~/myplugin-data"
        prompt: Plugin data directory path

设置存储在你的 config.yaml 的 skills.config 下。hermes config migrate 提示输入未配置的设置，hermes config show 显示它们。当技能加载时，其解析的配置值会自动注入到上下文中，使 Agent 能够知道已配置的值。

详情参见技能设置和创建技能——配置设置。

技能目录结构

~/.hermes/skills/                  # 唯一可信来源
├── mlops/                         # 分类目录
│   ├── axolotl/
│   │   ├── SKILL.md               # 主要指令（必须）
│   │   ├── references/            # 额外文档
│   │   ├── templates/             # 输出格式
│   │   ├── scripts/               # 技能可调用的辅助脚本
│   │   └── assets/                # 补充文件
│   └── vllm/
│       └── SKILL.md
├── devops/
│   └── deploy-k8s/                # Agent 创建的技能
│       ├── SKILL.md
│       └── references/
├── .hub/                          # 技能 Hub 状态
│   ├── lock.json
│   ├── quarantine/
│   └── audit.log
└── .bundled_manifest              # 追踪已植入的内置技能

外部技能目录

如果你在 Hermes 外部维护技能——例如多个 AI 工具共用的 ~/.agents/skills/ 目录——你可以告诉 Hermes 也扫描这些目录。

在 ~/.hermes/config.yaml 的 skills 部分下添加 external_dirs：

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

路径支持 ~ 展开和 ${VAR} 环境变量替换。

工作原理

• 只读：外部目录只用于技能发现扫描。当 Agent 创建或编辑技能时，始终写入 ~/.hermes/skills/。
• 本地优先：如果本地目录和外部目录中存在同名技能，本地版本优先。
• 完全集成：外部技能出现在系统提示索引、skills_list、skill_view 和 /skill-name 斜杠命令中——与本地技能无异。
• 不存在的路径被静默跳过：如果配置的目录不存在，Hermes 会忽略它而不报错。适用于可能不在每台机器上都存在的可选共享目录。

示例

~/.hermes/skills/               # 本地（主要，读写）
├── devops/deploy-k8s/
│   └── SKILL.md
└── mlops/axolotl/
    └── SKILL.md

~/.agents/skills/               # 外部（只读，共享）
├── my-custom-workflow/
│   └── SKILL.md
└── team-conventions/
    └── SKILL.md

所有四个技能都出现在你的技能索引中。如果你在本地创建一个名为 my-custom-workflow 的新技能，它会遮蔽外部版本。

Agent 管理技能（skill_manage 工具）

Agent 可以通过 skill_manage 工具创建、更新和删除自己的技能。这是 Agent 的程序性记忆——当它找到一个非平凡的工作流程时，它会将方法保存为技能供将来重用。

Agent 何时创建技能

• 成功完成复杂任务后（5+ 次工具调用）
• 遇到错误或死路并找到可行路径时
• 用户纠正了它的方法时
• 发现了非平凡的工作流程时

动作

动作	用途	关键参数
create	从头创建新技能	name、content（完整 SKILL.md）、可选 category
patch	针对性修复（首选）	name、old_string、new_string
edit	重大结构性重写	name、content（完整 SKILL.md 替换）
delete	完全删除技能	name
write_file	添加/更新辅助文件	name、file_path、file_content
remove_file	删除辅助文件	name、file_path

提示

patch 动作是更新的首选方式——它比 edit 更省 token，因为工具调用中只出现变更的文本。

技能 Hub

从在线注册表、skills.sh、直接的 well-known 技能端点和官方可选技能浏览、搜索、安装和管理技能。

常用命令

hermes skills browse                              # 浏览所有 Hub 技能（官方优先）
hermes skills browse --source official            # 仅浏览官方可选技能
hermes skills search kubernetes                   # 搜索所有来源
hermes skills search react --source skills-sh     # 搜索 skills.sh 目录
hermes skills search https://mintlify.com/docs --source well-known
hermes skills inspect openai/skills/k8s           # 安装前预览
hermes skills install openai/skills/k8s           # 使用安全扫描安装
hermes skills install official/security/1password
hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force
hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify
hermes skills install https://sharethis.chat/SKILL.md              # 直接 URL（单文件 SKILL.md）
hermes skills install https://example.com/SKILL.md --name my-skill # frontmatter 没有名称时覆盖
hermes skills list --source hub                   # 列出通过 Hub 安装的技能
hermes skills check                               # 检查已安装的 Hub 技能是否有上游更新
hermes skills update                              # 在需要时用上游变更重新安装 Hub 技能
hermes skills audit                               # 重新扫描所有 Hub 技能以确保安全
hermes skills uninstall k8s                       # 删除一个 Hub 技能
hermes skills reset google-workspace              # 将内置技能从"用户修改"状态解除（见下文）
hermes skills reset google-workspace --restore    # 同时恢复内置版本，删除你的本地编辑
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills snapshot export setup.json          # 导出技能配置
hermes skills tap add myorg/skills-repo           # 添加自定义 GitHub 来源

支持的 Hub 来源

来源	示例	备注
official	official/security/1password	Hermes 附带的可选技能。
skills-sh	skills-sh/vercel-labs/agent-skills/vercel-react-best-practices	可通过 hermes skills search <query> --source skills-sh 搜索。Hermes 会在 skills.sh 别名与仓库文件夹不同时解析别名式技能。
well-known	well-known:https://mintlify.com/docs/.well-known/skills/mintlify	直接从网站的 /.well-known/skills/index.json 提供的技能。使用网站或文档 URL 进行搜索。
url	https://sharethis.chat/SKILL.md	直接指向单文件 SKILL.md 的 HTTP(S) URL。名称解析：frontmatter → URL 片段 → 交互提示 → --name 标志。
github	openai/skills/k8s	直接 GitHub 仓库/路径安装和自定义 tap。
clawhub、lobehub、claude-marketplace	特定来源标识符	社区或市场集成。

集成的 Hub 和注册表

Hermes 目前集成了以下技能生态系统和发现来源：

1. 官方可选技能（official）

这些技能在 Hermes 仓库中维护，以内置信任级别安装。

• 目录：官方可选技能目录
• 仓库中的来源：optional-skills/
• 示例：

hermes skills browse --source official
hermes skills install official/security/1password

2. skills.sh（skills-sh）

这是 Vercel 的公共技能目录。Hermes 可以直接搜索它、检查技能详情页面、解析别名式 slug，并从底层源仓库安装。

• 目录：skills.sh
• CLI/工具仓库：vercel-labs/skills
• 官方 Vercel 技能仓库：vercel-labs/agent-skills
• 示例：

hermes skills search react --source skills-sh
hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react
hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force

3. Well-known 技能端点（well-known）

这是从发布 /.well-known/skills/index.json 的网站进行基于 URL 的发现。它不是单一的集中式 Hub——它是一种 Web 发现约定。

• 示例实时端点：Mintlify 文档技能索引
• 参考服务器实现：vercel-labs/skills-handler
• 示例：

hermes skills search https://mintlify.com/docs --source well-known
hermes skills inspect well-known:https://mintlify.com/docs/.well-known/skills/mintlify
hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify

4. 直接 GitHub 技能（github）

Hermes 可以直接从 GitHub 仓库和基于 GitHub 的 tap 安装。当你已经知道仓库/路径或想添加自己的自定义来源仓库时很有用。

默认 tap（无需任何设置即可浏览）：

• openai/skills

• anthropics/skills

• VoltAgent/awesome-agent-skills

• garrytan/gstack

• 示例：

hermes skills install openai/skills/k8s
hermes skills tap add myorg/skills-repo

5. ClawHub（clawhub）

作为社区来源集成的第三方技能市场。

• 网站：clawhub.ai
• Hermes 来源 ID：clawhub

6. Claude 市场式仓库（claude-marketplace）

Hermes 支持发布 Claude 兼容插件/市场清单的市场仓库。

已知的集成来源包括：

• anthropics/skills
• aiskillstore/marketplace

Hermes 来源 ID：claude-marketplace

7. LobeHub（lobehub）

Hermes 可以搜索并将 LobeHub 公共目录中的 Agent 条目转换为可安装的 Hermes 技能。

• 网站：LobeHub
• 公共 Agent 索引：chat-agents.lobehub.com
• 后端仓库：lobehub/lobe-chat-agents
• Hermes 来源 ID：lobehub

8. 直接 URL（url）

直接从任何 HTTP(S) URL 安装单文件 SKILL.md——当作者将技能托管在自己的网站上时很有用（无 Hub 列表，无需输入 GitHub 路径）。Hermes 获取 URL，解析 YAML frontmatter，进行安全扫描并安装。

• Hermes 来源 ID：url
• 标识符：URL 本身（无需前缀）
• 范围：仅单文件 SKILL.md。带有 references/ 或 scripts/ 的多文件技能需要清单，应通过上述其他来源之一发布。

hermes skills install https://sharethis.chat/SKILL.md
hermes skills install https://example.com/my-skill/SKILL.md --category productivity

名称解析顺序：

1. SKILL.md YAML frontmatter 中的 name: 字段（推荐——每个格式规范的技能都有）。
2. URL 路径中的父目录名（例如 .../my-skill/SKILL.md → my-skill，或 .../my-skill.md → my-skill），当它是有效标识符（^[a-z][a-z0-9_-]*$）时。
3. 带 TTY 的终端上的交互提示。
4. 在非交互式界面（TUI 中的 /skills install 斜杠命令、网关平台、脚本）上，返回指向 --name 覆盖的清晰错误。

# frontmatter 没有名称且 URL 片段没有帮助——提供一个：
hermes skills install https://example.com/SKILL.md --name sharethis-chat

# 或在聊天会话中：
/skills install https://example.com/SKILL.md --name sharethis-chat

信任级别始终为 community——与其他所有来源相同的安全扫描会运行。URL 存储为安装标识符，因此当你想刷新时 hermes skills update 会自动从相同 URL 重新获取。

安全扫描和 --force

所有通过 Hub 安装的技能都经过安全扫描器检查数据外泄、提示词注入、破坏性命令、供应链信号和其他威胁。

hermes skills inspect ... 现在也在可用时显示上游元数据：

• 仓库 URL
• skills.sh 详情页面 URL
• 安装命令
• 每周安装量
• 上游安全审计状态
• well-known 索引/端点 URL

当你已经审查了第三方技能并想覆盖非危险的策略阻止时，使用 --force：

hermes skills install skills-sh/anthropics/skills/pdf --force

重要行为：

• --force 可以覆盖谨慎/警告级别发现的策略阻止。
• --force 不能覆盖 dangerous 扫描判定。
• 官方可选技能（official/...）被视为内置信任，不显示第三方警告面板。

信任级别

级别	来源	策略
builtin	随 Hermes 发布	始终受信任
official	仓库中的 optional-skills/	内置信任，无第三方警告
trusted	受信任的注册表/仓库，如 openai/skills、anthropics/skills	比社区来源更宽松的策略
community	其他所有内容（skills.sh、well-known 端点、自定义 GitHub 仓库、大多数市场）	非危险发现可用 --force 覆盖；dangerous 判定保持阻止

更新生命周期

Hub 现在追踪足够的溯源信息来重新检查已安装技能的上游副本：

hermes skills check          # 报告哪些已安装的 Hub 技能在上游发生了变化
hermes skills update         # 仅重新安装有可用更新的技能
hermes skills update react   # 更新一个特定的已安装 Hub 技能

这使用存储的来源标识符加上当前上游包内容哈希来检测漂移。

GitHub 速率限制

技能 Hub 操作使用 GitHub API，未认证用户的速率限制为每小时 60 次请求。如果在安装或搜索期间看到速率限制错误，在你的 .env 文件中设置 GITHUB_TOKEN 可将限制提高到每小时 5,000 次请求。当发生这种情况时，错误信息中包含可操作的提示。

发布自定义技能 tap

如果你想共享一组精选技能——对你的团队、组织或公开——你可以将它们发布为 tap：其他 Hermes 用户使用 hermes skills tap add <owner/repo> 添加的 GitHub 仓库。无需服务器，无需注册表注册，无需发布管道。只需一个 SKILL.md 文件目录。

仓库布局

tap 是任何 GitHub 仓库（公开或私有——私有需要 GITHUB_TOKEN），按如下方式布局：

owner/repo
├── skills/                       # 默认路径；每个 tap 可配置
│   ├── my-workflow/
│   │   ├── SKILL.md              # 必须
│   │   ├── references/           # 可选辅助文件
│   │   ├── templates/
│   │   └── scripts/
│   ├── another-skill/
│   │   └── SKILL.md
│   └── third-skill/
│       └── SKILL.md
└── README.md                     # 可选但有帮助

规则：

• 每个技能位于 tap 根路径（默认 skills/）下自己的目录中。
• 目录名成为技能的安装 slug。
• 每个技能目录必须包含带有标准 SKILL.md frontmatter 的 SKILL.md（name、description，以及可选的 metadata.hermes.tags、version、author、platforms、metadata.hermes.config）。
• 如 references/、templates/、scripts/、assets/ 等子目录在安装时与 SKILL.md 一起下载。
• 目录名以 . 或 _ 开头的技能被忽略。

Hermes 通过列出 tap 路径的每个子目录并探测每个目录中的 SKILL.md 来发现技能。

最小 tap 示例

my-org/hermes-skills
└── skills/
    └── deploy-runbook/
        └── SKILL.md

skills/deploy-runbook/SKILL.md：

---
name: deploy-runbook
description: Our deployment runbook — services, rollback, Slack channels
version: 1.0.0
author: My Org Platform Team
metadata:
  hermes:
    tags: [deployment, runbook, internal]
---

# Deploy Runbook

Step 1: ...

将其推送到 GitHub 后，任何 Hermes 用户都可以订阅并安装：

hermes skills tap add my-org/hermes-skills
hermes skills search deploy
hermes skills install my-org/hermes-skills/deploy-runbook

非默认路径

如果你的技能不在 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 的有效路径。

直接安装单个技能（不添加 tap）

用户也可以从任何公开的 GitHub 仓库安装单个技能，无需将整个仓库添加为 tap：

hermes skills install owner/repo/skills/my-workflow

当你想共享一个技能但不想让用户订阅你的整个注册表时很有用。

tap 的信任级别

新 tap 默认被分配 community 信任。从它们安装的技能经过标准安全扫描，首次安装时显示第三方警告面板。如果你的组织或广泛受信任的来源应该获得更高信任，将其仓库添加到 tools/skills_hub.py 中的 TRUSTED_REPOS（需要 Hermes 核心 PR）。

Tap 管理

hermes skills tap list                                # 显示所有已配置的 tap
hermes skills tap add myorg/skills-repo               # 添加（默认路径：skills/）
hermes skills tap remove myorg/skills-repo            # 删除

在运行中的会话中：

/skills tap list
/skills tap add myorg/skills-repo
/skills tap remove myorg/skills-repo

Tap 存储在 ~/.hermes/.hub/taps.json（按需创建）中。

内置技能更新（hermes skills reset）

Hermes 随仓库中的 skills/ 内置一套内置技能。在安装和每次 hermes update 时，同步过程将这些技能复制到 ~/.hermes/skills/ 并在 ~/.hermes/skills/.bundled_manifest 中记录清单，将每个技能名称映射到同步时的内容哈希（源哈希）。

每次同步时，Hermes 重新计算本地副本的哈希并与源哈希比较：

• 未更改 → 安全拉取上游变更，复制新的内置版本，记录新的源哈希。
• 已更改 → 视为用户修改，永远跳过，这样你的编辑不会被覆盖。

这种保护很好，但有一个尖锐的边缘情况。如果你编辑了一个内置技能，然后后来想放弃你的修改并通过从 ~/.hermes/hermes-agent/skills/ 粘贴来恢复内置版本，清单中仍持有上次成功同步时的旧源哈希。你新粘贴的内容（当前内置哈希）与那个过时的源哈希不匹配，所以同步继续将其标记为用户修改。

hermes skills reset 是解决这个问题的途径：

# 安全：清除此技能的清单条目。你的当前副本保留，
# 但下次同步会重新以它为基准，这样未来的更新能正常工作。
hermes skills reset google-workspace

# 完全恢复：同时删除你的本地副本并重新复制当前内置版本。
# 当你想要原始上游技能时使用。
hermes skills reset google-workspace --restore

# 非交互式（例如在脚本或 TUI 模式中）——跳过 --restore 确认。
hermes skills reset google-workspace --restore --yes

同样的命令也作为斜杠命令在聊天中工作：

/skills reset google-workspace
/skills reset google-workspace --restore

配置文件

每个配置文件在其自己的 HERMES_HOME 下有自己的 .bundled_manifest，所以 hermes -p coder skills reset <name> 只影响该配置文件。

斜杠命令（在聊天中）

所有相同的命令都可以用 /skills 使用：

/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

官方可选技能仍然使用如 official/security/1password 和 official/migration/openclaw-migration 这样的标识符。