skillhub/docs/hermes-integration-en.md

Hermes Agent Integration Guide

This guide explains how to install skills from SkillHub into 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

Validation date: 2026-07-17.

Hermes 0.18.2 uses an Agent Skills-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:

SkillHub registry
  -> skillhub install --dir <Hermes skills directory>
  -> <Hermes skills directory>/<skill-slug>/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:

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:

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:

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

skillhub search "pdf" --registry "$SKILLHUB_REGISTRY"

Record the namespace, slug, and required version. The following examples use my-team/my-skill:

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:

export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
export HERMES_SKILLHUB_DIR="$HERMES_HOME/skills/skillhub/$SKILLHUB_NAMESPACE"

Install the skill:

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:

$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:

hermes skills list --source local --enabled-only

Then start Hermes and invoke the slash command normalized from the skill name:

hermes

/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:

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:

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:

skillhub list \
  --registry "$SKILLHUB_REGISTRY"

Then remove the local installation:

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:

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:

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:

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-directory>/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.

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:

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 <slug>/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.