技能系统

技能是 Agent 可以按需加载的知识文档。它们采用渐进式披露模式来最小化 Token 消耗，并与 agentskills.io 开放标准兼容。

所有技能存放在 ~/.hermes/skills/ 目录中——这是主目录和唯一数据源。全新安装时，捆绑技能会从仓库复制到这里。通过 Hub 安装和 Agent 自创建的技能也会放在此目录。Agent 可以修改或删除任何技能。

你还可以指定外部技能目录——额外的文件夹会与本地目录一起被扫描。详见下方外部技能目录。

使用技能

每个已安装的技能都自动作为斜杠命令可用：

# 在 CLI 或任何消息平台中：
/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

# 仅输入技能名即可加载，Agent 会询问你需要什么：
/excalidraw

内置的 plan 技能是一个很好的例子。运行 /plan [请求] 会加载技能指令，告诉 Hermes 在需要时检查上下文，编写 Markdown 实现计划而非直接执行任务，并将结果保存在当前工作区的 .hermes/plans/ 目录下。

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

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

渐进式加载

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

• Level 0：skills_list() → [{name, description, category}, ...]（约 3k Token）
• Level 1：skill_view(name) → 完整内容 + 元数据（不等）
• Level 2：skill_view(name, path) → 特定参考文件（不等）

Agent 只在实际需要时才加载完整技能内容。

SKILL.md 格式

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux] # 可选 — 限制到特定操作系统平台
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web] # 可选 — 条件激活（见下文）
    requires_toolsets: [terminal] # 可选 — 条件激活（见下文）
    config: # 可选 — config.yaml 设置
      - 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.

平台特定技能

技能可以使用 platforms 字段限制自己在特定操作系统上运行：

值	匹配
macos	macOS (Darwin)
linux	Linux
windows	Windows

platforms: [macos] # 仅 macOS（如 iMessage、Apple Reminders、FindMy）
platforms: [macos, linux] # macOS 和 Linux

设置后，技能在不兼容平台上会自动从系统提示、skills_list() 和斜杠命令中隐藏。如果省略，技能在所有平台上加载。

条件激活（后备技能）

技能可以根据当前会话中可用的工具自动显示或隐藏自己。这对于后备技能最有用——当高级工具不可用时才出现的免费或本地替代方案。

metadata:
  hermes:
    fallback_for_toolsets: [web] # 仅当这些工具集不可用时显示
    requires_toolsets: [terminal] # 仅当这些工具集可用时显示
    fallback_for_tools: [web_search] # 仅当这些特定工具不可用时显示
    requires_tools: [terminal] # 仅当这些特定工具可用时显示

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

示例：内置的 duckduckgo-search 技能使用 fallback_for_toolsets: [web]。当你设置了 FIRECRAWL_API_KEY 时，web 工具集可用，Agent 使用 web_search——DuckDuckGo 技能保持隐藏。如果 API Key 缺失，web 工具集不可用，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 和终端沙箱——技能的脚本可以直接使用 $TENOR_API_KEY。

技能配置设置

技能还可以声明存储在 config.yaml 中的非密钥配置设置（路径、偏好）：

metadata:
  hermes:
    config:
      - key: myplugin.path
        description: Path to the plugin data directory
        default: "~/myplugin-data"
        prompt: Plugin data directory path

设置存储在 config.yaml 的 skills.config 下。hermes config migrate 会提示未配置的设置，hermes config show 会显示它们。技能加载时，其解析后的配置值会被注入上下文，Agent 会自动知道已配置的值。

技能目录结构

~/.hermes/skills/              # 唯一数据源
├── mlops/                     # 分类目录
│   ├── axolotl/
│   │   ├── SKILL.md           # 主指令文件（必需）
│   │   ├── references/        # 附加文档
│   │   ├── templates/         # 输出格式
│   │   ├── scripts/           # 可从技能调用的辅助脚本
│   │   └── assets/            # 补充文件
│   └── vllm/
│       └── SKILL.md
├── devops/
│   └── deploy-k8s/            # Agent 自创建的技能
│       ├── SKILL.md
│       └── references/
├── .hub/                      # Skills Hub 状态
│   ├── lock.json
│   ├── quarantine/
│   └── audit.log
└── .bundled_manifest          # 跟踪已播种的捆绑技能

外部技能目录

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

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

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

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

工作方式

• 本地创建，就地更新：新的 Agent 自创建技能写入 ~/.hermes/skills/。现有技能在 Agent 使用 skill_manage 操作（如 patch、edit、write_file、remove_file 或 delete）时，会在其原始位置被修改，包括 external_dirs 下的技能。

• 外部目录不是写保护边界：如果外部技能目录对 Hermes 进程可写，Agent 管理的技能更新可以更改该目录中的文件。如果共享外部技能必须保持只读，请使用文件系统权限或单独的 profile/toolset 设置。

• 本地优先：如果本地目录和外部目录中存在同名技能，本地版本优先。

• 完整集成：外部技能出现在系统提示索引、skills_list、skill_view 和 /skill-name 斜杠命令中——与本地技能无异。

• 不存在的路径被静默跳过：如果配置的目录不存在，Hermes 会忽略它而不报错。

技能包（Bundles）

技能包是小型 YAML 文件，将多个技能组合在单个斜杠命令下。当你运行 /<bundle-name> 时，包中列出的每个技能会同时加载——适用于某个任务总是需要同一组技能一起使用的场景。

创建技能包

# 为后端开发工作创建一个技能包
hermes bundles create backend-dev \
  --skill github-code-review \
  --skill test-driven-development \
  --skill github-pr-workflow \
  -d "Backend feature work — review, test, PR workflow"

然后在 CLI 或任何网关平台中：

/backend-dev refactor the auth middleware

Agent 会将三个技能加载到一条用户消息中，斜杠命令后的文本作为用户指令附加。

YAML 模式

技能包存放在 ~/.hermes/skill-bundles/<slug>.yaml，格式如下：

name: backend-dev
description: Backend feature work — review, test, PR workflow.
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow
instruction: |
  Always start by writing failing tests, then implement.
  Open the PR through the standard workflow with co-author tags.

字段说明：

• name（可选 — 默认为文件名）— 技能包的显示名称。标准化为连字符 slug 作为斜杠命令（Backend Dev → /backend-dev）。
• description（可选）— 在 /bundles 和 hermes bundles list 中显示的简短文本。
• skills（必需，非空列表）— 技能名称或相对于技能目录的路径。使用与 / 相同的标识符。
• instruction（可选）— 预置到加载技能内容之前的额外指导。用于编码”我们总是如何一起使用这些技能”。

管理技能包

# 列出所有已安装的技能包
hermes bundles list

# 查看某个技能包
hermes bundles show backend-dev

# 交互式创建技能包（省略 --skill 标志逐行输入）
hermes bundles create research

# 覆盖已有技能包
hermes bundles create backend-dev --skill ... --force

# 删除技能包
hermes bundles delete backend-dev

# 重新扫描 ~/.hermes/skill-bundles/ 并报告变更
hermes bundles reload

在聊天会话中，/bundles 列出所有已安装的技能包及其技能。

Agent 自管理技能（skill_manage 工具）

Agent 可以通过 skill_manage 工具创建、更新和删除自己的技能。这是 Agent 的程序化记忆——当它发现一个复杂的工作流时，会将方法保存为技能以供将来复用。

Agent 何时创建技能

• 成功完成复杂任务（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

提示

patch 操作是更新时首选——它比 edit 更 Token 高效，因为只有更改的文本出现在工具调用中。

Skills Hub

浏览、搜索、安装和管理来自在线注册表、skills.sh、直接知名技能端点和官方可选技能。

常用命令

hermes skills browse                           # 浏览所有 Hub 技能（官方优先）
hermes skills browse --source official         # 仅浏览官方可选技能
hermes skills search kubernetes                # 搜索所有来源
hermes skills search react --source skills-sh  # 搜索 skills.sh 目录
hermes skills inspect openai/skills/k8s        # 安装前预览
hermes skills install openai/skills/k8s        # 安装（带安全扫描）
hermes skills install official/security/1password
hermes skills install https://sharethis.chat/SKILL.md  # 直接 URL
hermes skills list --source hub                # 列出 Hub 安装的技能
hermes skills check                            # 检查已安装 Hub 技能的上游更新
hermes skills update                           # 重新安装有上游变更的 Hub 技能
hermes skills audit                            # 重新扫描所有 Hub 技能的安全性
hermes skills uninstall k8s                    # 移除 Hub 技能
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo        # 添加自定义 GitHub 来源

支持的 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 搜索
well-known	well-known:https://mintlify.com/docs/.well-known/skills/mintlify	从网站 /.well-known/skills/index.json 提供的技能
url	https://sharethis.chat/SKILL.md	直接 HTTP(S) URL 到单文件 SKILL.md
github	openai/skills/k8s	直接 GitHub 仓库/路径安装和自定义 tap