From 9af4d391f342a447bffe4b750d10c38036db9d84 Mon Sep 17 00:00:00 2001 From: dongmucat <70678707+dongmucat@users.noreply.github.com> Date: Wed, 22 Jul 2026 15:01:50 +0800 Subject: [PATCH] docs(integrations): add Hermes Agent skill guide (#584) * docs(integrations): add Hermes skill guide Signed-off-by: dongmucat <1127093059@qq.com> * docs(integrations): clarify Hermes skill collision handling Signed-off-by: dongmucat <1127093059@qq.com> --------- Signed-off-by: dongmucat <1127093059@qq.com> --- README.md | 6 + README_zh.md | 6 + docs/hermes-integration-en.md | 278 ++++++++++++++++++++++++++++++++++ docs/hermes-integration.md | 278 ++++++++++++++++++++++++++++++++++ 4 files changed, 568 insertions(+) create mode 100644 docs/hermes-integration-en.md create mode 100644 docs/hermes-integration.md diff --git a/README.md b/README.md index d47ef5cc..2b068ab9 100644 --- a/README.md +++ b/README.md @@ -436,6 +436,12 @@ namespace `my-space` plus skill slug `my-skill`. 📖 **[Complete OpenClaw Integration Guide →](./docs/openclaw-integration.md)** +### [Hermes Agent](https://github.com/NousResearch/hermes-agent) + +[Hermes Agent](https://github.com/NousResearch/hermes-agent) uses the standard `SKILL.md` format and recursively discovers skills under `$HERMES_HOME/skills/`. Use SkillHub CLI's explicit `--dir` option to install a complete SkillHub package into Hermes without a registry adapter, then verify it with `hermes skills list`. + +📖 **[Complete Hermes Agent Integration Guide →](./docs/hermes-integration-en.md)** + ### [AstronClaw](https://agent.xfyun.cn/astron-claw) [AstronClaw](https://agent.xfyun.cn/astron-claw) is a cloud AI assistant built on OpenClaw's core capabilities, providing 24/7 online service through enterprise platforms like WeChat Work, DingTalk, and Feishu. It features a built-in skill system with over 130 official skills. You can connect it to a self-hosted SkillHub registry to enable one-click skill installation, search repository, dialogue-based automatic installation, and even custom skills management within your organization. diff --git a/README_zh.md b/README_zh.md index 80e65b75..42fb8225 100644 --- a/README_zh.md +++ b/README_zh.md @@ -370,6 +370,12 @@ namespace `my-space` 和 skill slug `my-skill`。 📖 **[完整 OpenClaw 集成指南 →](./docs/openclaw-integration.md)** +### [Hermes Agent](https://github.com/NousResearch/hermes-agent) + +[Hermes Agent](https://github.com/NousResearch/hermes-agent) 使用标准 `SKILL.md` 格式，并会递归发现 `$HERMES_HOME/skills/` 中的技能。通过 SkillHub CLI 的 `--dir` 参数即可把完整技能包安装到 Hermes，无需新增 registry 适配器；安装后可使用 `hermes skills list` 验证。 + +📖 **[完整 Hermes Agent 集成指南 →](./docs/hermes-integration.md)** + ### [AstronClaw](https://agent.xfyun.cn/astron-claw) [AstronClaw](https://agent.xfyun.cn/astron-claw) 是基于 OpenClaw 核心能力打造的云端 AI 助手，提供全天候在线服务，随时随地通过企业微信、钉钉、飞书等渠道提供服务。它内置了丰富的技能系统，您可以将其连接到自托管的 SkillHub 注册中心，支持技能市场一键安装、仓库搜索、对话自动安装，甚至管理和分发组织内部的自定义私有技能。 diff --git a/docs/hermes-integration-en.md b/docs/hermes-integration-en.md new file mode 100644 index 00000000..5c4031d8 --- /dev/null +++ b/docs/hermes-integration-en.md @@ -0,0 +1,278 @@ +# Hermes Agent Integration Guide + +This guide explains how to install skills from SkillHub into [NousResearch Hermes Agent](https://github.com/NousResearch/hermes-agent), then discover, load, update, and remove those skills in Hermes. + +“Hermes” in this guide means `NousResearch/hermes-agent`; it does not cover other projects with the same name. + +## Validated scope + +| Component | Validated version | Notes | +|-----------|-------------------|-------| +| SkillHub Server | `v0.2.13` | Public or self-hosted registry | +| SkillHub CLI | `0.1.8` | npm package `@astron-team/skillhub` | +| Hermes Agent | `0.18.2` | Upstream tag [`v2026.7.7.2`](https://github.com/NousResearch/hermes-agent/tree/v2026.7.7.2) | + +Validation date: 2026-07-17. + +Hermes 0.18.2 uses an [Agent Skills](https://agentskills.io/)-compatible `SKILL.md` format and recursively scans `$HERMES_HOME/skills/`. SkillHub CLI can extract a complete skill package into any explicit `--dir` target. The current integration therefore needs no format conversion, Hermes-specific CLI profile, or server adapter: + +```text +SkillHub registry + -> skillhub install --dir + -> //SKILL.md + -> Hermes discovers and loads the skill on demand +``` + +> Hermes 0.18.2 has no native SkillHub registry source. This guide uses SkillHub CLI for search, download, and local installation, while Hermes handles discovery and execution. + +## Prerequisites + +1. Install and initialize Hermes Agent. +2. Install SkillHub CLI: + +```bash +npm install -g @astron-team/skillhub + +skillhub version +hermes version +``` + +3. Ensure the skill package has a valid root `SKILL.md` with at least `name` and `description` frontmatter. + +The examples below use Bash/zsh. On Windows, use the same directory structure, replace the default Hermes home with `$HOME\.hermes`, and set variables using PowerShell syntax. + +## Quick start + +### 1. Configure the SkillHub registry + +Set the public or self-hosted SkillHub URL: + +```bash +export SKILLHUB_REGISTRY=https://skillhub.your-company.com +``` + +You can skip login for public skills that allow anonymous downloads. For team namespaces, restricted skills, or private deployments, save an API token first: + +```bash +skillhub login \ + --registry "$SKILLHUB_REGISTRY" \ + --token YOUR_API_TOKEN + +skillhub whoami --registry "$SKILLHUB_REGISTRY" +``` + +Use placeholder tokens in examples. Never write a real token into `SKILL.md`, scripts, or version control. + +### 2. Search for a skill + +```bash +skillhub search "pdf" --registry "$SKILLHUB_REGISTRY" +``` + +Record the namespace, slug, and required version. The following examples use `my-team/my-skill`: + +```bash +export SKILLHUB_NAMESPACE=my-team +export SKILLHUB_SKILL=my-skill +``` + +### 3. Install into the primary Hermes skills directory + +Set the home of the active Hermes profile. The default profile normally uses `~/.hermes`; if you use a custom `HERMES_HOME` or a named profile, point it at the actual profile directory: + +```bash +export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}" +export HERMES_SKILLHUB_DIR="$HERMES_HOME/skills/skillhub/$SKILLHUB_NAMESPACE" +``` + +Install the skill: + +```bash +skillhub install "$SKILLHUB_SKILL" \ + --namespace "$SKILLHUB_NAMESPACE" \ + --dir "$HERMES_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" +``` + +SkillHub CLI preserves `SKILL.md`, `references/`, `scripts/`, `templates/`, `assets/`, and other package files. It also writes `.skillhub/metadata.json` to record the installation source. The resulting layout looks like this: + +```text +$HERMES_HOME/skills/ +└── skillhub/ + └── my-team/ + └── my-skill/ + ├── SKILL.md + ├── references/ # optional + ├── scripts/ # optional + └── .skillhub/ + └── metadata.json +``` + +Separating target directories by namespace reduces filesystem collisions between skills with the same slug. Hermes recursively scans these levels. + +### 4. Verify and load the skill in Hermes + +First, confirm that Hermes discovers the skill: + +```bash +hermes skills list --source local --enabled-only +``` + +Then start Hermes and invoke the slash command normalized from the skill `name`: + +```bash +hermes +``` + +```text +/my-skill +``` + +You can also ask Hermes in natural language to use the skill. Hermes lists the raw `SKILL.md` frontmatter `name`, but its slash command lowercases that name, replaces spaces and underscores with hyphens, removes other characters outside `a-z0-9-`, and collapses repeated hyphens. For example, `PDF_Tools` becomes `/pdf-tools`. The command may therefore differ from the SkillHub slug. + +If a running session does not immediately show a new skill, run `/reload-skills` or restart the session. + +## Update a skill + +SkillHub CLI 0.1.8 overwrites a local skill by repeating the install command with `--force`. Omitting `--version` resolves the latest published version; you can also pin one explicitly: + +```bash +skillhub install "$SKILLHUB_SKILL" \ + --namespace "$SKILLHUB_NAMESPACE" \ + --dir "$HERMES_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" \ + --force + +# Pinned version example +skillhub install "$SKILLHUB_SKILL" \ + --namespace "$SKILLHUB_NAMESPACE" \ + --version 1.2.0 \ + --dir "$HERMES_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" \ + --force +``` + +Review the new version before overwriting because `--force` replaces the existing skill directory. Afterward, run: + +```bash +skillhub list \ + --dir "$HERMES_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" + +hermes skills list --source local --enabled-only +``` + +> `skillhub update` updates SkillHub CLI itself; it does not update installed skills. Refresh an installed skill with `skillhub install ... --force`. + +## Remove a skill + +First, list every installation from the same registry and confirm that there are no other same-slug skills you need to keep: + +```bash +skillhub list \ + --registry "$SKILLHUB_REGISTRY" +``` + +Then remove the local installation: + +```bash +skillhub remove "$SKILLHUB_SKILL" \ + --registry "$SKILLHUB_REGISTRY" +``` + +SkillHub CLI deletes both the skill directory and the local inventory record. Local `remove` in this version matches only registry and slug; it does not filter by namespace or directory. Every same-slug target from that registry, across all namespaces and installation directories, is removed. If the unfiltered `skillhub list` shows a match you need to keep, do not run the command; namespace- or directory-scoped removal requires a future CLI capability. + +After removal, run `/reload-skills`, restart the Hermes session, or confirm that the skill is gone with: + +```bash +hermes skills list --source local --enabled-only +``` + +## Optional: use a shared external skills directory + +When several agents share `~/.agents/skills`, install SkillHub skills into that shared tree instead of the primary Hermes directory: + +```bash +export SHARED_SKILLHUB_DIR="$HOME/.agents/skills/skillhub/$SKILLHUB_NAMESPACE" + +skillhub install "$SKILLHUB_SKILL" \ + --namespace "$SKILLHUB_NAMESPACE" \ + --dir "$SHARED_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" +``` + +Merge the shared root into `$HERMES_HOME/config.yaml` without replacing existing `skills` settings: + +```yaml +skills: + external_dirs: + - ~/.agents/skills +``` + +Hermes lists and loads external skills alongside local skills. Do not rely on local shadowing: Hermes 0.18.2 refuses ambiguous `skill_view` matches across the local skills directory and `external_dirs`. Rename or remove a colliding copy instead. + +> `external_dirs` is not a read-only boundary. If the Hermes process can write to an external directory, Hermes skill-management tools can modify its files. Use filesystem permissions or an isolated Hermes profile when shared skills must remain read-only. + +## Compatibility and security boundaries + +- **Format compatibility is not complete runtime compatibility.** Hermes can read `SKILL.md` and supporting files, but agent-specific tools, MCP servers, commands, environment variables, and platform capabilities referenced by a skill still need individual verification. +- **Hermes treats this path as local.** A skill copied by SkillHub CLI does not run through the Hermes Skills Hub community-install scanner. Review the SkillHub security report and the skill contents before installation, and use Hermes terminal isolation where appropriate. +- **Keep multi-file packages intact.** Do not replace SkillHub CLI with the Hermes 0.18.2 direct-URL source for multi-file skills. That release guarantees a single `SKILL.md` for URL installs, whereas SkillHub CLI extracts the complete package. +- **Avoid name collisions.** Namespace-separated filesystem paths do not resolve slash-command collisions. Keep normalized command names unique within one Hermes profile. For example, `PDF Tools` and `pdf_tools` both become `/pdf-tools`. +- **Protect credentials.** A registry token is only for SkillHub access and does not belong in a skill package. Skills that need runtime secrets should use Hermes environment-variable and security settings. + +## Troubleshooting + +### The new skill is missing from the Hermes list + +Check these items in order: + +1. The current session uses the same `HERMES_HOME` used during installation. +2. The final path contains `/SKILL.md`. +3. `SKILL.md` contains valid `name` and `description` fields. +4. `platforms` or other frontmatter does not exclude the current operating system. +5. The skill appears after `/reload-skills` or in a new session. + +```bash +skillhub list --dir "$HERMES_SKILLHUB_DIR" --registry "$SKILLHUB_REGISTRY" +hermes skills list --source local +``` + +### Installation reports `skill already installed` + +Existing directories are not overwritten by default. Review the target version, then add `--force`: + +```bash +skillhub install "$SKILLHUB_SKILL" \ + --namespace "$SKILLHUB_NAMESPACE" \ + --dir "$HERMES_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" \ + --force +``` + +### The CLI reports `registry unreachable` or a download failure + +- Confirm that `SKILLHUB_REGISTRY` is the SkillHub root URL. +- Run `skillhub search` against the same registry to distinguish registry reachability from a download failure. +- Check proxy, DNS, certificate, and self-hosted service status. +- Retry a transient network error only after confirming the service is healthy; do not bypass certificate failures by disabling TLS verification. + +### The skill is listed but fails during execution + +Check tool names, shell commands, script runtimes, packages, MCP servers, environment variables, and operating-system restrictions referenced by that skill. Those are skill-specific runtime compatibility concerns, not failures of `SKILL.md` discovery. + +### Can `hermes skills install` consume a SkillHub coordinate directly? + +Hermes 0.18.2 has no SkillHub registry source and cannot resolve a SkillHub namespace/slug directly. Use `skillhub install --dir ...` as shown in this guide. Native search, installation, updates, and security scanning inside Hermes would require a separately designed Hermes source adapter with its own protocol and acceptance scope. + +## Regression checks after upgrades + +After upgrading SkillHub CLI or Hermes, verify at least the following: + +1. `skillhub install --dir` still creates `/SKILL.md` and preserves support files. +2. `hermes skills list --source local --enabled-only` discovers the skill. +3. `/skill-name` loads `SKILL.md` and exposes support-file paths; then read one referenced file with `skill_view(name, file_path)` or exercise the script/asset the skill actually uses. +4. `skillhub install --force` overwrites the skill while keeping a healthy inventory. +5. Hermes no longer discovers the skill after `skillhub remove`. + +Upstream reference: [Hermes Skills System at v0.18.2](https://github.com/NousResearch/hermes-agent/blob/v2026.7.7.2/website/docs/user-guide/features/skills.md). diff --git a/docs/hermes-integration.md b/docs/hermes-integration.md new file mode 100644 index 00000000..25743bfd --- /dev/null +++ b/docs/hermes-integration.md @@ -0,0 +1,278 @@ +# Hermes Agent 集成指南 + +本文档说明如何把 SkillHub 中的技能安装到 [NousResearch Hermes Agent](https://github.com/NousResearch/hermes-agent)，并在 Hermes 中发现、加载、更新和移除这些技能。 + +本文中的 “Hermes” 特指 `NousResearch/hermes-agent`，不适用于其他同名项目。 + +## 已验证范围 + +| 组件 | 已验证版本 | 说明 | +|------|------------|------| +| SkillHub Server | `v0.2.13` | 公开或自托管 registry | +| SkillHub CLI | `0.1.8` | npm 包 `@astron-team/skillhub` | +| Hermes Agent | `0.18.2` | 上游 tag [`v2026.7.7.2`](https://github.com/NousResearch/hermes-agent/tree/v2026.7.7.2) | + +验证日期：2026-07-17。 + +Hermes 0.18.2 使用兼容 [Agent Skills](https://agentskills.io/) 的 `SKILL.md` 格式，并递归扫描 `$HERMES_HOME/skills/`。SkillHub CLI 可以通过 `--dir` 把完整技能包解压到指定目录。因此，当前兼容链路不需要格式转换、Hermes 专用 CLI profile 或服务端适配： + +```text +SkillHub registry + -> skillhub install --dir + -> //SKILL.md + -> Hermes 发现并按需加载 +``` + +> Hermes 0.18.2 没有原生 SkillHub registry source。本指南使用 SkillHub CLI 负责搜索、下载和本地安装，Hermes 负责发现和执行技能。 + +## 前置条件 + +1. 已安装并初始化 Hermes Agent。 +2. 已安装 SkillHub CLI： + +```bash +npm install -g @astron-team/skillhub + +skillhub version +hermes version +``` + +3. 技能包根目录包含有效的 `SKILL.md`，其中至少有 `name` 和 `description` frontmatter。 + +以下示例使用 Bash/zsh。Windows 用户可使用同一目录结构，将默认 Hermes 主目录替换为 `$HOME\.hermes`，并按 PowerShell 语法设置变量。 + +## 快速开始 + +### 1. 配置 SkillHub registry + +设置公开或自托管 SkillHub 地址： + +```bash +export SKILLHUB_REGISTRY=https://skillhub.your-company.com +``` + +公开且允许匿名下载的技能可以跳过登录。访问团队命名空间、受限技能或私有部署时，先保存 API Token： + +```bash +skillhub login \ + --registry "$SKILLHUB_REGISTRY" \ + --token YOUR_API_TOKEN + +skillhub whoami --registry "$SKILLHUB_REGISTRY" +``` + +请使用占位 Token 演示，不要把真实 Token 写入 `SKILL.md`、脚本或版本库。 + +### 2. 搜索技能 + +```bash +skillhub search "pdf" --registry "$SKILLHUB_REGISTRY" +``` + +记录结果中的 namespace、slug 和所需版本。下面以 `my-team/my-skill` 为例： + +```bash +export SKILLHUB_NAMESPACE=my-team +export SKILLHUB_SKILL=my-skill +``` + +### 3. 安装到 Hermes 主技能目录 + +设置当前 Hermes profile 的主目录。默认 profile 通常是 `~/.hermes`；如果使用自定义 `HERMES_HOME` 或命名 profile，请指向实际 profile 目录： + +```bash +export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}" +export HERMES_SKILLHUB_DIR="$HERMES_HOME/skills/skillhub/$SKILLHUB_NAMESPACE" +``` + +安装技能： + +```bash +skillhub install "$SKILLHUB_SKILL" \ + --namespace "$SKILLHUB_NAMESPACE" \ + --dir "$HERMES_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" +``` + +SkillHub CLI 会保留技能包中的 `SKILL.md`、`references/`、`scripts/`、`templates/`、`assets/` 等文件，并额外写入 `.skillhub/metadata.json` 记录安装来源。目录结构类似： + +```text +$HERMES_HOME/skills/ +└── skillhub/ + └── my-team/ + └── my-skill/ + ├── SKILL.md + ├── references/ # 可选 + ├── scripts/ # 可选 + └── .skillhub/ + └── metadata.json +``` + +按 namespace 分目录可以减少不同命名空间中同 slug 技能的文件路径冲突。Hermes 会递归扫描这些层级。 + +### 4. 在 Hermes 中验证和加载 + +先确认 Hermes 发现了技能： + +```bash +hermes skills list --source local --enabled-only +``` + +然后启动 Hermes，在会话中使用由技能 `name` 规范化得到的斜杠命令： + +```bash +hermes +``` + +```text +/my-skill +``` + +也可以在自然语言请求中明确要求 Hermes 使用该技能。Hermes 列表显示 `SKILL.md` frontmatter 中的原始 `name`，斜杠命令会把它转为小写、把空格和下划线替换为连字符、移除其他非 `a-z0-9-` 字符，并合并重复连字符。例如 `PDF_Tools` 对应 `/pdf-tools`。该命令不一定与 SkillHub slug 相同。 + +已经运行的会话未立即显示新技能时，执行 `/reload-skills` 或重新启动会话。 + +## 更新技能 + +SkillHub CLI 0.1.8 使用同一安装命令加 `--force` 覆盖本地技能。省略 `--version` 会解析最新已发布版本；也可以显式固定版本： + +```bash +skillhub install "$SKILLHUB_SKILL" \ + --namespace "$SKILLHUB_NAMESPACE" \ + --dir "$HERMES_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" \ + --force + +# 固定版本示例 +skillhub install "$SKILLHUB_SKILL" \ + --namespace "$SKILLHUB_NAMESPACE" \ + --version 1.2.0 \ + --dir "$HERMES_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" \ + --force +``` + +覆盖前请先审查新版本，因为 `--force` 会替换现有技能目录。更新后重新运行： + +```bash +skillhub list \ + --dir "$HERMES_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" + +hermes skills list --source local --enabled-only +``` + +> `skillhub update` 更新的是 SkillHub CLI 自身，不会更新已安装技能。已安装技能使用 `skillhub install ... --force` 刷新。 + +## 移除技能 + +先列出同一 registry 中的全部安装，确认没有其他需要保留的同 slug 技能： + +```bash +skillhub list \ + --registry "$SKILLHUB_REGISTRY" +``` + +再移除本地安装： + +```bash +skillhub remove "$SKILLHUB_SKILL" \ + --registry "$SKILLHUB_REGISTRY" +``` + +SkillHub CLI 会同时删除技能目录和本地 inventory 记录。当前版本的本地 `remove` 仅按 registry 和 slug 匹配，不按 namespace 或目录过滤；同一 registry 下所有 namespace、所有安装目录中的相同 slug 都会被移除。如果未过滤的 `skillhub list` 中存在需要保留的匹配项，请不要执行该命令；按 namespace 或目录精确移除需要后续 CLI 能力支持。 + +移除后，使用 `/reload-skills`、重启 Hermes 会话，或运行以下命令确认技能已消失： + +```bash +hermes skills list --source local --enabled-only +``` + +## 可选：使用共享的 external skill 目录 + +如果多个 Agent 共用 `~/.agents/skills`，可以把 SkillHub 技能安装到共享目录，而不是 Hermes 主目录： + +```bash +export SHARED_SKILLHUB_DIR="$HOME/.agents/skills/skillhub/$SKILLHUB_NAMESPACE" + +skillhub install "$SKILLHUB_SKILL" \ + --namespace "$SKILLHUB_NAMESPACE" \ + --dir "$SHARED_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" +``` + +然后把共享根目录合并到 `$HERMES_HOME/config.yaml`，不要覆盖已有的 `skills` 配置： + +```yaml +skills: + external_dirs: + - ~/.agents/skills +``` + +Hermes 会把 external skill 与本地技能一起列出和加载。不要依赖本地技能覆盖 external skill：Hermes 0.18.2 会拒绝加载本地技能目录与 `external_dirs` 之间存在歧义的 `skill_view` 匹配；请改名或移除其中一个冲突副本。 + +> `external_dirs` 不是只读边界。只要 Hermes 进程拥有写权限，Hermes 的技能管理工具就可能修改其中的文件。共享目录需要只读保护时，请使用文件系统权限或隔离的 Hermes profile。 + +## 兼容性与安全边界 + +- **格式兼容不等于运行时完全兼容。** Hermes 能读取 `SKILL.md` 和配套文件，但技能引用的 Agent 专用工具、MCP server、命令、环境变量或平台能力仍需逐项验证。 +- **Hermes 将此路径识别为 local skill。** 通过 SkillHub CLI 复制到本地的技能不会经过 Hermes Skills Hub 的 community 安装扫描。安装前应查看 SkillHub 安全报告并审查技能内容，必要时使用 Hermes 的终端隔离能力。 +- **保留多文件包。** 不要把多文件 SkillHub 技能改成 Hermes 0.18.2 的直接 URL 安装；该版本的 URL source 只保证单个 `SKILL.md`，而 SkillHub CLI 会解压完整包。 +- **避免名称冲突。** 文件路径按 namespace 隔离仍不能解决斜杠命令冲突；同一 Hermes profile 内应保持规范化后的命令名唯一。例如 `PDF Tools` 和 `pdf_tools` 都会变成 `/pdf-tools`。 +- **保护凭证。** Token 只用于 SkillHub registry 访问，不应写进技能包。需要运行时 secret 的技能应遵循 Hermes 的环境变量和安全设置方式。 + +## 常见问题 + +### Hermes 列表中没有新技能 + +依次检查： + +1. 当前会话的 `HERMES_HOME` 是否与安装时一致。 +2. 最终路径下是否存在 `/SKILL.md`。 +3. `SKILL.md` 是否包含有效的 `name` 和 `description`。 +4. `platforms` 等 frontmatter 是否排除了当前操作系统。 +5. 执行 `/reload-skills` 或启动新会话后是否出现。 + +```bash +skillhub list --dir "$HERMES_SKILLHUB_DIR" --registry "$SKILLHUB_REGISTRY" +hermes skills list --source local +``` + +### 安装提示 `skill already installed` + +已有目录默认不会被覆盖。先审查目标版本，再增加 `--force`： + +```bash +skillhub install "$SKILLHUB_SKILL" \ + --namespace "$SKILLHUB_NAMESPACE" \ + --dir "$HERMES_SKILLHUB_DIR" \ + --registry "$SKILLHUB_REGISTRY" \ + --force +``` + +### 提示 `registry unreachable` 或下载失败 + +- 核对 `SKILLHUB_REGISTRY` 是否是 SkillHub 根地址。 +- 先运行同一 registry 的 `skillhub search` 判断 registry 是否可达。 +- 检查代理、DNS、证书和自托管服务状态。 +- 短暂网络错误可以在确认服务正常后重试；不要通过关闭 TLS 校验绕过证书问题。 + +### 技能已列出但执行失败 + +检查技能引用的工具名称、shell 命令、脚本解释器、依赖包、MCP server、环境变量和操作系统限制。此类问题属于具体技能的运行时兼容性，不代表 `SKILL.md` 发现链路失败。 + +### 能否直接运行 `hermes skills install` 安装 SkillHub 坐标？ + +Hermes 0.18.2 没有 SkillHub registry source，不能直接解析 SkillHub 的 namespace/slug。请使用本指南中的 `skillhub install --dir ...`。如果未来需要 Hermes 内原生搜索、安装、更新和安全扫描，应单独设计 Hermes source adapter，并重新定义协议和验收范围。 + +## 升级后的回归检查 + +升级 SkillHub CLI 或 Hermes 后，至少重新验证： + +1. `skillhub install --dir` 仍生成 `/SKILL.md` 并保留配套文件。 +2. `hermes skills list --source local --enabled-only` 能发现技能。 +3. `/skill-name` 能加载 `SKILL.md` 并暴露配套文件路径；再通过 `skill_view(name, file_path)` 读取一个实际引用文件，或执行技能使用的脚本/资产验证其运行时路径。 +4. `skillhub install --force` 能覆盖更新且 inventory 正常。 +5. `skillhub remove` 后 Hermes 不再发现该技能。 + +上游参考：[Hermes Skills System（v0.18.2）](https://github.com/NousResearch/hermes-agent/blob/v2026.7.7.2/website/docs/user-guide/features/skills.md)。