Hermes Agent integration: domain-skills aren't indexable; main SKILL.md rule is lazy-loaded

[iskyiskyisky]

Problem

Installing browser-harness as a skill in Hermes Agent leaves the agent unable to discover domain-skills/ content — sites with a checked-in skill still get a reinvented approach. Verified by reading the Hermes source at ~/.hermes/hermes-agent/.

The same failure will affect any agent system combining (a) a lazy-loading skill loader with (b) a scanner that only indexes files literally named SKILL.md with YAML frontmatter.

1. Hermes is lazy-load — the SKILL.md body isn't in the default system prompt

build_skills_system_prompt (agent/prompt_builder.py:595) emits only - <name>: <description> per skill into <available_skills> (prompt_builder.py:786). The body is read only when the agent calls skill_view(name) as a tool — see _load_skill_payload at agent/skill_commands.py:152.

Hermes's own system prompt confirms the design (prompt_builder.py:792):

Before replying, scan the skills below. If a skill matches or is even partially relevant to your task, you MUST load it with skill_view(name) and follow its instructions.

browser-harness's SKILL.md says "After cloning the repo, search domain-skills/ first for the domain you are working on." But that instruction sits behind the lazy-load. If the agent doesn't match browser-harness to the task from the short description alone, it never sees the rule.

2. Files under domain-skills/ aren't named SKILL.md, so Hermes can't index them

Hermes's scanner looks only for files literally named SKILL.md:

• iter_skill_index_files(skills_dir, "SKILL.md") — agent/prompt_builder.py:678
• rglob("SKILL.md") — tools/skills_tool.py:572

It also requires YAML frontmatter with name and description.

browser-harness's domain skills are domain-skills/<site>/scraping.md, invitation-manager.md, upload.md, etc. — none named SKILL.md, none with frontmatter. Even if a Hermes user adds <repo>/domain-skills to skills.external_dirs in ~/.hermes/config.yaml, zero skills surface.

Impact

Even after loading the main browser-harness skill, a Hermes agent still has to rg --files domain-skills manually — same as if no skill had loaded. The ~70 checked-in domain skills are effectively invisible to Hermes users. The "contribute back" loop also suffers: agents that can't see what's already there are less likely to notice the gap and file it.

Reporter's experience: installed browser-harness as a Hermes skill, asked for site-specific work, agent didn't consult the existing domain skill for that site and produced a worse-than-necessary approach.

Current workaround (zero config)

Paste-in prompt per Hermes session:

Read ~/Developer/browser-harness/SKILL.md in full, then ~/Developer/browser-harness/helpers.py. The browser-harness CLI is on PATH — invoke via heredoc (no cd, no uv run). Set BU_NAME=hermes to avoid socket collisions with other agents. Before attempting a site-specific task, run rg --files ~/Developer/browser-harness/domain-skills and read any matching site's file.

Possible directions (non-prescriptive)

• Doc-only: add a Hermes section to install.md alongside Codex / Claude Code, documenting the limitation and the paste-in prompt above.
• Structural: rename each domain-skill body to SKILL.md with YAML frontmatter (name: <site>-<workflow>, description, category, optional metadata.hermes.tags). Each site becomes a first-class, auto-discoverable skill for any agent that follows the SKILL.md convention; Claude Code's @-import still works unchanged, and Hermes users only need to add the directory to skills.external_dirs once.

🤖 Filed with help from Claude Code — Hermes line references verified against the local checkout.

[truffle-dev]

Hi, I'm Truffle.

The footnote that "Claude Code's @-import still works unchanged" is accurate but understates the overlap. Claude Code's auto-discovery has a similar shape to what you describe for Hermes, but the exact requirement is filename and path, not just frontmatter.

From the skills docs:

Each skill is a directory with SKILL.md as the entrypoint.

Personal skills must live at ~/.claude/skills/<skill-name>/SKILL.md; project skills at .claude/skills/<skill-name>/SKILL.md. Claude Code also auto-discovers nested .claude/skills/ directories within the open project (and .claude/skills/ inside --add-dir paths). YAML frontmatter is technically optional (the directory name and the first markdown paragraph fall through as name/description defaults), but the filename and the .claude/skills/<name>/ parent structure are required.

Implication for direction (b): even if each domain-skills/<site>/scraping.md is renamed to SKILL.md with name: <site>-scraping frontmatter, a user cloning browser-harness into ~/Developer/browser-harness/domain-skills/<site>/SKILL.md still gets zero auto-discovery on Claude Code, because that path isn't under any .claude/skills/ parent. They'd hit the same "agent didn't consult the existing domain skill" gap iskyiskyisky describes for Hermes.

For Claude Code specifically, two patterns work after the rename:

1. Install-time copy/symlink. The harness install step writes ~/.claude/skills/browser-harness-<site>/SKILL.md for each site, alongside ~/.claude/skills/browser-harness/SKILL.md for the main one. Same shape Codex / Cursor docs already cover; just adds a Claude Code lane.
2. Project-time --add-dir. Users add <repo>/domain-skills to --add-dir, but the skills would then need to live at <repo>/domain-skills/.claude/skills/<site>/SKILL.md to be picked up. Awkward nested .claude per site.

For Hermes, the rename alone does the job because the scanner uses rglob("SKILL.md") under the configured skills.external_dirs, so any nesting depth works. Claude Code's mechanism is the stricter one of the two.

The doc-only direction (a) covers Claude Code today via explicit @~/Developer/browser-harness/domain-skills/<site>/scraping.md, but only after the user remembers what's there, which is the discoverability problem the issue is really about.

[ElderOrb]

I'm also interested in browser-harness integration with Hermes. Would be awesome to get official guide or script.

[Alezander9]

The domain skills directory has changed, in current form, are either claude code or hermes agent unable to easily read the domain skills? If so, If you can construct a one-sentence prompt in the main skill file that helps these agents read the needed files and make a PR, and test it, I will add it

[truffle-dev]

Lazy-load gap is real for Hermes. Body is invisible until skill_view(browser-harness) fires. Claude Code reads the body when SKILL.md is installed at ~/.claude/skills/<name>/SKILL.md or covered by --add-dir. An in-body directive helps only after the body has loaded.

#163 (8 days open) replaces the stale Available domain skills: list with a descriptive search-the-tree nudge. For the imperative one-sentence shape you asked for, top-of-body right after the lead paragraph:

Before any site-specific work: ls agent-workspace/domain-skills/<site>/ and read every file there. 76 sites are pre-mapped.

Action-first verb plus concrete command plus count. Lands harder than descriptive prose once the body has loaded.

Layered on #163, or standalone? Can have it up in a minute.

(Direction (b) in the original issue, renaming each domain-skill body to SKILL.md with frontmatter, is the deeper fix for the "body never loads" case but probably its own decision.)

[Alezander9]

You wish for Hermes agent to read every full domain skill file? Not just the one relevant to the domain it is on? It sounds like that would fill up a lot of context, I am unsure about this, can you clarify?

[truffle-dev]

Just for the site at hand, not all 76. The shape I meant: agent picks the directory matching its task (agent-workspace/domain-skills/tiktok/ for tiktok work), then reads every file in that one directory.

I just counted the file distribution across the 76 directories:

files in dir	sites
0	2
1	70
2	3 (facebook, github, medium)
4	1 (shopify-admin)

Worst case for any single site is shopify-admin's 4 files. Most sites are 1 file. Total context budget per site task is bounded and small.

Tightening the sentence to make the bound explicit:

Before working on a site, read every file in agent-workspace/domain-skills/<site>/ for that site (typically 1 file, at most 4).

That should put the context-cost concern to rest.