创建 Skills

Skills 是向 Hermes Agent 添加新能力的首选方式。它们比 tools 更容易创建，不需要修改 agent 代码，并且可以与社区共享。

它应该是 Skill 还是 Tool？

当满足以下情况时，将其做成 Skill：

• 能力可以表达为“说明 + shell 命令 + 现有工具”
• 它封装了 agent 可以通过 terminal 或 web_extract 调用的外部 CLI 或 API
• 它不需要将自定义 Python 集成或 API key 管理内置到 agent 中
• 示例：arXiv 搜索、git 工作流、Docker 管理、PDF 处理、通过 CLI 工具发送邮件

当满足以下情况时，将其做成 Tool：

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

Skill 目录结构

Bundled skills 位于 skills/ 中，并按类别组织。官方 optional skills 在 optional-skills/ 中使用相同结构：

skills/
├── research/
│   └── arxiv/
│       ├── SKILL.md              # 必需：主要说明
│       └── scripts/              # 可选：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]          # 可选 — 限制到特定 OS platforms
                                   #   有效值：macos, linux, windows
                                   #   省略则在所有 platforms 上加载（默认）
metadata:
  hermes:
    tags: [Category, Subcategory, Keywords]
    related_skills: [other-skill-name]
    requires_toolsets: [web]            # 可选 — 只有这些 toolsets active 时才显示
    requires_tools: [web_search]        # 可选 — 只有这些 tools 可用时才显示
    fallback_for_toolsets: [browser]    # 可选 — 当这些 toolsets active 时隐藏
    fallback_for_tools: [browser_navigate]  # 可选 — 当这些 tools 存在时隐藏
    config:                              # 可选 — skill 需要的 config.yaml settings
      - key: my.setting
        description: "What this setting controls"
        default: "sensible-default"
        prompt: "Display prompt for setup"
required_environment_variables:          # 可选 — skill 需要的 env vars
  - 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 — agent 什么时候应该加载此 skill？

## Quick Reference
常用 commands 或 API calls 的表格。

## Procedure
agent 遵循的分步说明。

## Pitfalls
已知 failure modes 以及如何处理它们。

## Verification
agent 如何确认它已工作。

Platform-Specific Skills

Skills 可以使用 platforms 字段将自己限制到特定操作系统：

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

设置后，在不兼容的平台上，该 skill 会自动从 system prompt、skills_list() 和 slash commands 中隐藏。如果省略或为空，该 skill 会在所有 platforms 上加载（向后兼容）。

Conditional Skill Activation

Skills 可以声明对特定 tools 或 toolsets 的依赖。这控制该 skill 是否会在给定 session 的 system prompt 中出现。

metadata:
  hermes:
    requires_toolsets: [web]           # 如果 web toolset 未 active，则隐藏
    requires_tools: [web_search]       # 如果 web_search tool 不可用，则隐藏
    fallback_for_toolsets: [browser]   # 如果 browser toolset active，则隐藏
    fallback_for_tools: [browser_navigate]  # 如果 browser_navigate 可用，则隐藏

Field	Behavior
requires_toolsets	当任何列出的 toolset 不可用时，Skill 会被隐藏
requires_tools	当任何列出的 tool 不可用时，Skill 会被隐藏
fallback_for_toolsets	当任何列出的 toolset 可用时，Skill 会被隐藏
fallback_for_tools	当任何列出的 tool 可用时，Skill 会被隐藏

fallback_for_* 的使用场景：创建一个在 primary tool 不可用时作为 workaround 的 skill。例如，一个带有 fallback_for_tools: [web_search] 的 duckduckgo-search skill，只会在需要 API key 的 web search tool 未配置时显示。

requires_* 的使用场景：创建一个只有在某些 tools 存在时才有意义的 skill。例如，一个带有 requires_toolsets: [web] 的 web scraping workflow skill，在 web tools disabled 时不会干扰 prompt。

Environment Variable Requirements

Skills 可以声明它们需要的环境变量。当一个 skill 通过 skill_view 加载时，它所需的 vars 会自动注册，以便透传到 sandboxed execution environments（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"   # 哪个功能需要此 var

每个 entry 支持：

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

用户也可以在 config.yaml 中手动配置 passthrough variables：

terminal:
  env_passthrough:
    - MY_CUSTOM_VAR
    - ANOTHER_VAR

示例请参见 skills/apple/，其中包含 macOS-only skills。

加载时的安全设置

当 skill 需要 API key 或 token 时，请使用 required_environment_variables。缺失的值不会让 skill 从 discovery 中隐藏。相反，当 skill 在本地 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

用户可以跳过设置并继续加载 skill。Hermes 永远不会将原始 secret 值暴露给 model。Gateway 和 messaging sessions 会显示本地设置指导，而不是在带内收集 secrets。

Sandbox Passthrough

当你的 skill 被加载时，任何已声明且已设置的 required_environment_variables 都会自动透传到 execute_code 和 terminal sandboxes —— 包括 Docker 和 Modal 这样的远程 backends。你的 skill 脚本可以访问 $TENOR_API_KEY（或 Python 中的 os.environ["TENOR_API_KEY"]），无需用户额外配置任何内容。详情请参见 Environment Variable Passthrough。

旧版 prerequisites.env_vars 仍作为向后兼容 alias 受支持。

Config Settings（config.yaml）

Skills 可以声明非 secret 设置，这些设置会存储在 config.yaml 的 skills.config namespace 下。与环境变量（secrets，存储在 .env 中）不同，config settings 用于 paths、preferences 和其他非敏感值。

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)

每个 entry 支持：

• key（必需）—— setting 的 dotpath（例如 myplugin.path）
• description（必需）—— 说明该 setting 控制什么
• default（可选）—— 如果用户没有配置，则使用默认值
• prompt（可选）—— 在 hermes config migrate 期间显示的提示文本；fallback 到 description

工作方式：

1. Storage：值会写入 config.yaml 的 skills.config.<key> 下：

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

2. Discovery：hermes config migrate 会扫描所有已启用 skills，找到尚未配置的 settings，并提示用户。Settings 也会出现在 hermes config show 的 “Skill Settings” 下。

3. Runtime injection：当 skill 加载时，其 config values 会被解析，并附加到 skill message 中：

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

agent 可以看到已配置的值，而不需要自己读取 config.yaml。

4. Manual setup：用户也可以直接设置值：

hermes config set skills.config.myplugin.path ~/my-data

何时使用哪一个

对于 API keys、tokens 和其他 secrets，请使用 required_environment_variables（存储在 ~/.hermes/.env 中，永远不会显示给 model）。对于 paths、preferences 和非敏感 settings，请使用 config（存储在 config.yaml 中，在 config show 中可见）。

Credential File Requirements（OAuth tokens 等）

使用 OAuth 或基于文件的 credentials 的 skills 可以声明需要挂载到远程 sandboxes 中的文件。这用于以文件形式存储的 credentials（不是 env vars）—— 通常是由 setup script 生成的 OAuth token files。

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

每个 entry 支持：

• path（必需）—— 相对于 ~/.hermes/ 的文件路径
• description（可选）—— 说明该文件是什么以及如何创建

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

• 以只读 bind mounts 挂载到 Docker containers 中
• 同步到 Modal sandboxes（在创建时 + 每次 command 前，因此 mid-session OAuth 可用）
• 在 local backend 上无需任何特殊处理即可使用

何时使用哪一个

对于简单 API keys 和 tokens（存储在 ~/.hermes/.env 中的字符串），请使用 required_environment_variables。对于 OAuth token files、client secrets、service account JSON、certificates，或任何磁盘上的 credential 文件，请使用 required_credential_files。

完整示例请参见 skills/productivity/google-workspace/SKILL.md，其中同时使用了两者。

Skill Guidelines

No External Dependencies

优先使用 stdlib Python、curl 和现有 Hermes tools（web_extract、terminal、read_file）。如果需要依赖，请在 skill 中记录安装步骤。

Progressive Disclosure

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

Include Helper Scripts

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

从 SKILL.md 引用 bundled scripts

当 skill 加载时，activation message 会将绝对 skill 目录暴露为 [Skill directory: /abs/path]，并且还会替换 SKILL.md body 中任意位置的两个模板 tokens：

Token	Replaced with
${HERMES_SKILL_DIR}	skill 目录的绝对路径
${HERMES_SESSION_ID}	active session id（如果没有 session，则保留原样）

因此，SKILL.md 可以直接告诉 agent 运行 bundled script：

To analyse the input, run:

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

agent 会看到替换后的绝对路径，并使用 terminal tool 调用一个可直接运行的 command —— 不需要路径计算，不需要额外的 skill_view round-trip。可通过在 config.yaml 中设置 skills.template_vars: false 全局禁用替换。

Inline shell snippets（选择启用）

Skills 也可以在 SKILL.md body 中嵌入写作 !`cmd` 的 inline shell snippets。启用后，每个 snippet 的 stdout 会在 agent 读取之前被内联到 message 中，因此 skills 可以注入动态上下文：

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

默认关闭 —— SKILL.md 中的任何 snippet 都会在 host 上无需审批地运行，因此只应对你信任的 skill sources 启用它：

config.yaml

skills:
  inline_shell: true
  inline_shell_timeout: 10   # 每个 snippet 的秒数

Snippets 会以 skill directory 作为 working directory 运行，输出限制为 4000 个字符。失败（timeouts、非零退出）会显示为简短的 [inline-shell error: ...] 标记，而不会破坏整个 skill。

测试它

运行 skill 并验证 agent 是否正确遵循说明：

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

Skill 应该放在哪里？

Bundled skills（位于 skills/ 中）会随每个 Hermes 安装一起发布。它们应该对大多数用户广泛有用：

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

如果你的 skill 是官方的且有用，但不是普遍需要的（例如付费服务集成、重量级依赖），请将其放入 optional-skills/ —— 它会随 repo 发布，可通过 hermes skills browse 发现（标记为 “official”），并以 builtin trust 安装。

如果你的 skill 是专门的、社区贡献的或小众的，它更适合 Skills Hub —— 将其上传到 registry，并通过 hermes skills install 分享。

发布 Skills

到 Skills Hub

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

到自定义仓库

将你的 repo 添加为 tap：

hermes skills tap add owner/repo

用户随后可以从你的 repository 中搜索和安装。

Security Scanning

所有通过 hub 安装的 skills 都会经过安全扫描器，检查：

• 数据外泄模式
• Prompt injection attempts
• 破坏性 commands
• Shell injection

Trust levels：

• builtin —— 随 Hermes 发布（始终受信任）
• official —— 来自 repo 中的 optional-skills/（builtin trust，无第三方警告）
• trusted —— 来自 openai/skills、anthropics/skills、huggingface/skills
• community —— 非危险 findings 可以用 --force 覆盖；危险 verdicts 仍会被阻止

Hermes 现在可以从多个外部 discovery models 消费第三方 skills：

• direct GitHub identifiers（例如 openai/skills/k8s）
• skills.sh identifiers（例如 skills-sh/vercel-labs/json-render/json-render-react）
• 从 /.well-known/skills/index.json 提供服务的 well-known endpoints

如果你希望你的 skills 在没有 GitHub-specific installer 的情况下可被发现，请考虑从 well-known endpoint 提供它们，此外也可以将它们发布到 repo 或 marketplace。