hermes教程-创建技能

技能是向 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]  # 可选 — 当这些工具存在时隐藏
    config:                              # 可选 — 技能需要的 config.yaml 设置
      - key: my.setting
        description: "此设置控制的内容"
        default: "sensible-default"
        prompt: "设置提示"
    blueprint:                              # 可选 — 将此技能标记为可运行的自动化
      schedule: "0 9 * * *"              #   cron 表达式 / "every 2h" / ISO 时间戳
      deliver: origin                    #   可选（默认 origin）
      prompt: "每次运行的任务指令"  # 可选
      no_agent: false                    # 可选
required_environment_variables:          # 可选 — 技能需要的环境变量
  - name: MY_API_KEY
    prompt: "输入你的 API 密钥"
    help: "在 https://example.com 获取"
    required_for: "API 访问"
---
## 技能标题

简要介绍。

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

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

## 步骤
代理遵循的逐步说明。

## 陷阱
已知的失败模式及如何处理。

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

平台特定技能

技能可以使用 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 可用则隐藏

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 密钥"               # 提示用户时显示
    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。缺失的值不会将技能从发现中隐藏。相反，当技能在本地 CLI 中加载时，Hermes 会安全地提示输入它们。

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 作为向后兼容的别名仍然受支持。

配置设置（config.yaml）

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

metadata:
  hermes:
    config:
      - key: myplugin.path
        description: 插件数据目录的路径
        default: "~/myplugin-data"
        prompt: 插件数据目录路径
      - key: myplugin.domain
        description: 插件操作的域
        default: ""
        prompt: 插件域（例如 AI/ML 研究）

每个条目支持：

• key（必需）— 设置的点路径（例如 myplugin.path）
• description（必需）— 解释此设置控制的内容
• default（可选）— 如果用户未配置，则使用默认值
• prompt（可选）— 在 hermes config migrate 期间显示的提示文本；回退到 description

工作原理：

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

   yamlCopy

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

2. 发现： hermes config migrate 扫描所有启用的技能，找到未配置的设置并提示用户。设置也会出现在 hermes config show 的“技能设置”下。

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

   textCopy

   [技能配置（来自 ~/.hermes/config.yaml）：
     myplugin.path = /home/user/my-data
   ]

   代理看到配置的值，无需自己读取 config.yaml。

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

   bashCopy

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

提示 — 何时使用哪种

对 API 密钥、令牌和其他秘密使用 required_environment_variables（存储在 ~/.hermes/.env 中，从不向模型显示）。对路径、偏好和非敏感设置使用 config（存储在 config.yaml 中，在配置显示中可见）。

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

技能指南

无外部依赖

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

渐进式披露

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

包含辅助脚本

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

将媒体作为文档传递（[[as_document]]）

如果你的技能生成高分辨率截图、图表或任何有损预览压缩会损害质量的图像——在响应的某处（通常是最后一行）输出字面指令 [[as_document]]。网关会剥离该指令，并将该响应中的每个提取的媒体路径作为可下载的文件附件传递，而不是内联图像气泡。请参阅技能输出和媒体传递了解完整语义。

从 SKILL.md 引用捆绑脚本

当技能加载时，激活消息将绝对技能目录暴露为 [技能目录：/abs/path]，并在 SKILL.md 正文中的任何位置替换两个模板令牌：

因此，SKILL.md 可以告诉代理直接运行捆绑脚本：

要分析输入，请运行：

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

代理看到替换后的绝对路径，并使用可立即运行的命令调用 terminal 工具——无需路径计算，无需额外的 skill_view 往返。在 config.yaml 中使用 skills.template_vars: false 全局禁用替换。

内联 shell 片段（选择加入）

技能还可以在 SKILL.md 正文中嵌入内联 shell 片段，写作 !`cmd`。启用后，每个片段的 stdout 会在代理读取消息之前内联到消息中，因此技能可以注入动态上下文：

当前日期：!`date -u +%Y-%m-%d`
Git 分支：!`git -C ${HERMES_SKILL_DIR} rev-parse --abbrev-ref HEAD`

这默认关闭——SKILL.md 中的任何片段都会在未经批准的情况下在主机上运行，因此仅对您信任的技能源启用：

## config.yaml
skills:
  inline_shell: true
  inline_shell_timeout: 10   # 每个片段的秒数

片段以技能目录作为工作目录运行，输出限制为 4000 个字符。失败（超时、非零退出）会显示为简短的 [内联 shell 错误：...] 标记，而不是破坏整个技能。

测试它

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

hermes chat --toolsets skills -q "使用 X 技能执行 Y"

技能应该放在哪里？

捆绑技能（在 skills/ 中）随每个 Hermes 安装一起提供。它们应该对大多数用户广泛有用：

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

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

如果你的技能是专门的、社区贡献的或小众的，它更适合放在技能中心——上传到注册表并通过 hermes skills install 共享。

蓝图：也是自动化的技能

蓝图是一个普通的技能，额外在其 frontmatter 中声明了一个计划。添加 metadata.hermes.blueprint 块，该技能就变成了一个可共享、可运行的自动化：

metadata:
  hermes:
    tags: [blueprint, email]
    blueprint:
      schedule: "0 8 * * *"     # 存在 `blueprint:` 标记为可运行
      deliver: telegram          # 可选（默认：origin）
      prompt: "总结我未读的邮件和今天的日历。"  # 可选
      no_agent: false            # 可选

因为蓝图是一个技能，它通过整个技能管道不变地流动——搜索、检查、安装、安全扫描、来源、taps、集中索引和 hermes skills publish 用于共享。无需学习新东西。

安装蓝图。 当你安装一个带有 blueprint: 块的技能时，Hermes 将其注册为建议的 cron 作业，而不是立即调度。调度是选择加入的——安装永远不会静默创建重复作业。你通过 /suggestions 查看并接受它：

hermes skills install owner/morning-brief
## → 蓝图：'morning-brief' 是一个自动化（计划 0 8 * * *）。
## 已添加到你的建议中——运行 /suggestions 来调度或忽略它。
## 然后，在会话中：
/suggestions             # 列出待处理的建议，编号
/suggestions accept 1    # 创建 cron 作业
/suggestions dismiss 1   # 不再提供

蓝图是统一建议的 Cron 作业界面的一个来源——同一个地方，策划的入门自动化以及（稍后）使用模式和集成建议也会出现。请参阅下面的建议的 Cron 作业。

分享你构建的自动化。 由 cron 作业加载的蓝图（hermes cron create --skill <name> ...）可以导出回 SKILL.md 并像任何其他技能一样发布，因此你为自己调整的自动化对其他人来说变成了一个命令安装。

蓝图层没有添加新的对象类型、存储或传输——蓝图是一个技能，计划是一个 cron 作业，共享是现有的发布/tap/索引路径。

建议的 Cron 作业

Hermes 可以提议自动化，让你一键接受，而不是让你手动组装 cron 作业。每个提议都通过一个界面——/suggestions 命令——无论来自何处：

/suggestions             # 列出待处理的
/suggestions accept N    # 调度建议 N（创建 cron 作业）
/suggestions dismiss N   # 忽略它——锁定，不再提供
/suggestions catalog     # 添加策划的入门自动化

接受建议会调用与 cronjob 工具相同的 cron.jobs.create_job——没有第二个作业引擎。建议从不自动创建作业；接受始终是明确的。被忽略的建议通过稳定键锁定，因此相同的提议不会再次提供。待处理列表有上限，因此永远不会变成烦人的墙。

重要邮件监控目录条目是轮询→分类→展示模式：它使用一个便宜的分类器模型（config.yaml 中的 auxiliary.monitor）对收件箱项目进行评分，并仅传递超过紧急阈值的项目，否则保持静默。

发布技能

到技能中心

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、huggingface/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 的安装程序即可被发现，请考虑除了在仓库或市场中发布外，还从知名端点提供它们。