hermes - 💡(How to fix) Fix Feature: native skill metadata / discovery contract for adapter hosts [1 participants]

Summary

Hermes Agent (when used as a Paperclip adapter via hermes-paperclip-adapter) has no native mechanism to discover or surface attached skills to the model. claude_local agents get .claude/skills/ filesystem discovery; Hermes agents get nothing equivalent. The result: Hermes agents in Paperclip don't know what skills they have attached and can't reach for them by name.

This is distinct from #4667 (project-local filesystem discovery). That issue is about Hermes discovering skills from paths on disk in the working directory. This issue is about adapter hosts (like Paperclip) that manage a curated skill set via API — there is no filesystem path to discover, only an API-provided list — and need a runtime contract for injecting that list into Hermes.

Reproduce

1. Configure a Paperclip agent with adapterType: hermes_local and attach a skill (any) via the Paperclip skills API.
2. Trigger a heartbeat run.
3. Inspect the spawned Hermes process: no env var, no file, no prompt section tells the agent which skills are available.
4. The agent operates blind to its skill set — it can use MCPs/tools but can't be told "you have skill X for purpose Y."

Workaround

We poll the Paperclip skills API at deploy time and write a TOOLS.md file into the agent's instructions bundle directory:

SKILLS=$(curl -H "Authorization: Bearer $BOARD_API_KEY" \
  "$PAPERCLIP_API/agents/$AGENT_ID/skills" | jq -r '...')
printf "## Available skills\n\n%s" "$SKILLS" > "$INSTRUCTIONS_DIR/TOOLS.md"

Then a separate patch makes Hermes read AGENTS.md/SOUL.md/HEARTBEAT.md/TOOLS.md from the instructions directory and prepend to the prompt.

Brittle:

1. TOOLS.md drifts the moment skills change without a redeploy.
2. The skill list is a flat blob; Hermes has no abstraction for "skill" so the model can't reason about them as discrete capabilities.

Proposed direction

Hermes adds skill metadata to its agent runtime contract. Either:

• An env var / config that points at a directory of skill files (analogous to .claude/skills/) — letting adapter hosts write skill files into a tmpdir at spawn time and pass the path.
• A structured prompt-section concept (similar to MCP prompt resources) so adapters can pass per-skill metadata that the model treats as discrete capabilities.
• An HERMES_INJECTED_SKILLS_DIR env var the adapter sets at spawn time, with Hermes treating that dir as a read-only, pre-populated skills source (no hermes skills install needed).

Not unique to Paperclip — any host attaching curated skills to a Hermes agent will need this.

Why we care

We run 6 Hermes agents in production handling client-facing work; their not-knowing-which-skills-they-have leads to consistent under-utilization of available capabilities and forces us to over-specify in AGENTS.md (itself a workaround for this gap).