Skip to content

feat: add Hermes Agent integration (skills workspaces + external_dirs)`#543

Open
justyork wants to merge 4 commits into
msitarzewski:mainfrom
justyork:feat/hermes-integration
Open

feat: add Hermes Agent integration (skills workspaces + external_dirs)`#543
justyork wants to merge 4 commits into
msitarzewski:mainfrom
justyork:feat/hermes-integration

Conversation

@justyork
Copy link
Copy Markdown

What does this PR do?

Adds Hermes Agent as a supported integration platform, following the same workspace model as OpenClaw.

  • scripts/convert.sh: shared write_agent_workspace() (SOUL / AGENTS / IDENTITY split) used by OpenClaw and Hermes; new convert_hermes() emits SKILL.md plus workspace files under integrations/hermes/<slug>/.
  • scripts/install.sh: install_hermes() copies workspaces to ~/.hermes/agency-agents/ and registers skills.external_dirs in ~/.hermes/config.yaml (safe in-place edit, not EOF append).
  • Docs: integrations/hermes/README.md, updates to root README.md, integrations/README.md, and CONTRIBUTING.md.
  • .gitignore: generated integrations/hermes/*/ excluded (only integrations/hermes/README.md is committed).

Each Agency agent becomes a Hermes skill discoverable via /skill-slug and hermes chat --toolsets skills, with persona/ops content loaded from bundled SOUL.md / AGENTS.md via ${HERMES_SKILL_DIR} (progressive disclosure).

Not included: generated skill workspaces (~184 directories); users run ./scripts/convert.sh --tool hermes locally.

Agent Information (if adding/modifying an agent)

N/A — this PR adds a tool integration, not a new agent markdown file.

Integration Information

Item Value
Platform Hermes Agent
Pattern OpenClaw-style per-agent workspace + Hermes SKILL.md entry point
Install target ~/.hermes/agency-agents/<slug>/
Discovery skills.external_dirs~/.hermes/agency-agents
Activation /frontend-developer, hermes chat --toolsets skills -q "Use the … skill …"

Motivation

Hermes uses a skills system (SKILL.md, agentskills.io-compatible) and understands SOUL.md / AGENTS.md, but only one global ~/.hermes/SOUL.md per instance. The Agency roster needs per-specialist personas, so a flat skill workspace per agent (with external_dirs) matches Hermes architecture better than a single monolithic skill or overwriting global SOUL.

Testing

Tested on two environments:

Environment Notes
Windows (Git Bash) convert.sh / install.sh; paths and workspace layout verified
Ubuntu 24.04 (VPS) Full pipeline + Hermes CLI; clean install after removing prior agency-agents paths and fixing config
./scripts/convert.sh --tool hermes   # → 184 workspaces under integrations/hermes/
bash -n scripts/convert.sh scripts/install.sh
./scripts/install.sh --tool hermes --no-interactive
  • Convert: 184 agents converted successfully (Windows and Ubuntu 24.04 VPS).
  • Install: 184 workspaces copied to ~/.hermes/agency-agents/.
  • Config: skills.external_dirs receives ~/.hermes/agency-agents under the skills: section. Installer replaces default external_dirs: [] with a valid block list (does not append list items after [] or at EOF).
  • Sample workspace (frontend-developer, ux-researcher): SKILL.md, SOUL.md, AGENTS.md, IDENTITY.md; ${HERMES_SKILL_DIR} in Procedure.
  • Git: only script/doc changes + integrations/hermes/README.md committed (no generated slug directories).

Ubuntu 24.04 VPS (Hermes CLI):

  • Clean reinstall: removed ~/.hermes/agency-agents and prior broken config lines, then convert + install again.
  • hermes skills list — Agency skills visible, no config.yaml parse errors.
  • Activating a skill (e.g. /ux-researcher) loads full bundled context (SOUL + AGENTS via skill procedure).
hermes skills list | grep -E 'frontend-developer|ux-researcher'
hermes chat --toolsets skills -q "Use the frontend-developer skill and summarize its role in one sentence."

Checklist

  • No generated integration output committed (only integrations/hermes/README.md)
  • convert.sh and install.sh updated; hermes added to tool lists / parallel convert
  • Documented in README.md and integrations/README.md
  • Tested convert.sh --tool hermes and install.sh --tool hermes on Windows (Git Bash) and Ubuntu 24.04 (VPS)
  • Tested with Hermes CLI on VPS (skills list, skill activation, full skill content)
  • Clean install path verified on VPS
  • OpenClaw converter refactored to shared write_agent_workspace() (no behavior change intended)
  • Follows the agent template structure from CONTRIBUTING.md (N/A — integration PR)
  • Includes YAML frontmatter with name, description, color (N/A — integration PR)
  • Has concrete code/template examples (for new agents) (N/A — integration PR)

Notes for maintainers

  • Aligns with CONTRIBUTING guidance for new platforms; happy to open a Discussion retroactively if preferred before merge.
  • ensure_hermes_external_dir() fixes (follow-up to initial integration):
    • Does not append - ~/.hermes/agency-agents at EOF of config.yaml.
    • Inserts under skills.external_dirs; replaces external_dirs: [] with block-list form.
    • Warns if agency-agents appears outside a valid external_dirs list (e.g. after external_dirs: []).
  • Recovery notes for broken configs: integrations/hermes/README.md (Fix broken config.yaml).

@justyork justyork mentioned this pull request May 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant