H繁中版
文件Flows社群 Repos開始使用
文件開發者指南creating skills
<!-- Source: https://hermesbible.com/docs/developer-guide/creating-skills -->

技能是向 Hermes Agent 新增新功能的首選方式。它們比工具更容易建立，不需要修改 Agent 的程式碼，並且可以與社群分享。

應該是技能還是工具？

在以下情況製作成技能：

  • 能力可以表達為指令 + shell 命令 + 現有工具
  • 它包裝了一個 Agent 可以透過 terminal 或 web_extract 呼叫的外部 CLI 或 API
  • 它不需要自訂 Python 整合或內建到 Agent 中的 API 金鑰管理
  • 範例：arXiv 搜尋、git 工作流程、Docker 管理、PDF 處理、透過 CLI 工具的 email

在以下情況製作成工具：

  • 它需要端到端的 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]          # 選用——限定特定 OS 平台
                                   #   有效值：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: "What this setting controls"
        default: "sensible-default"
        prompt: "Display prompt for setup"
    blueprint:                              # 選用——將此技能標記為可執行的自動化
      schedule: "0 9 * * *"              #   cron 表達式 / "every 2h" / ISO 時間戳
      deliver: origin                    #   選用（預設 origin）
      prompt: "Task instruction for each run"  # 選用
      no_agent: false                    # 選用
required_environment_variables:          # 選用——技能需要的環境變數
  - name: MY_API_KEY
    prompt: "Enter your API key"
    help: "Get one at https://example.com"
    required_for: "API access"
---

# Skill Title

簡短介紹。

## When to Use
觸發條件——Agent 何時應載入此技能？

## Quick Reference
常見命令或 API 呼叫的表格。

## Procedure
Agent 遵循的逐步指令。

## Pitfalls
已知的失敗模式及其處理方式。

## Verification
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 技能只在 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: 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)

每個項目支援：

  • key（必要）— 設定的點路徑（例如 myplugin.path）
  • description（必要）— 解釋設定控制什麼
  • default（選用）— 使用者未設定時的預設值
  • prompt（選用）— 在 hermes config migrate 期間顯示的提示文字；回退到 description

運作方式：

  1. 儲存： 值被寫入 config.yaml 的 skills.config.<key> 下：

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

  2. 發現： hermes config migrate 掃描所有啟用的技能，找到未設定的設定並提示使用者。設定也出現在 hermes config show 的「Skill Settings」下。

  3. 執行時注入： 當技能載入時，其設定值被解析並附加到技能訊息中：

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

    Agent 看到已設定的值，無需自行讀取 config.yaml。

  4. 手動設定： 使用者也可以直接設定值：

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

提示——何時用哪個

對 API 金鑰、權杖和其他密鑰使用 required_environment_variables（存在 ~/.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 運作）
  • 在本地後端上無需特殊處理即可使用

提示——何時用哪個

對簡單的 API 金鑰和權杖使用 required_environment_variables（存在 ~/.hermes/.env 中的字串）。對 OAuth 權杖檔案、用戶端密鑰、服務帳號 JSON、憑證或任何是磁碟上檔案的憑證使用 required_credential_files。

參見 skills/productivity/google-workspace/SKILL.md 了解同時使用兩者的完整範例。

技能指引

無外部依賴

優先使用 Python 標準庫、curl 和現有 Hermes 工具（web_extract、terminal、read_file）。若需要依賴，在技能中記錄安裝步驟。

漸進式披露

將最常用的工作流程放在前面。邊界情況和進階用法放在底部。這使常見任務的 token 使用量保持低。

包含輔助腳本

對於 XML/JSON 解析或複雜邏輯，在 scripts/ 中包含輔助腳本——不要期望 LLM 每次都行內撰寫解析器。

以文件形式遞送媒體（[[as_document]]）

如果你的技能產生高解析度截圖、圖表或任何有損預覽壓縮會影響的圖片——在回應中某處（通常是最後一行）發出字面指令 [[as_document]]。閘道器移除該指令並將該回應中提取的每個媒體路徑作為可下載的檔案附件遞送，而非行內圖片泡泡。參見技能輸出與媒體遞送了解完整語義。

從 SKILL.md 引用內建腳本

當技能載入時，啟動訊息將絕對技能目錄暴露為 [Skill directory: /abs/path]，並在 SKILL.md 主體中的任何位置替換兩個範本 token：

Token替換為
${HERMES_SKILL_DIR}技能目錄的絕對路徑
${HERMES_SESSION_ID}活躍的會話 ID（無會話時保留原位）

因此 SKILL.md 可以告訴 Agent 直接執行內建腳本：

To analyse the input, run:

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

Agent 看到替換後的絕對路徑並以現成可執行的命令呼叫 terminal 工具——無需路徑計算、無需額外的 skill_view 往返。在 config.yaml 中設定 skills.template_vars: false 以全域停用替換。

行內 shell 程式碼片段（選擇啟用）

技能也可以嵌入以 !`cmd` 格式寫在 SKILL.md 主體中的行內 shell 程式碼片段。啟用時，每個片段的 stdout 在 Agent 讀取前被行內到訊息中，因此技能可以注入動態上下文：

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

這預設為停用——SKILL.md 中的任何片段都在主機上無需批准就運行，因此只對你信任的技能來源啟用：

# config.yaml
skills:
  inline_shell: true
  inline_shell_timeout: 10   # 每個片段的秒數

片段以技能目錄為工作目錄運行，輸出上限為 4000 字元。失敗（逾時、非零退出碼）顯示為簡短的 [inline-shell error: ...] 標記，而非中斷整個技能。

測試

運行技能並驗證 Agent 正確遵循指令：

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

技能應放在哪裡？

內建技能（在 skills/ 中）隨每個 Hermes 安裝發行。它們應對大多數使用者廣泛有用：

  • 文件處理、網頁研究、常見開發工作流程、系統管理
  • 被廣泛的人群定期使用

如果你的技能是官方的且有用但非普遍需要（例如付費服務整合、重量級依賴），將它放在 optional-skills/ 中——它隨 repo 發行，可透過 hermes skills browse 發現（標記為「official」），並以內建的信任安裝。

如果你的技能是專業的、社群貢獻的或小眾的，它更適合 Skills Hub——上傳到一個儲存庫並透過 hermes skills install 分享。

Blueprint：既是技能也是自動化

Blueprint 是一個普通技能，額外在其 frontmatter 中宣告排程。新增 metadata.hermes.blueprint 區塊，技能就成為可分享的、可執行的自動化：

metadata:
  hermes:
    tags: [blueprint, email]
    blueprint:
      schedule: "0 8 * * *"     # `blueprint:` 的存在標記它為可執行
      deliver: telegram          # 選用（預設：origin）
      prompt: "Summarize my unread email and today's calendar."  # 選用
      no_agent: false            # 選用

因為 blueprint 就是一個技能，它不變地流經整個技能管線——搜尋、檢查、安裝、安全掃描、出處、taps、集中索引，以及用於分享的 hermes skills publish。無需學習新東西。

安裝 blueprint。 當你安裝帶有 blueprint: 區塊的技能時，Hermes 將其註冊為建議的排程任務而非排程它。排程是選擇啟用的——安裝永遠不會靜默建立一個定期任務。你透過 /suggestions 審查並接受它：

hermes skills install owner/morning-brief
# → Blueprint: 'morning-brief' is an automation (schedule 0 8 * * *).
#   Added to your suggestions — run /suggestions to schedule or dismiss it.

# 然後，在會話中：
/suggestions             # 列出待處理的建議，帶編號
/suggestions accept 1    # 建立排程任務
/suggestions dismiss 1   # 永不再提供

Blueprint 是統一的 Suggested Cron Jobs 介面的一個來源——與策劃的入門自動化和（稍後）使用模式及整合建議出現的相同位置。參見下方建議的排程任務。

分享你建立的自動化。 由排程任務載入的 blueprint（hermes cron create --skill <name> ...）可以匯出回 SKILL.md 並像任何其他技能一樣發佈，因此你為自己調整的自動化成為別人的一鍵安裝。

Blueprint 層不增加新的物件類型、儲存或傳輸——blueprint 是技能，排程是排程任務，分享是現有的 publish/tap/index 路徑。

建議的排程任務

Hermes 可以提議自動化並讓你一鍵接受它們，而非讓你手動組裝排程任務。每個提案都流經一個介面——/suggestions 命令——不論它來自哪裡：

來源觸發
catalog策劃的入門自動化（/suggestions catalog）— 每日簡報、重要郵件監控、每週回顧、工作日開始提醒
blueprint你安裝了帶有 blueprint: 區塊的技能
usage背景審查注意到排程可以服務的重複性請求
integration你連接了一個帳號（Gmail、GitHub、...）並提供了明顯的自動化
/suggestions             # 列出待處理
/suggestions accept N    # 排程建議 N（建立排程任務）
/suggestions dismiss N   # 拒絕它——鎖定，永遠不再提供
/suggestions catalog     # 加入策劃的入門自動化

接受建議呼叫與 cronjob 工具使用的相同 cron.jobs.create_job——沒有第二個任務引擎。建議永不自動建立任務；接受始終是明確的。被拒絕的建議透過穩定的鍵鎖定，因此相同的提案永遠不再提供。待處理列表有上限，因此永遠不會成為嘮叨牆。

重要郵件監控目錄項目是 poll→classify→surface 模式：它使用便宜的分類模型（config.yaml 中的 auxiliary.monitor）評分收件匣項目，並只遞送高於緊急閾值的項目，否則保持靜默。

發佈技能

到 Skills Hub

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

到自訂儲存庫

將你的 repo 加為 tap：

hermes skills tap add owner/repo

使用者然後可以從你的儲存庫搜尋和安裝。

安全掃描

所有 hub 安裝的技能都經過安全掃描器檢查：

  • 資料外洩模式
  • 提示注入嘗試
  • 破壞性命令
  • Shell 注入

信任等級：

  • builtin — 隨 Hermes 發行（永遠受信任）
  • official — 來自 repo 中的 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 專屬安裝器即可被發現，考慮除了在儲存庫或市集中發佈之外，還從知名端點提供它們。

擴展 CLI

contributingcron internals