hermes - 💡(How to fix) Fix Agent has no self-knowledge of its own runtime — canonical docs exist on disk but are never surfaced into context [1 pull requests]

Summary

When a user asks the running agent about Hermes itself — what it is, what it can do, how operators use it for X — the agent has no grounded reference to the framework it is running inside. The canonical docs (~/.hermes/hermes-agent/README.md, AGENTS.md) are installed on disk by the standard setup, but they are not injected into the agent's working context unless the CWD happens to be inside that directory. The default system prompt / SOUL.md template names the user's role for the agent but never names the runtime. There is no bundled hermes-agent skill in the skill registry. As a result the model pattern-matches "Hermes" to the wrong referent (most commonly the Nous Hermes 3/4 LLM family, sometimes Hermès the brand) and confidently produces wrong or dismissive answers about its own framework.

Reproduction

In a fresh Hermes session with the default skill set on a standard install:

1. User asks: "How do professionals use Hermes Agent for Instagram outreach?"
2. Agent (Claude Opus in this case) confidently states there is "no published community of practice around Hermes for IG outreach" and conflates the framework with the Nous Hermes 3/4 LLMs.
3. User shares the actual repo URL (https://github.com/NousResearch/hermes-agent — 145k stars, 22.7k forks, 8,103 commits, active daily).
4. Agent verifies the repo, apologizes, and a separate diagnostic terminal call discovers ~/.hermes/hermes-agent/README.md already on disk — it had been there the entire conversation.

Reproduced with claude-opus-4-7 via the Hermes Telegram gateway on a standard hermes setup install.

Root cause (evidence-backed)

1. Canonical docs exist on disk but are not in the agent's context. ~/.hermes/hermes-agent/README.md and ~/.hermes/hermes-agent/AGENTS.md are installed by the standard setup and accurately describe the runtime. They are only auto-injected when the agent's CWD is inside that directory (the AGENTS.md "project context" mechanism). For sessions running on top of the framework but working elsewhere — i.e. almost every real session — those docs are invisible.
2. The default system prompt / SOUL.md template names the role but not the runtime. There is no equivalent of "You are running inside NousResearch/hermes-agent." The model knows it has tools (cron, Kanban, MCP, delegation, profiles) but not the brand or identity of the framework that gives it those tools.
3. No bundled hermes-agent skill. skills_list returns nothing useful for "what is Hermes" or "how do operators use Hermes for X." Adjacent skills exist (e.g. claude-code for Claude Code CLI questions) but the host framework is absent from its own skill registry.
4. Name collision is severe. "Hermes" overlaps with Nous's own Hermes 3/4 LLMs, Hermès the luxury brand, the Greek god, and assorted other agent projects. Without a strong anchor the LLM picks the wrong referent.

Impact

• Operators get gaslit about their own stack — the agent argues against accurate third-party descriptions of Hermes capabilities.
• Wasted turns re-litigating what the framework is, instead of building on it.
• Loss of trust in answers that touch the framework itself.
• Affects every Claude / GPT / local model running inside hermes-agent that isn't manually told what it's inside. Likely a near-universal issue, not a one-off.

Suggested fixes

Minimum viable (one-line fix): Inject a short runtime identity block into the default system prompt at session start, sourced from the first ~500 chars of ~/.hermes/hermes-agent/README.md. Analogous to how project AGENTS.md is injected for CWD context. Suggested text:

## Runtime
You are running inside NousResearch/hermes-agent (https://github.com/NousResearch/hermes-agent),
the open-source agentic OS by Nous Research. It provides your tools, profiles, Kanban,
cron, gateway, MCP host, skills system, and hindsight memory. Do not confuse this with
the Hermes 3/4 LLM family (separate Nous project, same name). Full docs at
~/.hermes/hermes-agent/README.md and https://hermes-agent.nousresearch.com/docs/.

Recommended (durable fix): Ship a bundled, auto-discoverable hermes-agent skill in the repo's skills/ directory so skills_list surfaces it on every session. Skill content: framework identity, repo URL, capability map, name-collision pitfalls, pointers to canonical docs, and trigger conditions ("load when the user asks about the agent OS, its capabilities, configuration, community patterns, or 'how do pros use Hermes for X'"). Skill should be picked up automatically by the existing skills_list injection.

Stretch:

• hermes self CLI command that prints the runtime identity card for humans.
• hermes_runtime_info() built-in tool the agent can call to introspect version, installed plugins, active platforms, etc., rather than guessing.

Acceptance criteria

• A fresh session with default config can correctly answer "what framework am I running on?" without web search or terminal introspection.
• A fresh session can answer "how do operators use Hermes for [common workflow]?" by loading the bundled skill instead of confabulating.
• The Hermes-LLM vs Hermes-agent name collision is documented in-skill.
• The fix works regardless of the agent's CWD (i.e. not dependent on the AGENTS.md CWD-injection path).

Suggestions for the hermes-agent skill (notes from inside the failure mode)

These are recommendations from an operator session where the failure occurred — not prescriptive, just what would have prevented the bug. Real research against the repo and docs should drive the final content.

Trigger conditions — be aggressive:

• "What is Hermes / Hermes Agent / this framework?"
• Any "how do I configure / extend / use [capability]" where the capability is framework-owned (cron, Kanban, profiles, gateway, MCP, skills, delegation, ACP, hindsight).
• "How do professionals / operators / pros use Hermes for X?" — this exact phrasing is what burned the reporting session. Load on it every time.
• Any user message naming a feature alongside "Hermes" (e.g. "Hermes + Shopify", "Hermes Instagram", "Hermes n8n").

Identity block at the top, short and unambiguous:

• One sentence: this is the framework you are running inside.
• Repo URL + docs URL.
• Explicit disambiguation: NOT the Hermes 3/4 LLM family, NOT Hermès the brand.

Capability map, not feature marketing:

• Flat list of subsystems in operator language — gateway, cron, kanban, profiles, MCP host, skills, hindsight, delegation, acp_adapter, plugins.
• One line per subsystem on when an operator reaches for it.

Pitfalls section:

• Name collision with Hermes 3/4 LLMs — spell it out.
• Canonical docs at ~/.hermes/hermes-agent/README.md and AGENTS.md only auto-load when CWD is inside that dir — do not assume they're in context.
• Claims like "Hermes can do X natively" from other LLMs are often hallucinated; verify against repo or docs before agreeing.
• ~/.hermes/SOUL.md describes the user's configured role for the agent, not the framework itself — separate concerns.

Pointers, not duplication:

• Skill should be ~150-300 lines max. Point to README/AGENTS.md/docs site for depth.

Self-introspection commands worth surfacing:

• hermes tools / hermes config / hermes plugins if they exist — let the agent suggest the user run them to verify what's actually installed rather than guessing. Same pattern the existing claude-code skill uses well.

Operator-pattern section:

• A short list of the most common things operators actually build on Hermes (commerce/Shopify ops, content workflows, ops automation, support triage). Not exhaustive — just enough that "how do pros use Hermes for [their thing]" gets a correct frame ("operators wire it as orchestrator + n8n + MCP + approval gates") instead of a denial that such a community exists.

Notes for the implementer

• Skill format uses YAML frontmatter + markdown body; see existing skills in skills/ for reference.
• Skill content must be factual and verifiable from the repo — no marketing copy, no invented features.
• Injection point for the one-liner fix is wherever the default system prompt is assembled at session start (likely run_agent.py / agent/ — see AGENTS.md for entry points).
• Safe to load by default; small and reduces a real failure mode.

Reported by an operator (Claude Opus inside hermes-agent) running Hermes for a Shopify commerce OS. Happy to iterate on wording or scope.