原文链接：Creating Skills sidebar position: 3 title: "创建技能" description: "如何为 Hermes Agent 创建技能——SKILL.md 格式、指南和发布" 技能(Skills)是为 Hermes Agent 添加新功能的首选方式。它们比工具更容易创建，不
> 原文链接：Creating Skills
sidebar_position: 3 title: "创建技能" description: "如何为 Hermes Agent 创建技能——SKILL.md 格式、指南和发布"
创建技能(Skills)
技能(Skills)是为 Hermes Agent 添加新功能的首选方式。它们比工具更容易创建，不需要修改 Agent 代码，并且可以与社区共享。
应该做成技能还是工具？
做成技能的情况：
- 该功能可以表示为指令 + Shell 命令 + 现有工具
- 它封装了一个外部 CLI 或 API，Agent 可以通过
terminal或web_extract调用 - 它不需要与 Agent 深度集成的自定义 Python 代码或 API 密钥管理
- 示例：arXiv 搜索、Git 工作流、Docker 管理、PDF 处理、通过 CLI 工具发送邮件
做成**工具(Tool)**的情况：
- 它需要与 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 访问"
---
# 技能标题
简要介绍。
## 何时使用
触发条件 — Agent 何时应加载此技能？
## 快速参考
常用命令或 API 调用表格。
## 步骤
Agent 遵循的分步指令。
## 陷阱
已知失败模式及处理方法。
## 验证
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 密钥）未配置时显示。
requires_* 用例： 创建一个只在某些工具存在时才有意义的技能。例如，一个带有 requires_toolsets: [web] 的网页抓取工作流技能，在 web 工具被禁用时不会占用提示词空间。
环境变量要求
技能可以声明它们需要的环境变量。当技能通过 skill_view 加载时，其必需的变量会自动注册以传递到沙盒执行环境（terminal、execute_code）中。
required_environment_variables:
- name: TENOR_API_KEY
prompt: "Tenor API key" # 提示用户时显示
help: "在 https://tenor.com 获取你的密钥" # 帮助文本或 URL
required_for: "GIF 搜索功能" # 哪个功能需要此变量
每个条目支持：
name（必需）— 环境变量名prompt（可选）— 向用户询问值时的提示文本help（可选）— 获取值的帮助文本或 URLrequired_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: 从 https://developers.google.com/tenor 获取密钥
required_for: 完整功能
用户可以跳过设置并继续加载技能。Hermes 永远不会向模型暴露原始密钥值。网关和消息会话显示本地设置指引，而不是在频道内收集密钥。
:::tip 沙盒传递
当你的技能被加载时，任何已设置的声明 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: LLM Wiki 知识库目录的路径
default: "~/wiki"
prompt: Wiki 目录路径
- key: wiki.domain
description: Wiki 覆盖的领域
default: ""
prompt: Wiki 领域（例如 AI/ML 研究）
每个条目支持：
key（必需）— 设置的点分路径（例如wiki.path）description（必需）— 解释此设置控制什么default（可选）— 用户未配置时的默认值prompt（可选）—hermes config migrate期间显示的提示文本；默认使用description
工作原理：
-
存储： 值写入
config.yaml的skills.config.<key>下：skills: config: wiki: path: ~/my-research -
发现：
hermes config migrate扫描所有已启用的技能，找到未配置的设置，并提示用户。设置也会出现在hermes config show的"技能设置"部分。 -
运行时注入： 当技能加载时，其配置值被解析并附加到技能消息中：
[Skill config (from ~/.hermes/config.yaml): wiki.path = /home/user/my-research ]Agent 看到已配置的值，无需自己读取
config.yaml。 -
手动设置： 用户也可以直接设置值：
hermes config set skills.config.wiki.path ~/my-wiki
:::tip 何时使用哪种
使用 required_environment_variables 来存储 API 密钥、令牌和其他密钥（存储在 ~/.hermes/.env 中，不向模型展示）。使用 config 来存储路径、偏好和非敏感设置（存储在 config.yaml 中，可在 config show 中查看）。
:::
凭据文件要求(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 也能工作）
- 在本地后端上无需特殊处理即可使用
:::tip 何时使用哪种
使用 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/ 中包含辅助脚本——不要期望 LLM 每次都内联编写解析器。
测试
运行技能并验证 Agent 是否正确遵循指令：
hermes chat --toolsets skills -q "使用 X 技能完成 Y"
技能应该放在哪里？
内置技能（在 skills/ 中）随每次 Hermes 安装提供。它们应该是大多数用户广泛需要的：
- 文档处理、网络研究、常见开发工作流、系统管理
- 被广泛人群定期使用
如果你的技能是官方的但并非所有人都需要（例如付费服务集成、重量级依赖），请放在 optional-skills/ 中——它随仓库一起发布，可通过 hermes skills browse 发现（标记为"official"），并以内置信任级别安装。
如果你的技能是专业性的、社区贡献的或小众的，更适合放在技能中心(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/skillscommunity— 非危险发现可以用--force覆盖；dangerous判定保持阻止
Hermes 现在可以从多个外部发现模型消费第三方技能：
- 直接 GitHub 标识符（例如
openai/skills/k8s） skills.sh标识符（例如skills-sh/vercel-labs/json-render/json-render-react）- 从
/.well-known/skills/index.json提供的知名端点
如果你希望你的技能在不使用 GitHub 特定安装器的情况下被发现，考虑从知名端点提供服务，同时发布到仓库或市场。