创建技能

技能是为 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              # 必需：主要指令
│       └── scripts/              # 可选：辅助脚本
│           └── search_arxiv.py
├── productivity/
│   └── ocr-and-documents/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
└── ...

SKILL.md 格式

---
name: my-skill
description: 简要描述（显示在技能搜索结果中）
version: 1.0.0
author: 你的名字
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]  # 可选 — 当这些工具存在时隐藏
required_environment_variables:          # 可选 — 技能需要的环境变量
  - name: MY_API_KEY
    prompt: "输入你的 API 密钥"
    help: "在 https://example.com 获取"
    required_for: "API 访问"
---

# 技能标题

简要介绍。

## 何时使用
触发条件 — 代理应该在何时加载此技能？

## 快速参考
常用命令或 API 调用的表格。

## 步骤
代理遵循的分步指令。

## 常见问题
已知的失败模式及处理方法。

## 验证
代理如何确认操作成功。

平台特定技能

技能可以使用 platforms 字段限制自己只能在特定的操作系统上运行：

platforms: [macos]            # 仅限 macOS（例如，iMessage、Apple 提醒事项）
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 技能，仅在 web 搜索工具（需要 API 密钥）未配置时显示。

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

环境变量要求

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

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: "Tenor API 密钥"               # 提示用户时显示
    help: "在 https://tenor.com 获取你的密钥"  # 帮助文本或 URL
    required_for: "GIF 搜索功能"   # 哪个功能需要此变量

每个条目支持：

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 密钥
    help: 从 https://developers.google.com/tenor 获取密钥
    required_for: 完整功能

用户可以跳过设置并继续加载技能。Hermes 永远不会向模型暴露原始密钥值。网关和消息会话会显示本地设置指南，而不是在会话中收集密钥。

沙盒传递

当你的技能被加载时，任何已设置的 required_environment_variables 都会自动传递到 execute_code 和 terminal 沙盒中 — 包括 Docker 和 Modal 等远程后端。你的技能的脚本可以访问 $TENOR_API_KEY（或在 Python 中访问 os.environ["TENOR_API_KEY"]），而无需用户配置任何额外内容。详情请参阅环境变量传递。

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

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

使用 OAuth 或基于文件的凭证的技能可以声明需要挂载到远程沙盒中的文件。这适用于存储为文件（而非环境变量）的凭证 — 通常是由设置脚本生成的 OAuth 令牌文件。

required_credential_files:
  - path: google_token.json
    description: Google OAuth2 令牌（由设置脚本创建）
  - path: google_client_secret.json
    description: Google OAuth2 客户端凭证

每个条目支持：

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）。如果需要依赖项，请在技能中记录安装步骤。

渐进式披露

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

包含辅助脚本

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

测试它

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

hermes chat --toolsets skills -q "使用 X 技能来做 Y"

技能应该放在哪里？

捆绑技能（在 skills/ 中）随每个 Hermes 安装包一起发布。它们应该对大多数用户普遍有用：

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

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

如果你的技能是专业化的、社区贡献的或小众的，它更适合放在技能中心 — 将其上传到注册表并通过 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 的安装程序即可被发现，除了在仓库或市场中发布外，还可以考虑从知名端点提供服务。

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

技能目录结构​

SKILL.md 格式​

平台特定技能​

条件性技能激活​

环境变量要求​

加载时的安全设置​

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

技能指南​

无外部依赖​

渐进式披露​

包含辅助脚本​

测试它​

技能应该放在哪里？​

发布技能​

发布到技能中心​

发布到自定义仓库​

安全扫描​