跳到主要内容

创建技能

技能是向 Hermes Agent 添加新功能的首选方式。相比工具，技能更易于创建，无需修改代理代码，并且可以与社区共享。

应该创建技能还是工具？​

当满足以下条件时，请创建一个 技能：

  • 功能可以通过指令 + shell 命令 + 现有工具来表达
  • 包装了一个外部 CLI 或 API，代理可通过 terminal 或 web_extract 调用
  • 不需要在代理中内嵌自定义的 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/
└── ...

SKILL.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_toolsets当任意列出的工具集 不可用 时，该技能被 隐藏
requires_tools当任意列出的工具 不可用 时，该技能被 隐藏
fallback_for_toolsets当任意列出的工具集 可用 时，该技能被 隐藏
fallback_for_tools当任意列出的工具 可用 时，该技能被 隐藏

fallback_for_* 的使用场景： 创建一个备用技能，用于主工具不可用时的替代方案。例如，一个 duckduckgo-search 技能设置 fallback_for_tools: [web_search]，仅在未配置 Web 搜索工具（需要 API 密钥）时显示。

requires_* 的使用场景： 创建一个仅在某些工具存在时才有意义的技能。例如，一个网页抓取工作流技能设置 requires_toolsets: [web]，当 Web 工具被禁用时不会污染提示。

环境变量需求​

技能可以声明其所需的环境变量。当通过 skill_view 加载技能时，其所需变量会自动注册并传入沙箱执行环境（terminal、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。缺少值 不会 将技能从发现中隐藏。相反，Hermes 在本地 CLI 中加载技能时会安全地提示用户输入。

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"]），无需用户额外配置。详情请参见 环境变量传入。

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

配置设置（config.yaml）​

技能可以声明非敏感的配置项，这些设置将存储在 config.yaml 的 skills.config 命名空间下。与存储在 .env 中的环境变量（密钥）不同，配置项用于路径、偏好设置等非敏感值。

metadata:
  hermes:
    config:
      - key: wiki.path
        description: Path to the LLM Wiki knowledge base directory
        default: "~/wiki"
        prompt: Wiki directory path
      - key: wiki.domain
        description: Domain the wiki covers
        default: ""
        prompt: Wiki domain (e.g., AI/ML research)

每项条目支持：

  • key（必需）—— 设置的点路径（例如 wiki.path）
  • description（必需）—— 说明该设置控制的内容
  • default（可选）—— 用户未配置时的默认值
  • prompt（可选）—— 在执行 hermes config migrate 时显示的提示文本；若未提供则回退到 description

工作原理：

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

    skills:
      config:
        wiki:
          path: ~/my-research

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

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

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

    代理在无需自行读取 config.yaml 的情况下即可看到已配置的值。

  4. 手动设置：用户也可以直接设置值：

    hermes config set skills.config.wiki.path ~/my-wiki
何时使用哪种方式

使用 required_environment_variables 来处理 API 密钥、令牌等敏感信息（存储在 ~/.hermes/.env 中，不会显示给模型）。使用 config 来处理路径、偏好设置和非敏感配置（存储在 config.yaml 中，可在 config show 中查看）。

凭据文件要求（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 以获取同时使用两者的完整示例。

技能编写指南​

无外部依赖​

优先使用标准库 Python、curl 和现有的 Hermes 工具（如 web_extract、terminal、read_file）。如果必须引入依赖，请在技能文档中说明安装步骤。

渐进式披露​

将最常见的工作流放在最前面。边缘情况和高级用法置于底部。这有助于降低常见任务的 token 使用量。

包含辅助脚本​

对于 XML/JSON 解析或复杂逻辑，应在 scripts/ 目录中包含辅助脚本——不要期望 LLM 每次都内联编写解析器。

进行测试​

运行该技能并验证代理是否正确遵循了指令：

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

技能应放置在何处？​

捆绑技能（位于 skills/ 中）随每个 Hermes 安装一起提供。它们应具有对大多数用户都广泛有用的特性：

  • 文档处理、网络研究、常见开发工作流、系统管理
  • 被广泛人群频繁使用

如果你的技能是官方的且有用，但并非普遍需要（例如付费服务集成、重型依赖），请将其放入 optional-skills/ —— 它会随仓库一起发布，可通过 hermes skills browse 发现（标记为“官方”），并以内置信任方式安装。

如果你的技能是专业化的、社区贡献的或小众的，更适合发布到 技能中心（Skills Hub） —— 上传至注册表，并通过 hermes skills install 共享。

发布技能​

发布到技能中心​

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

发布到自定义仓库​

将你的仓库添加为一个 tap：

hermes skills tap add owner/repo

用户随后即可从你的仓库中搜索并安装技能。

安全扫描​

所有通过技能中心安装的技能都会经过安全扫描，检查以下内容：

  • 数据外泄模式
  • 提示注入尝试
  • 破坏性命令
  • Shell 注入

信任等级：

  • builtin —— 随 Hermes 一起发布（始终受信任）
  • official —— 来自仓库中的 optional-skills/（内置信任，无第三方警告）
  • trusted —— 来自 openai/skills、anthropics/skills
  • community —— 非危险发现可使用 --force 覆盖；危险判定仍被阻止

Hermes 现在可从多个外部发现模型中消费第三方技能：

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

如果你希望你的技能在无需 GitHub 特定安装器的情况下也能被发现，建议除了在仓库或市场中发布外，还提供一个知名端点。