跳到主要内容

创建技能

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

应该做成技能还是工具？​

以下情况做成技能：

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

以下情况做成工具：

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

技能目录结构​

内置技能位于按分类组织的 skills/ 目录中。官方可选技能在 optional-skills/ 中使用相同结构：

skills/
├── research/
│   └── arxiv/
│       ├── SKILL.md              # 必需：主要指令
│       └── scripts/              # 可选：辅助脚本
│           └── search_arxiv.py
├── productivity/
│   └── ocr-and-documents/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
└── ...

SKILL.md 格式​

---
name: my-skill
description: 简短描述（显示在技能搜索结果中）
version: 1.0.0
author: Your Name
license: MIT
platforms: [macos, linux]          # 可选——限制到特定操作系统平台
                                   #   有效值：macos, linux, windows
                                   #   省略则在所有平台上加载（默认）
metadata:
  hermes:
    tags: [Category, Subcategory, Keywords]
    related_skills: [other-skill-name]
    requires_toolsets: [web]            # 可选——仅在这些工具集激活时显示
    requires_tools: [web_search]        # 可选——仅在这些工具可用时显示
    fallback_for_toolsets: [browser]    # 可选——当这些工具集激活时隐藏
    fallback_for_tools: [browser_navigate]  # 可选——当这些工具存在时隐藏
    config:                              # 可选——技能所需的 config.yaml 设置
      - key: my.setting
        description: "此设置控制的内容"
        default: "sensible-default"
        prompt: "设置时显示的提示"
required_environment_variables:          # 可选——技能所需的环境变量
  - name: MY_API_KEY
    prompt: "输入您的 API 密钥"
    help: "在 https://example.com 获取"
    required_for: "API 访问"
---

# 技能标题

简短介绍。

## When to Use
触发条件——Agent 何时应加载此技能？

## Quick Reference
常用命令或 API 调用的对照表。

## Procedure
Agent 遵循的步骤说明。

## Pitfalls
已知失败模式及处理方法。

## Verification
Agent 如何确认操作成功。

平台专属技能​

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

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

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

条件技能激活​

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

metadata:
  hermes:
    requires_toolsets: [web]           # 若 web 工具集未激活则隐藏
    requires_tools: [web_search]       # 若 web_search 工具不可用则隐藏
    fallback_for_toolsets: [browser]   # 若 browser 工具集已激活则隐藏
    fallback_for_tools: [browser_navigate]  # 若 browser_navigate 可用则隐藏
字段行为
requires_toolsets当任意列出的工具集不可用时，技能被隐藏
requires_tools当任意列出的工具不可用时，技能被隐藏
fallback_for_toolsets当任意列出的工具集可用时，技能被隐藏
fallback_for_tools当任意列出的工具可用时，技能被隐藏

fallback_for_* 的使用场景： 创建主工具不可用时的替代技能。例如，带有 fallback_for_tools: [web_search] 的 duckduckgo-search 技能仅在未配置需要 API 密钥的 web 搜索工具时显示。

requires_* 的使用场景： 创建仅在特定工具存在时才有意义的技能。例如，带有 requires_toolsets: [web] 的网页抓取工作流技能，在 web 工具被禁用时不会出现在提示词中。

环境变量要求​

技能可以声明所需的环境变量。当通过 skill_view 加载技能时，其必需变量会自动注册为透传到沙箱执行环境（terminal、execute_code）的变量。

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: "Tenor API key"               # 提示用户时显示
    help: "Get your key at https://tenor.com"  # 帮助文本或 URL
    required_for: "GIF search functionality"   # 说明哪个功能需要此变量

每个条目支持：

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

用户也可以在 config.yaml 中手动配置透传变量：

terminal:
  env_passthrough:
    - MY_CUSTOM_VAR
    - ANOTHER_VAR

macOS 专属技能示例参见 skills/apple/。

加载时的安全设置​

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

遗留的 prerequisites.env_vars 仍作为向后兼容别名受到支持。

配置设置（config.yaml）​

技能可以声明存储在 config.yaml 的 skills.config 命名空间下的非密钥设置。与环境变量（密钥，存储在 .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. 存储： 值写入 config.yaml 的 skills.config.<key> 下：

    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
    ]

    Agent 无需自己读取 config.yaml 即可看到已配置的值。

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

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

对 API 密钥、令牌和其他密钥使用 required_environment_variables（存储在 ~/.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）
  • 在本地后端无需特殊处理即可访问
何时使用哪种方式

对简单 API 密钥和令牌（存储在 ~/.hermes/.env 中的字符串）使用 required_environment_variables。对 OAuth 令牌文件、客户端密钥、服务账号 JSON、证书或任何磁盘上的凭证文件使用 required_credential_files。

完整示例参见同时使用两者的 skills/productivity/google-workspace/SKILL.md。

技能规范​

无外部依赖​

优先使用标准库 Python、curl 和现有 Hermes 工具（web_extract、terminal、read_file）。如果需要某个依赖，请在技能中记录安装步骤。

渐进式披露​

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

包含辅助脚本​

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

从 SKILL.md 引用内置脚本​

技能加载时，激活消息会将技能目录的绝对路径暴露为 [Skill directory: /abs/path]，同时在 SKILL.md 正文中替换两个模板令牌：

令牌替换为
${HERMES_SKILL_DIR}技能目录的绝对路径
${HERMES_SESSION_ID}当前会话 ID（无会话时原样保留）

因此，SKILL.md 可以指示 Agent 直接运行内置脚本：

To analyse the input, run:

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

Agent 会看到替换后的绝对路径，并使用现成可运行的命令调用 terminal 工具——无需路径运算，无需额外的 skill_view 往返。通过在 config.yaml 中设置 skills.template_vars: false 可全局禁用替换。

内联 Shell 片段（可选启用）​

技能还可以在 SKILL.md 正文中嵌入以 !`cmd` 形式编写的内联 Shell 片段。启用后，每个片段的 stdout 会在 Agent 读取之前内联到消息中，使技能能够注入动态上下文：

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   # 每个片段的秒数

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

测试技能​

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

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

技能应放在哪里？​

内置技能（位于 skills/）随每次 Hermes 安装一起发布，应对大多数用户广泛有用：

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

如果您的技能是官方的且有用但并非普遍需要（例如付费服务集成、重量级依赖），将其放在 optional-skills/ 中——它随仓库发布，可通过 hermes skills browse 发现（标记为"official"），并以内置信任级别安装。

如果您的技能是专业化的、社区贡献的或小众的，更适合放在技能 Hub 中——上传到注册表并通过 hermes skills install 分享。

发布技能​

发布到技能 Hub​

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

发布到自定义仓库​

将您的仓库添加为 tap：

hermes skills tap add owner/repo

用户随后可以从您的仓库中搜索和安装。

安全扫描​

所有从 Hub 安装的技能都会经过安全扫描器检查：

  • 数据泄露模式
  • 提示词注入尝试
  • 破坏性命令
  • 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 专属安装程序即可被发现，除了在仓库或市场发布外，考虑从知名端点提供技能。