Skip to main content

创建技能

This guide explains how to create, format, and publish skills for the Hermes Agent ecosystem using the standardized SKILL.md format. Skills extend Hermes Agent's capabilities by enabling it to perform specific tasks, integrate with tools, or interact with external systems.

📄 1. Understanding the SKILL.md Format​

The SKILL.md file is a Markdown document that describes a skill in a structured way. It must be placed at the root of your skill repository (e.g., your-skill-repo/SKILL.md).

✅ Required Fields in SKILL.md​

FieldDescription
nameA short, descriptive name for the skill (e.g., weather-checker, github-issues)
descriptionA clear, concise explanation of what the skill does (max 200 words)
versionSkill version (e.g., 1.0.0)
authorYour name or organization (e.g., Jane Doe, Acme Labs)
licenseSPDX-compliant license (e.g., MIT, Apache-2.0)
tagsArray of keywords (e.g., ["api", "utility", "automation"])
inputsList of required input parameters (with type and description)
outputsList of expected output values (with type and description)
exampleExample usage (can include JSON or code snippet)
dependenciesExternal dependencies (if any)
repositoryURL to the skill’s source code (GitHub/GitLab/etc.)
documentationLink to detailed documentation (optional)

💡 Note: All fields are required unless explicitly marked as optional.

🧩 2. Example: SKILL.md Template​

---
name: weather-checker
description: Retrieves current weather data for a given location using OpenWeatherMap API.
version: 1.0.0
author: Alice Chen
license: MIT
tags:
  - weather
  - api
  - utility
inputs:
  - name: location
    type: string
    description: The city or ZIP code to check weather for (e.g., "London", "90210")
    required: true
outputs:
  - name: temperature
    type: number
    description: Current temperature in Celsius
  - name: condition
    type: string
    description: Weather condition (e.g., "Clear", "Rainy")
example: |
  {
    "location": "San Francisco",
    "temperature": 18,
    "condition": "Partly Cloudy"
  }
dependencies:
  - openweathermap-api-client@^1.2.0
repository: https://github.com/alice/weather-checker-skill
documentation: https://docs.hermes-agent.dev/skills/weather-checker
---

🛠️ 3. Skill Development Guidelines​

✅ Best Practices​

  • Keep it focused: One skill = one task (e.g., “send-email”, “parse-json”).
  • Use standard inputs/outputs: Stick to string, number, boolean, object, array.
  • Validate inputs early: Reject invalid or missing inputs gracefully.
  • Handle errors clearly: Return meaningful error messages via error field in output.
  • Avoid hardcoding secrets: Use environment variables (process.env.OPENWEATHER_API_KEY).
  • Document edge cases: Mention rate limits, timeouts, or API quotas.

❌ Avoid These​

  • Including sensitive credentials in code or config files.
  • Using non-standard or ambiguous field names.
  • Making skills too large or complex (split into smaller ones if needed).
  • Skipping error handling or logging.

📤 4. Publishing Your Skill​

Once your skill is ready:

Step 1: Create a Public Repository​

  • Host your skill on GitHub, GitLab, or similar.
  • Include the SKILL.md file at the root.
  • Add a README.md with setup instructions and examples.

Step 2: Tag Your Repository​

Add the hermes-skill topic to your repo (on GitHub):

  • Go to Settings > Topics
  • Add hermes-skill

This helps Hermes Agent discover your skill automatically.

Step 3: Submit to the Official Registry (Optional)​

To get listed in the Hermes Agent Skill Hub:

  1. Fork the official registry repo
  2. Add your skill entry under skills/ directory (e.g., skills/weather-checker.json)
  3. Submit a pull request with your changes.

Example Entry (skills/weather-checker.json):​

{
  "name": "weather-checker",
  "url": "https://github.com/alice/weather-checker-skill",
  "source": "github",
  "tags": ["weather", "api", "utility"],
  "description": "Retrieves current weather data for a given location using OpenWeatherMap API.",
  "last_updated": "2025-04-05T12:00:00Z"
}

✅ Once merged, your skill will appear in the public hub and be discoverable by all Hermes Agents.

🔗 5. Integrating with Hermes Agent​

After publishing, users can use your skill via:

  • CLI: hermes run --skill weather-checker --input location=Paris
  • API: Call /api/skills/weather-checker with input payload
  • UI: Select from skill catalog in Hermes Dashboard

Ensure your skill supports async execution and returns valid JSON responses.

📚 Resources​

🤝 Need Help?​

Join the community:

✅ You're now ready to build and share powerful skills for Hermes Agent!
Let’s make AI agents smarter, one skill at a time. 🚀"​

创建技能

技能是向 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              # Required: main instructions
│       └── scripts/              # Optional: 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]          # Optional — restrict to specific OS platforms
                                   #   Valid: macos, linux, windows
                                   #   Omit to load on all platforms (default)
metadata:
  hermes:
    tags: [Category, Subcategory, Keywords]
    related_skills: [other-skill-name]
    requires_toolsets: [web]            # Optional — only show when these toolsets are active
    requires_tools: [web_search]        # Optional — only show when these tools are available
    fallback_for_toolsets: [browser]    # Optional — hide when these toolsets are active
    fallback_for_tools: [browser_navigate]  # Optional — hide when these tools exist
    config:                              # Optional — config.yaml settings the skill needs
      - key: my.setting
        description: "What this setting controls"
        default: "sensible-default"
        prompt: "Display prompt for setup"
required_environment_variables:          # Optional — env vars the skill needs
  - 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 — when should the agent load this skill?

## Quick Reference
Table of common commands or API calls.

## Procedure
Step-by-step instructions the agent follows.

## Pitfalls
Known failure modes and how to handle them.

## Verification
How the agent confirms it worked.

平台特定技能​

技能可通过 platforms 字段限制其仅在特定操作系统上运行：

platforms: [macos]            # macOS only (e.g., iMessage, Apple Reminders)
platforms: [macos, linux]     # macOS and Linux
platforms: [windows]          # Windows only

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

条件性技能激活​

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

metadata:
  hermes:
    requires_toolsets: [web]           # Hide if the web toolset is NOT active
    requires_tools: [web_search]       # Hide if web_search tool is NOT available
    fallback_for_toolsets: [browser]   # Hide if the browser toolset IS active
    fallback_for_tools: [browser_navigate]  # Hide if browser_navigate IS available
字段行为
requires_toolsets当任意列出的工具集 不可用 时，技能被 隐藏
requires_tools当任意列出的工具 不可用 时，技能被 隐藏
fallback_for_toolsets当任意列出的工具集 可用 时，技能被 隐藏
fallback_for_tools当任意列出的工具 可用 时，技能被 隐藏

fallback_for_* 的使用场景： 创建一个备用技能，当主工具不可用时启用。例如，一个 duckduckgo-search 技能，仅在未配置网络搜索工具（需 API 密钥）时显示。

requires_* 的使用场景： 创建仅在某些工具存在时才有意义的技能。例如，一个网页抓取工作流技能，带有 requires_toolsets: [web]，当禁用网络工具时不会污染提示。

环境变量要求​

技能可声明其所需的环境变量。当通过 skill_view 加载技能时，其所需变量会自动注册并传入沙箱执行环境（终端、execute_code）。

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: "Tenor API key"               # Shown when prompting user
    help: "Get your key at https://tenor.com"  # Help text or URL
    required_for: "GIF search functionality"   # What needs this var

每项支持：

  • name（必需）—— 环境变量名称
  • prompt（可选）—— 向用户询问值时的提示文本
  • help（可选）—— 获取该值的帮助文本或链接
  • 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 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: wiki.path
        description: Path to the LLM Wiki knowledge base directory
        default: "~/wiki"
        prompt: Wiki directory path
      - key: wiki.domain
        description: Domain the wiki covers
        default: ""
        prompt: Wiki domain (e.g., AI/ML research)

每项支持：

  • key（必需）—— 设置的点路径（例如 wiki.path）
  • description（必需）—— 解释该设置控制的内容
  • default（可选）—— 用户未配置时的默认值
  • prompt（可选）—— 在 hermes config migrate 过程中显示的提示文本；若无则回退至 description

工作原理：

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

    skills:
      config:
        wiki:
          path: ~/my-research

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

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

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

    代理会看到已配置的值，而无需自行读取 config.yaml。

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

    hermes config set skills.config.wiki.path ~/my-wiki
如何选择使用哪种方式

使用 required_environment_variables 存储 API 密钥、令牌等 敏感信息（存储在 ~/.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 流程）
  • 在 本地后端 上无需特殊处理即可使用
如何选择使用哪种方式

使用 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/ 中包含辅助脚本——不要期望大模型每次都内联编写解析器。

进行测试​

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

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

技能应存放在何处？​

内置技能（位于 skills/）随每个 Hermes 安装包一起提供。它们应具有 对大多数用户普遍有用 的特性：- 文档处理、网络调研、常见开发工作流、系统管理

  • 被广泛人群频繁使用

如果您的技能是官方且实用，但并非人人必需（例如付费服务集成、重型依赖），请将其放入 optional-skills/ —— 该技能随仓库一同提供，可通过 hermes skills browse（标记为“官方”）发现，并可借助内置信任机制安装。

如果您的技能较为专业、由社区贡献或属于小众领域，更适合发布至 技能中心（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/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 特定安装器的情况下也能被发现，建议除在仓库或市场发布外，同时通过知名端点提供服务。