Skip to main content

创建技能

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

本页说明如何按 Hermes 当前的技能体系来编写和组织技能，包括：

  • 什么时候应该做技能，而不是做工具
  • SKILL.md 的推荐结构
  • 平台限制、条件激活和环境变量声明
  • 配置项与凭证文件的处理方式
  • 官方技能与可选技能的放置位置

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

创建技能 当：

  • 功能可以通过指令 + 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 技能，仅在未配置网络搜索工具（需 API 密钥）时显示。

requires_* 的使用场景： 创建仅在某些工具存在时才有意义的技能。例如，一个网页抓取工作流技能，带有 requires_toolsets: [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（可选）—— 获取该值的帮助文本或链接
  • 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. 运行时注入： 当技能加载时，其配置值会被解析并附加到技能消息中：

    [技能配置（来自 ~/.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/ 中包含辅助脚本——不要期望大模型每次都内联编写解析器。

进行测试​

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

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 覆盖；dangerous 的判定仍被阻止

Hermes 现已支持从多个外部发现模型消费第三方技能：

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

若您希望技能在无需 GitHub 特定安装器的情况下也能被发现，建议除在仓库或市场发布外，同时通过知名端点提供服务。