跳到主要内容

创建技能

技能是为 Hermes Agent 添加新功能的首选方式。它们比工具更容易创建，不需要对代理进行代码更改，并且可以与社区共享。

它应该是技能还是工具？​

在以下情况下将其设为技能：

  • 能力可以表达为指令+shell命令+现有工具
  • 它包装了代理可以通过 terminal 或 web_extract 调用的外部 CLI 或 API
  • 不需要将自定义 Python 集成或 API 密钥管理嵌入到代理中
  • 示例：arXiv 搜索、git 工作流程、Docker 管理、PDF 处理、通过 CLI 工具发送电子邮件

在以下情况下将其设为工具：

  • 它需要与 API 密钥、身份验证流程或多组件配置进行端到端集成
  • 它需要每次都必须精确执行的自定义处理逻辑
  • 它处理二进制数据、流或实时事件
  • 示例：浏览器自动化、TTS、视觉分析

技能目录结构​

捆绑技能位于按类别组织的 skills/ 中。官方可选技能在optional-skills/中使用相同的结构：

skills/
├── research/
│   └── arxiv/
│       ├── SKILL.md              # Required: main instructions
│       └── scripts/              # Optional: helper scripts
│           └── search_arxiv.py
├── productivity/
│   └── ocr-and-documents/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
└── ...

技能.md 格式​

---
name: my-skill
description: Brief description (shown in skill search results)
version: 1.0.0
author: Your Name
license: MIT
platforms: [macos, linux]          # Optional — restrict to specific OS platforms
                                   #   Valid: macos, linux, windows
                                   #   Omit to load on all platforms (default)
metadata:
  hermes:
    tags: [Category, Subcategory, Keywords]
    related_skills: [other-skill-name]
    requires_toolsets: [web]            # Optional — only show when these toolsets are active
    requires_tools: [web_search]        # Optional — only show when these tools are available
    fallback_for_toolsets: [browser]    # Optional — hide when these toolsets are active
    fallback_for_tools: [browser_navigate]  # Optional — hide when these tools exist
    config:                              # Optional — config.yaml settings the skill needs
      - key: my.setting
        description: "What this setting controls"
        default: "sensible-default"
        prompt: "Display prompt for setup"
required_environment_variables:          # Optional — env vars the skill needs
  - name: MY_API_KEY
    prompt: "Enter your API key"
    help: "Get one at https://example.com"
    required_for: "API access"
---

# Skill Title

Brief intro.

## When to Use
Trigger conditions — when should the agent load this skill?

## Quick Reference
Table of common commands or API calls.

## Procedure
Step-by-step instructions the agent follows.

## Pitfalls
Known failure modes and how to handle them.

## Verification
How the agent confirms it worked.

平台特定技能​

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

platforms: [macos]            # macOS only (e.g., iMessage, Apple Reminders)
platforms: [macos, linux]     # macOS and Linux
platforms: [windows]          # Windows only

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

有条件的技能激活​

技能可以声明对特定工具或工具集的依赖关系。这控制技能是否出现在给定会话的系统提示中。

metadata:
  hermes:
    requires_toolsets: [web]           # Hide if the web toolset is NOT active
    requires_tools: [web_search]       # Hide if web_search tool is NOT available
    fallback_for_toolsets: [browser]   # Hide if the browser toolset IS active
    fallback_for_tools: [browser_navigate]  # Hide if browser_navigate IS available
领域行为
requires_toolsetsrequires_toolsets当任何列出的工具集不可用时，技能就隐藏
requires_toolsrequires_tools当任何列出的工具不可用时，技能就隐藏
fallback_for_toolsetsfallback_for_toolsets当任何列出的工具集可用时，技能就会隐藏**
fallback_for_toolsfallback_for_tools当任何列出的工具可用时，技能就隐藏**

fallback_for_* 的用例： 创建一项技能，在主要工具不可用时作为解决方法。例如，带有 fallback_for_tools: [web_search] 的 duckduckgo-search 技能仅在未配置网络搜索工具（需要 API 密钥）时显示。

requires_* 的用例： 创建一项仅在存在某些工具时才有意义的技能。例如，当禁用 Web 工具时，具有 requires_toolsets: [web] 的 Web 抓取工作流程技能不会使提示混乱。

环境变量要求​

技能可以声明自己需要的环境变量。当通过 skill_view 加载技能时，其所需的变量会自动注册以传递到沙盒执行环境（终端、execute_code）。

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: "Tenor API key"               # Shown when prompting user
    help: "Get your key at https://tenor.com"  # Help text or URL
    required_for: "GIF search functionality"   # What needs this var

每个条目支持：

  • name (必需) — 环境变量名称
  • prompt (可选) — 询问用户值时的提示文本
  • help (可选) — 用于获取值的帮助文本或 URL
  • required_for (可选) — 描述哪个功能需要此变量

用户还可以在 config.yaml 中手动配置直通变量：

terminal:
  env_passthrough:
    - MY_CUSTOM_VAR
    - ANOTHER_VAR

请参阅 skills/apple/ 了解仅限 macOS 的技能示例。

加载时的安全设置​

当技能需要 API 密钥或令牌时，请使用 required_environment_variables。缺失值不会隐藏技能，使其不被发现。相反，当技能加载到本地 CLI 中时，Hermes 会安全地提示它们。

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 绝不会向模型暴露原始秘密值。网关和消息会话显示本地设置指南，而不是在带内收集机密。

:::提示沙箱穿越 加载技能后，任何声明的 required_environment_variables 设置都会自动传递到 execute_code 和 terminal 沙箱 - 包括 Docker 和 Modal 等远程后端。您的技能脚本可以访问 $TENOR_API_KEY （或 Python 中的 os.environ["TENOR_API_KEY"]），而无需用户进行任何额外配置。有关详细信息，请参阅 Environment Variable Passthrough。 :::

旧版 prerequisites.env_vars 仍然支持作为向后兼容的别名。

配置设置 (config.yaml)​

技能可以声明存储在 skills.config 命名空间下的 config.yaml 中的非秘密设置。与环境变量（存储在 .env 中的秘密）不同，配置设置用于路径、首选项和其他非敏感值。

metadata:
  hermes:
    config:
      - key: myplugin.path
        description: Path to the plugin data directory
        default: "~/myplugin-data"
        prompt: Plugin data directory path
      - key: myplugin.domain
        description: Domain the plugin operates on
        default: ""
        prompt: Plugin domain (e.g., AI/ML research)

每个条目支持：

  • key（必需）— 设置的点路径（例如 myplugin.path）
  • description（必需）— 解释设置控制的内容
  • default (可选) — 如果用户未配置它，则为默认值
  • prompt (可选) — hermes config migrate 期间显示的提示文本；回退到 description

它是如何工作的：

  1. 存储： 值写入到 skills.config.<key> 下的 config.yaml 中：

    skills:
      config:
        myplugin:
          path: ~/my-data

  2. 发现： hermes config migrate 扫描所有已启用的技能，查找未配置的设置，并提示用户。设置也显示在“技能设置”下的 hermes config show 中。

  3. 运行时注入： 当技能加载时，其配置值将被解析并附加到技能消息中：

    [Skill config (from ~/.hermes/config.yaml):
      myplugin.path = /home/user/my-data
    ]

代理无需读取 config.yaml 本身即可查看配置的值。

  1. 手动设置： 用户也可以直接设置值： 
    hermes config set skills.config.myplugin.path ~/my-data

:::提示 何时使用哪个 使用 required_environment_variables 作为 API 密钥、令牌和其他 秘密（存储在 ~/.hermes/.env 中，从未向模型显示）。将 config 用于路径、首选项和非敏感设置（存储在 config.yaml 中，在配置显示中可见）。 :::

凭证文件要求（OAuth 令牌等）​

使用 OAuth 或基于文件的凭据的技能可以声明需要安装到远程沙箱中的文件。这适用于存储为 文件（不是环境变量）的凭据 — 通常是由安装脚本生成的 OAuth 令牌文件。

required_credential_files:
  - path: google_token.json
    description: Google OAuth2 token (created by setup script)
  - path: google_client_secret.json
    description: Google OAuth2 client credentials

每个条目支持：

  • path（必需）— 相对于 ~/.hermes/ 的文件路径
  • description (可选) — 解释文件是什么以及它是如何创建的

加载时，Hermes 会检查这些文件是否存在。丢失文件会触发 setup_needed。现有文件会自动：

  • 作为只读绑定安装安装到 Docker 容器中
  • 同步到 Modal 沙箱（在创建时+每个命令之前，因此会话中 OAuth 可以工作）
  • 可在 本地 后端使用，无需任何特殊处理

:::提示 何时使用哪个 使用 required_environment_variables 表示简单的 API 密钥和令牌（存储在 ~/.hermes/.env 中的字符串）。将 required_credential_files 用于 OAuth 令牌文件、客户端密钥、服务帐户 JSON、证书或磁盘上文件形式的任何凭据。 :::

请参阅 skills/productivity/google-workspace/SKILL.md 以获取使用两者的完整示例。

技能指南​

无外部依赖​

更喜欢 stdlib Python、curl 和现有的 Hermes 工具（web_extract、terminal、read_file）。如果需要依赖项，请记录技能中的安装步骤。

渐进式披露​

将最常见的工作流程放在第一位。边缘案例和高级用法位于底部。这使得常见任务的令牌使用量保持在较低水平。

包含辅助脚本​

对于 XML/JSON 解析或复杂逻辑，请在 scripts/ 中包含帮助程序脚本 - 不要期望 LLM 每次都内联编写解析器。

引用 SKILL.md 中的捆绑脚本​

加载技能时，激活消息会将绝对技能目录公开为 [Skill directory: /abs/path] ，并替换 SKILL.md 正文中任意位置的两个模板标记：

代币替换为
${HERMES_SKILL_DIR}${HERMES_SKILL_DIR}技能目录的绝对路径
${HERMES_SESSION_ID}${HERMES_SESSION_ID}活动会话 ID（如果没有会话，则保留在原处）

因此 SKILL.md 可以告诉代理直接运行捆绑脚本：

To analyse the input, run:

    node ${HERMES_SKILL_DIR}/scripts/analyse.js <input>

代理看到替换的绝对路径，并使用准备运行的命令调用 terminal 工具 - 没有路径数学，没有额外的 skill_view 往返。使用 config.yaml 中的 skills.template_vars: false 禁用全局替换。

内联 shell 片段（选择加入）​

技能还可以在 SKILL.md 正文中嵌入编写为“ !cmd ”的内联 shell 片段。启用后，每个片段的标准输出都会在代理读取消息之前内联到消息中，因此技能可以注入动态上下文：

Current date: !`date -u +%Y-%m-%d`
Git branch: !`git -C ${HERMES_SKILL_DIR} rev-parse --abbrev-ref HEAD`

默认情况下此功能处于关闭状态 - SKILL.md 中的任何片段都无需批准即可在主机上运行，​​因此仅针对您信任的技能源启用它：

# config.yaml
skills:
  inline_shell: true
  inline_shell_timeout: 10   # seconds per snippet

代码片段以技能目录作为工作目录运行，输出上限为 4000 个字符。失败（超时、非零退出）显示为短 [inline-shell error: ...] 标记，而不是破坏整个技能。

测试一下​

运行技能并验证代理是否正确遵循说明：

hermes chat --toolsets skills -q "Use the X skill to do Y"

技能应该放在哪里？​

每个 Hermes 安装都会附带捆绑技能（在 skills/ 中）。它们应该对大多数用户广泛有用：

  • 文档处理、网络研究、通用开发工作流程、系统管理
  • 广泛的人群经常使用

如果您的技能是官方的且有用但不是普遍需要的（例如，付费服务集成、重量级依赖项），请将其放入 optional-skills/ — 它随存储库一起提供，可以通过 hermes skills browse （标记为“官方”）发现，并通过内置信任进行安装。

如果您的技能是专门的、社区贡献的或利基的，那么它更适合技能中心 - 将其上传到注册表并通过 hermes skills install 共享。

出版技巧​

前往技能中心​

hermes skills publish skills/my-skill --to github --repo owner/repo

到自定义存储库​

添加您的存储库作为水龙头：

hermes skills tap add owner/repo

然后，用户可以从您的存储库中搜索并安装。

安全扫描​

所有集线器安装的技能都会经过安全扫描仪，检查：

  • 数据泄露模式
  • 及时尝试注射
  • 破坏性命令
  • 外壳注射

信任级别：

  • builtin — 随 Hermes 一起提供（始终值得信赖）
  • official — 来自存储库中的 optional-skills/ （内置信任，无第三方警告）
  • trusted — 来自 openai/skills、anthropics/skills
  • community — 非危险结果可以用 --force 覆盖； dangerous 判决仍被阻止

Hermes 现在可以使用来自多个外部发现模型的第三方技能：

  • 直接 GitHub 标识符（例如 openai/skills/k8s）
  • skills.sh 标识符（例如 skills-sh/vercel-labs/json-render/json-render-react）
  • 从 /.well-known/skills/index.json 提供服务的知名端点

如果您希望在没有特定于 GitHub 的安装程序的情况下发现您的技能，除了在存储库或市场中发布它们之外，还可以考虑从众所周知的端点提供它们。