Skills 系统

Skills 是 agent 可以在需要时加载的按需知识文档。它们遵循渐进式披露模式以最小化 token 使用量，并与 agentskills.io 开放标准兼容。

所有 skills 存在于 ~/.hermes/skills/ — 主要目录和真实来源。在全新安装时，捆绑的 skills 会从仓库复制。Hub 安装和 agent 创建的 skills 也放在这里。agent 可以修改或删除任何 skill。

您还可以将 Hermes 指向外部 skill 目录 — 与本地目录一起扫描的其他文件夹。请参阅下面的 外部 Skill 目录。

另请参阅：

• 捆绑 Skills 目录
• 官方可选 Skills 目录

使用 Skills

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

# 在 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

# 只需 skill 名称会加载它并让 agent 询问您需要什么：
/excalidraw

捆绑的 plan skill 是一个带有自定义行为的 skill 支持斜杠命令的好例子。运行 /plan [request] 告诉 Hermes 在需要时检查上下文，写一个 markdown 实现计划而不是执行任务，并将结果保存到活动工作目录/backend 工作目录下的 .hermes/plans/ 中。

您也可以通过自然对话与 skills 交互：

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

渐进式披露

Skills 使用 token 高效的加载模式：

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)

Agent 仅在实际需要时才加载完整的 skill 内容。

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.

平台特定 Skills

Skills 可以使用 platforms 字段将自己限制在特定操作系统上：

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

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

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

条件激活（回退 Skills）

Skills 可以根据当前会话中哪些工具可用自动显示或隐藏自己。这对于回退 skills 最有用 — 应该是免费或本地替代品，仅在高级工具不可用时出现。

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

字段	行为
fallback_for_toolsets	当列出的工具集可用时，Skill 被隐藏。当它们缺失时显示。
fallback_for_tools	相同，但检查单个工具而不是工具集。
requires_toolsets	当列出的工具集不可用时，Skill 被隐藏。当它们存在时显示。
requires_tools	相同，但检查单个工具。

示例： 内置的 duckduckgo-search skill 使用 fallback_for_toolsets: [web]。当您设置了 FIRECRAWL_API_KEY 时，web 工具集可用，agent 使用 web_search — DuckDuckGo skill 保持隐藏。如果 API 密钥缺失，web 工具集不可用，DuckDuckGo skill 自动显示为回退。

没有条件字段的 Skills 的行为与之前完全相同 — 它们始终显示。

加载时的安全设置

Skills 可以声明所需的环境变量而不会从发现中消失：

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 中加载 skill 时才安全地询问它。您可以跳过设置并继续使用 skill。消息平台永远不会在聊天中询问密钥 — 它们告诉您使用 hermes setup 或 ~/.hermes/.env 在本地。

设置后，声明的 env 变量会自动传递到 execute_code 和 terminal 沙箱 — skill 的脚本可以直接使用 $TENOR_API_KEY。对于非 skill env 变量，请使用 terminal.env_passthrough 配置选项。请参阅 Environment Variable Passthrough 了解详细信息。

Skill 配置设置

Skills 还可以声明非密钥配置设置（路径、偏好），存储在 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 显示它们。当 skill 加载时，其解析的配置值会被注入上下文，以便 agent 自动知道配置的值。

请参阅 Skill 设置 和 Creating Skills — Config Settings 了解详细信息。

Skill 目录结构

~/.hermes/skills/                  # 单一真实来源
├── mlops/                         # 类别目录
│   ├── axolotl/
│   │   ├── SKILL.md               # 主要说明（必需）
│   │   ├── references/            # 附加文档
│   │   ├── templates/             # 输出格式
│   │   ├── scripts/               # 可从 skill 调用的辅助脚本
│   │   └── assets/                # 补充文件
│   └── vllm/
│       └── SKILL.md
├── devops/
│   └── deploy-k8s/                # Agent 创建的 skill
│       ├── SKILL.md
│       └── references/
├── .hub/                          # Skills Hub 状态
│   ├── lock.json
│   ├── quarantine/
│   └── audit.log
└── .bundled_manifest                # 跟踪种子捆绑 skills

外部 Skill 目录

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

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

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

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

工作原理

• 只读：外部目录仅用于 skill 发现扫描。当 agent 创建或编辑 skill 时，它始终写入 ~/.hermes/skills/。
• 本地优先：如果同一 skill 名称同时存在于本地目录和外部目录中，本地版本获胜。
• 完全集成：外部 skills 出现在系统提示索引、skills_list、skill_view 和作为 /skill-name 斜杠命令中 — 与本地 skills 没有区别。
• 不存在的路径被静默跳过：如果配置的目录不存在，Hermes 无错误地忽略它。对于可能不在每台机器上存在的可选共享目录很有用。

示例

~/.hermes/skills/               # 本地（主要，读写）
├── devops/deploy-k8s/
│   └── SKILL.md
└── mlops/axolotl/
    └── SKILL.md

~/.agents/skills/               # 外部（只读，共享）
├── my-custom-workflow/
│   └── SKILL.md
└── team-conventions/
    └── SKILL.md

所有四个 skills 都出现在您的 skill 索引中。如果您在本地创建一个名为 my-custom-workflow 的新 skill，它会遮盖外部版本。

Agent 管理的 Skills（skill_manage 工具）

Agent 可以通过 skill_manage 工具创建、更新和删除自己的 skills。这是 agent 的程序记忆 — 当它弄清楚一个非平凡的工作流时，它将方法保存为 skill 以供将来重用。

Agent 何时创建 Skills

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

操作

操作	用于	关键参数
create	从头开始新 skill	name、content（完整 SKILL.md）、可选 category
patch	针对性修复（首选）	name、old_string、new_string
edit	主要结构性重写	name、content（完整 SKILL.md 替换）
delete	完全移除 skill	name
write_file	添加/更新支持文件	name、file_path、file_content
remove_file	移除支持文件	name、file_path

提示

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

Skills Hub

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

常用命令

hermes skills browse                              # 浏览所有 hub skills（官方优先）
hermes skills browse --source official            # 仅浏览官方可选 skills
hermes skills search kubernetes                   # 搜索所有来源
hermes skills search react --source skills-sh     # 搜索 skills.sh 目录
hermes skills search https://mintlify.com/docs --source well-known
hermes skills inspect openai/skills/k8s           # 安装前预览
hermes skills install openai/skills/k8s           # 使用安全扫描安装
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                   # 列出 hub 安装的 skills
hermes skills check                               # 检查已安装 hub skills 的上游更新
hermes skills update                              # 需要时使用上游更改重新安装 hub skills
hermes skills audit                               # 重新扫描所有 hub skills 的安全性
hermes skills uninstall k8s                       # 移除 hub skill
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills snapshot export setup.json          # 导出 skill 配置
hermes skills tap add myorg/skills-repo           # 添加自定义 GitHub 来源

支持的 hub 来源

来源	示例	备注
official	official/security/1password	与 Hermes 一起提供的可选 skills。
skills-sh	skills-sh/vercel-labs/agent-skills/vercel-react-best-practices	可通过 hermes skills search <query> --source skills-sh 搜索。当 skills.sh slug 与 repo 文件夹不同时，Hermes 解析别名样式 skills。
well-known	well-known:https://mintlify.com/docs/.well-known/skills/mintlify	直接从网站上的 /.well-known/skills/index.json 提供的 skills。不是单一集中式 hub — 它是一种 Web 发现约定。
github	openai/skills/k8s	直接 GitHub repo/path 安装和自定义 taps。
clawhub、lobehub、claude-marketplace	特定于来源的标识符	社区或市场集成。

集成的 hub 和注册表

Hermes 目前与这些 skills 生态系统和发现来源集成：

1. 官方可选 skills（official）

这些在 Hermes 仓库本身中维护，安装时具有内置信任。

• 目录：Official Optional Skills Catalog
• Repo 来源：optional-skills/
• 示例：

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

2. skills.sh（skills-sh）

这是 Vercel 的公共 skills 目录。Hermes 可以直接搜索它、检查 skill 详情页面、解析别名样式 slug，并从底层源 repo 安装。

• 目录：skills.sh
• CLI/工具 repo：vercel-labs/skills
• 官方 Vercel skills repo：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 skill 端点（well-known）

这是来自发布 /.well-known/skills/index.json 的网站的基于 URL 的发现。它不是单一集中式 hub — 它是一种 Web 发现约定。

• 示例实时端点：Mintlify docs skills index
• 参考服务器实现：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 skills（github）

Hermes 可以直接从 GitHub 仓库和基于 GitHub 的 taps 安装。当您已经知道 repo/path 或想要添加自己的自定义源 repo 时，这很有用。

默认 taps（无需任何设置即可浏览）：

• openai/skills

• anthropics/skills

• VoltAgent/awesome-agent-skills

• garrytan/gstack

• 示例：

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

5. ClawHub（clawhub）

作为社区来源集成的第三方 skills 市场。

• 网站：clawhub.ai
• Hermes 来源 ID：clawhub

6. Claude marketplace 风格 repos（claude-marketplace）

Hermes 支持发布 Claude 兼容插件/市场清单的市场 repos。

已知的集成来源包括：

• anthropics/skills
• aiskillstore/marketplace

Hermes 来源 ID：claude-marketplace

7. LobeHub（lobehub）

Hermes 可以从 LobeHub 的公共目录搜索和转换 agent 条目为可安装的 Hermes skills。

• 网站：LobeHub
• 公共 agents 索引：chat-agents.lobehub.com
• 支持 repo：lobehub/lobe-chat-agents
• Hermes 来源 ID：lobehub

安全扫描和 --force

所有 hub 安装的 skills 都会经过安全扫描器检查数据泄露、提示注入、破坏性命令、供应链信号和其他威胁。

hermes skills inspect ... 现在在可用时也显示上游元数据：

• repo URL
• skills.sh 详情页 URL
• 安装命令
• 每周安装数
• 上游安全审计状态
• well-known 索引/端点 URL

当您审查了第三方 skill 并想覆盖非危险策略阻止时，使用 --force：

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

重要行为：

• --force 可以覆盖 caution/warn 样式发现的政策阻止。
• --force 不会覆盖 dangerous 扫描裁决。
• 官方可选 skills（official/...）被视为内置信任，不显示第三方警告面板。

信任级别

级别	来源	政策
builtin	与 Hermes 一起提供	始终受信任
official	Repo 中的 optional-skills/	内置信任，无第三方警告
trusted	受信任的注册表/repos，如 openai/skills、anthropics/skills	比社区来源更宽松的政策
community	其他所有内容（skills.sh、well-known 端点、自定义 GitHub repos、大多数市场）	非危险发现可以用 --force 覆盖；dangerous 裁决保持阻止

更新生命周期

hub 现在跟踪足够的来源信息来重新检查已安装 skills 的上游副本：

hermes skills check          # 报告哪些已安装 hub skills 在上游有更改
hermes skills update         # 仅重新安装有可用更新的 skills
hermes skills update react   # 更新一个特定的已安装 hub skill

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

GitHub 速率限制

Skills hub 操作使用 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

官方可选 skills 仍使用标识符如 official/security/1password 和 official/migration/openclaw-migration。