跳到主要內容

創建技能

技能是向 Hermes Agent 添加新功能的首選方式。相比工具，技能更易於創建，無需修改 Agent 代碼，並且可以與社區共享。

應該創建技能還是工具？​

當滿足以下條件時，請創建一個 技能：

  • 功能可以通過指令 + shell 命令 + 現有工具來表達
  • 包裝了一個外部 CLI 或 API，Agent 可通過 terminal 或 web_extract 調用
  • 不需要在 Agent 中內嵌自定義的 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: Brief description (shown in skill search results)
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]            # 可選 — 僅當這些 toolsets 處於活動狀態時顯示
    requires_tools: [web_search]        # 可選 — 僅當這些 tools 可用時顯示
    fallback_for_toolsets: [browser]    # 可選 — 當這些 toolsets 處於活動狀態時隱藏
    fallback_for_tools: [browser_navigate]  # 可選 — 當這些 tools 存在時隱藏
    config:                              # 可選 — config.yaml skill 需要的設置
      - key: my.setting
        description: "What this setting controls"
        default: "sensible-default"
        prompt: "Display prompt for setup"
required_environment_variables:          # 可選 — skill 需要的環境變量
  - name: MY_API_KEY
    prompt: "Enter your API key"
    help: "Get one at https://example.com"
    required_for: "API access"
---

# Skill 標題

Brief intro.

## 何時使用
Trigger conditions — when should the agent load this skill?

## 快速參考
Table of common commands or API calls.

## 操作步驟
Step-by-step instructions the agent follows.

## 常見陷阱
Known failure modes and how to handle them.

## 驗證方式
How the agent confirms it worked.

平臺特定技能​

技能可以通過 platforms 字段限制其適用的操作系統：

platforms: [macos]            # 僅限 macOS（例如 iMessage、Apple 提醒）
platforms: [macos, linux]     # macOS 和 Linux
platforms: [windows]          # 僅限 Windows

設置後，該技能將自動從系統提示、skills_list() 和斜槓命令中隱藏，以避免在不兼容的平臺上顯示。若省略或為空，則該技能在所有平臺上加載（向後兼容）。

條件性技能激活​

技能可以聲明對特定工具或工具集的依賴關係，從而控制該技能在特定會話的系統提示中是否出現。

metadata:
  hermes:
    requires_toolsets: [web]           # 如果網絡 toolset 處於 NOT 活動狀態則隱藏
    requires_tools: [web_search]       # 如果 `web_search` Tool 不可用則隱藏
    fallback_for_toolsets: [browser]   # 如果瀏覽器 toolset 處於活動狀態則隱藏
    fallback_for_tools: [browser_navigate]  # 如果 `browser_navigate` 可用則隱藏
字段行為
requires_toolsets當任意列出的工具集 不可用 時，該技能被 隱藏
requires_tools當任意列出的工具 不可用 時，該技能被 隱藏
fallback_for_toolsets當任意列出的工具集 可用 時，該技能被 隱藏
fallback_for_tools當任意列出的工具 可用 時，該技能被 隱藏

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 key"               # 提示用戶時顯示
    help: "Get your key at https://tenor.com"  # 幫助文本或 URL
    required_for: "GIF search functionality"   # 什麼需要這個變量

每項條目支持：

  • 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 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. 運行時注入：當一個技能加載時，其配置值會被解析並附加到技能消息中：

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

    Agent 在無需自行讀取 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/ 目錄中包含輔助腳本——不要期望 LLM 每次都內聯編寫解析器。

進行測試​

運行該技能並驗證 Agent 是否正確遵循了指令：

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 覆蓋；危險判定仍被阻止

Hermes 現在可從多個外部發現模型中消費第三方技能：

  • 直接使用 GitHub 標識符（例如 openai/skills/k8s）
  • 使用 skills.sh 標識符（例如 skills-sh/vercel-labs/json-render/json-render-react）
  • 從 /.well-known/skills/index.json 提供的知名端點

如果你希望你的技能在無需 GitHub 特定安裝器的情況下也能被發現，建議除了在倉庫或市場中發佈外，還提供一個知名端點。