技能系统

技能是按需加载的知识文档，代理会在真正需要时再动态载入。它们遵循**渐进式披露（Progressive Disclosure）**模式，以尽量减少 token 消耗，并兼容 agentskills.io 开放标准。

所有技能都存放在 ~/.hermes/skills/ 中，这里可以视为技能系统的主目录和统一存储位置。首次安装时，随 Hermes 一起提供的技能会从代码仓库复制到这里；通过 Hub 安装的技能，或由代理自己创建的技能，也都会落在这里。代理本身也可以修改或删除技能。

你也可以让 Hermes 指向外部技能目录——额外的文件夹，与本地目录一同被扫描。详见下方的外部技能目录。

另请参阅：

使用技能

每个已安装的技能都会自动暴露为一个斜杠命令（slash command）：

# In the CLI or any messaging platform:
/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/plan design a rollout for migrating our auth provider

# Just the skill name loads it and lets the agent ask what you need:
/excalidraw

内置的 plan 技能是一个典型的由技能支持的斜杠命令，具备自定义行为。运行 /plan [request] 会指示 Hermes 在必要时检查上下文，不直接执行任务，而是生成一份 Markdown 格式的实施计划，并将结果保存到相对于当前工作区/后端工作目录的 .hermes/plans/ 路径下。

你也可以通过自然语言对话与技能交互：

hermes chat --toolsets skills -q "What skills do you have?"
hermes chat --toolsets skills -q "Show me the axolotl skill"

渐进式披露（Progressive Disclosure）

技能采用高效的令牌加载模式：

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata       (varies)
Level 2: skill_view(name, path)  → Specific reference file       (varies)

只有当代理真正需要时，才会加载完整的技能内容。

SKILL.md 格式

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]     # Optional — restrict to specific OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]    # Optional — conditional activation (see below)
    requires_toolsets: [terminal]   # Optional — conditional activation (see below)
    config:                          # Optional — config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

平台特定技能

技能可通过 platform 字段限制其仅在特定操作系统上启用：

值	匹配平台
`macos`	macOS（Darwin）
`linux`	Linux
`windows`	Windows

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

设置该字段后，该技能将在不兼容平台上自动隐藏，不会出现在系统提示中、skills_list() 或斜杠命令列表中。若未设置，则默认在所有平台上加载。

条件激活（备用技能）

技能可根据当前会话中可用工具的情况自动显示或隐藏。这在备用技能场景中尤为有用：即免费或本地替代方案，仅在高级工具不可用时才出现。

metadata:
  hermes:
    fallback_for_toolsets: [web]      # Show ONLY when these toolsets are unavailable
    requires_toolsets: [terminal]     # Show ONLY when these toolsets are available
    fallback_for_tools: [web_search]  # Show ONLY when these specific tools are unavailable
    requires_tools: [terminal]        # Show ONLY when these specific tools are available

字段	行为
`fallback_for_toolsets`	当列出的工具集可用时，技能被隐藏；缺失时则显示。
`fallback_for_tools`	同上，但检查的是单个工具而非工具集。
`requires_toolsets`	当列出的工具集不可用时，技能被隐藏；存在时则显示。
`requires_tools`	同上，但检查的是单个工具。

示例： 内置的 duckduckgo-search 技能使用了 fallback_for_toolsets: [web]。当你设置了 FIRECRAWL_API_KEY 时，网络工具集可用，代理将使用 web_search —— 此时 DuckDuckGo 技能保持隐藏。若 API 密钥缺失，网络工具集不可用，DuckDuckGo 技能便会自动作为备用技能出现。

未设置任何条件字段的技能行为不变——始终显示。

加载时的安全配置

技能可声明所需的环境变量，而无需从发现列表中消失：

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 仅在本地 CLI 中实际加载该技能时，才会安全地请求输入。你可以跳过设置并继续使用技能。消息界面从不在聊天中询问密钥——而是提示你使用 hermes setup 或 ~/.hermes/.env 在本地进行配置。

一旦完成配置，这些声明过的环境变量会自动传递给 execute_code 和 terminal 的沙箱环境，技能脚本可以直接使用 $TENOR_API_KEY。如果是与技能无关的环境变量，请改用 terminal.env_passthrough。详情见环境变量透传。

技能配置项

技能还可声明非敏感的配置项（如路径、偏好设置），这些配置存储在 config.yaml 中：

metadata:
  hermes:
    config:
      - key: wiki.path
        description: Path to the wiki directory
        default: "~/wiki"
        prompt: Wiki directory path

配置项存储在你的 config.yaml 文件中的 skills.config 下。hermes config migrate 会提示未配置的设置，hermes config show 可用于查看当前配置。当技能加载时，其解析后的配置值会被注入上下文，使代理能自动知晓已配置的值。

详情请见技能配置与创建技能：配置项。

技能目录结构

~/.hermes/skills/                  # Single source of truth
├── mlops/                         # Category directory
│   ├── axolotl/
│   │   ├── SKILL.md               # Main instructions (required)
│   │   ├── references/            # Additional docs
│   │   ├── templates/             # Output formats
│   │   ├── scripts/               # Helper scripts callable from the skill
│   │   └── assets/                # Supplementary files
│   └── vllm/
│       └── SKILL.md
├── devops/
│   └── deploy-k8s/                # Agent-created skill
│       ├── SKILL.md
│       └── references/
├── .hub/                          # Skills Hub state
│   ├── lock.json
│   ├── quarantine/
│   └── audit.log
└── .bundled_manifest              # Tracks seeded bundled skills

外部技能目录

如果你在 Hermes 之外维护技能（例如，多个 AI 工具共享的 ~/.agents/skills/ 目录），可以告诉 Hermes 也扫描这些目录。

在 ~/.hermes/config.yaml 的 skills 部分添加 external_dirs：

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

路径支持 ~ 扩展和 ${VAR} 环境变量替换。

工作机制

只读扫描：外部目录仅用于技能发现。当代理创建或编辑技能时，始终写入 ~/.hermes/skills/。
本地优先：若同一技能名同时存在于本地目录和外部目录，本地版本优先。
完全集成：外部技能会出现在系统提示索引、skills_list、skill_view 和斜杠命令中——与本地技能无异。
不存在路径静默跳过：若配置的目录不存在，Hermes 会忽略而不报错。适用于可选的共享目录，可能并非每台机器都存在。

示例

~/.hermes/skills/               # Local (primary, read-write)
├── devops/deploy-k8s/
│   └── SKILL.md
└── mlops/axolotl/
    └── SKILL.md

~/.agents/skills/               # External (read-only, shared)
├── my-custom-workflow/
│   └── SKILL.md
└── team-conventions/
    └── SKILL.md

所有四个技能均出现在你的技能索引中。如果你在本地创建一个名为 my-custom-workflow 的新技能，它将覆盖外部版本。

代理自管理技能（`skill_manage` 工具）

代理可通过 skill_manage 工具自行创建、更新和删除技能。这是代理的过程记忆——当它发现一个非平凡的工作流程时，会将其保存为技能以供未来复用。

代理创建技能的时机

成功完成复杂任务（5+ 工具调用）
遇到错误或死胡同并找到可行路径
用户纠正了它的方法
发现非平凡的工作流

操作类型

操作	用途	关键参数
`create`	从零创建新技能	`name`, `content`（完整 SKILL.md），可选 `category`
`patch`	针对性修复（推荐）	`name`, `old_string`, `new_string`
`edit`	重大结构调整	`name`, `content`（完整 SKILL.md 替换）
`delete`	完全移除某个技能	`name`
`write_file`	添加/更新支持文件	`name`, `file_path`, `file_content`
`remove_file`	移除支持文件	`name`, `file_path`

tip

建议使用 patch 进行更新——相比 edit 更节省令牌，因为工具调用中仅包含变更部分的文本。

技能中心（Skills Hub）

你可以通过 Skills Hub 从在线注册表、skills.sh、知名技能端点以及官方可选技能源中浏览、搜索、安装和管理技能。

常用命令

hermes skills browse                              # Browse all hub skills (official first)
hermes skills browse --source official            # Browse only official optional skills
hermes skills search kubernetes                   # Search all sources
hermes skills search react --source skills-sh     # Search the skills.sh directory
hermes skills search https://mintlify.com/docs --source well-known
hermes skills inspect openai/skills/k8s           # Preview before installing
hermes skills install openai/skills/k8s           # Install with security scan
hermes skills install official/security/1password
hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force
hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify
hermes skills list --source hub                   # List hub-installed skills
hermes skills check                               # Check installed hub skills for upstream updates
hermes skills update                              # Reinstall hub skills with upstream changes when needed
hermes skills audit                               # Re-scan all hub skills for security
hermes skills uninstall k8s                       # Remove a hub skill
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills snapshot export setup.json          # Export skill config
hermes skills tap add myorg/skills-repo           # Add a custom GitHub source

支持的 Hub 源| 来源 | 示例 | 备注 |

|------|------|------| | official | official/security/1password | Hermes 内置的可选技能。 | | skills-sh | skills-sh/vercel-labs/agent-skills/vercel-react-best-practices | 可通过 hermes skills search <query> --source skills-sh 搜索。Hermes 在技能名称（skills.sh 的 slug）与仓库文件夹名不一致时，会自动解析别名风格的技能。 | | well-known | well-known:https://mintlify.com/docs/.well-known/skills/mintlify | Skills served directly from /.well-known/skills/index.json 在网站上。通过站点或文档 URL 进行搜索。 | | github | openai/skills/k8s | 直接从 GitHub 仓库/路径安装，以及自定义 tap。 | | clawhub, lobehub, claude-marketplace | 与来源相关的标识符 | 社区或市场集成。 |

已集成的枢纽与注册中心

Hermes 目前集成了以下技能生态系统和发现源：

1. 官方可选技能（`official`）

这些技能由 Hermes 仓库直接维护，并默认具备内置信任。

目录：官方可选技能目录
仓库内源码位置：optional-skills/
示例：

hermes skills browse --source official
hermes skills install official/security/1password

2. skills.sh（`skills-sh`）

这是 Vercel 的公开技能目录。Hermes 可以直接搜索它、检查技能详情页、解析别名风格的 slug，并从底层源代码仓库安装。

目录：skills.sh
CLI/工具仓库：vercel-labs/skills
官方 Vercel 技能仓库：vercel-labs/agent-skills
示例：

hermes skills search react --source skills-sh
hermes skills inspect skills-sh/vercel-labs/json-render/json-render-react
hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force

3. 知名技能端点（`well-known`）

这是一种基于 URL 的发现机制，适用于在网站上发布 /.well-known/skills/index.json 的站点。这不是单一的集中式枢纽，而是一种网页发现规范。

实际运行示例端点：Mintlify 文档技能索引
参考服务器实现：vercel-labs/skills-handler
示例：

hermes skills search https://mintlify.com/docs --source well-known
hermes skills inspect well-known:https://mintlify.com/docs/.well-known/skills/mintlify
hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify

4. 直接来自 GitHub 的技能（`github`）

Hermes 可以直接从 GitHub 仓库或基于 GitHub 的 tap 安装技能。当你已知特定仓库路径，或希望添加自己的自定义源仓库时非常有用。

默认 tap（无需额外配置即可浏览）：

hermes skills install openai/skills/k8s
hermes skills tap add myorg/skills-repo

5. ClawHub（`clawhub`）

一个第三方技能市场，作为社区源集成。

网站：clawhub.ai
Hermes 源 ID：clawhub

6. Claude 市场风格仓库（`claude-marketplace`）

Hermes 支持发布兼容 Claude 插件/市场的清单文件的市场型仓库。

已集成的知名来源包括：

Hermes 源 ID：claude-marketplace

7. LobeHub（`lobehub`）

Hermes 可以搜索并转换 LobeHub 公开目录中的代理条目为可安装的 Hermes 技能。

网站：LobeHub
公开代理索引：chat-agents.lobehub.com
后端仓库：lobehub/lobe-chat-agents
Hermes 源 ID：lobehub

安全扫描与 `--force`

所有通过枢纽安装的技能都会经过 安全扫描，检测数据外泄、提示注入、破坏性命令、供应链信号及其他威胁。

hermes skills inspect ... 现在还会在可用时展示上游元数据：

仓库地址
skills.sh 详情页地址
安装命令
每周安装量
上游安全审计状态
知名索引/端点 URL

当你审查过第三方技能后，若想绕过非危险性策略限制，请使用 --force：

hermes skills install skills-sh/anthropics/skills/pdf --force

重要行为说明：

--force 可用于覆盖“谨慎”或“警告”级别的发现结果。
--force 不会覆盖 dangerous 的扫描结论。
官方可选技能（official/...）被视为内置信任，不会显示第三方警告面板。

信任等级

等级	来源	策略
`builtin`	随 Hermes 一同分发	始终受信任
`official`	位于仓库内的 `optional-skills/`	内置信任，不显示第三方警告
`trusted`	受信任的注册中心/仓库，如 `openai/skills`、`anthropics/skills`	比社区源更宽松的策略
`community`	其他所有来源（`skills.sh`、知名端点、自定义 GitHub 仓库、大多数市场）	非危险性发现可通过 `--force` 覆盖；`dangerous` 结论仍被阻止

更新生命周期

如今，枢纽已追踪足够的溯源信息，可重新检查已安装技能的上游副本：

hermes skills check          # Report which installed hub skills changed upstream
hermes skills update         # Reinstall only the skills with updates available
hermes skills update react   # Update one specific installed hub skill

该功能利用存储的源标识符加上当前上游包内容哈希来检测漂移。

GitHub 请求速率限制

技能枢纽操作使用 GitHub API，未认证用户的速率为每小时 60 次请求。如果在安装或搜索时遇到速率限制错误，请在你的 .env 文件中设置 GITHUB_TOKEN，将限额提升至每小时 5,000 次。错误消息会包含可操作提示。

斜杠命令（聊天内使用）

所有相同命令均支持 /skills：

/skills browse
/skills search react --source skills-sh
/skills search https://mintlify.com/docs --source well-known
/skills inspect skills-sh/vercel-labs/json-render/json-render-react
/skills install openai/skills/skill-creator --force
/skills check
/skills update
/skills list

官方可选技能仍使用类似 official/security/1password 和 official/migration/openclaw-migration 的标识符。

使用技能​

渐进式披露（Progressive Disclosure）​

SKILL.md 格式​

平台特定技能​

条件激活（备用技能）​

加载时的安全配置​

技能配置项​

技能目录结构​

外部技能目录​

工作机制​

示例​

代理自管理技能（skill_manage 工具）​

代理创建技能的时机​

操作类型​

技能中心（Skills Hub）​

常用命令​

支持的 Hub 源| 来源 | 示例 | 备注 |​

已集成的枢纽与注册中心​

1. 官方可选技能（official）​

2. skills.sh（skills-sh）​

3. 知名技能端点（well-known）​

4. 直接来自 GitHub 的技能（github）​

5. ClawHub（clawhub）​

6. Claude 市场风格仓库（claude-marketplace）​

7. LobeHub（lobehub）​

安全扫描与 --force​

信任等级​

更新生命周期​

斜杠命令（聊天内使用）​