hermes - 💡(How to fix) Fix Walk CLAUDE.md / AGENTS.md / .cursorrules to git root + auto-discover project-local skills

This issue started from a concrete code observation, but it surfaced a deeper design tension worth discussing before we talk about patches.

The surface-level gap

_find_hermes_md() in agent/context_files.py walks from cwd to git root looking for .hermes.md/HERMES.md. _load_claude_md(), _load_agents_md(), and _load_cursorrules() don't -- they check cwd only. The shared _find_git_root() infrastructure already exists, so the code change is small (~40 lines plus tests).

But the reason for the gap is architectural, not accidental.

The architectural tension

Hermes positions itself as a meta-agent. The autonomous-ai-agents skill category documents how to delegate coding tasks to Claude Code, OpenCode, or Codex via terminal or ACP. There is a dedicated ACP adapter for IDE integration. In this model, CLAUDE.md is Claude Code's project context, not Hermes's. Keeping Hermes from consuming it makes sense -- you don't want the orchestrator claiming the worker's config.

The reality of how people use Hermes

A survey of HN, Reddit, and GitHub discussions reveals a different picture:

• The dominant migration pattern is people switching TO Hermes from OpenClaw/OpenCode as their primary (often only) coding agent. "I switched to Hermes Agent and it's been night and day how much more stable and usable it is over OpenClaw." "Its amazing, its openclaw already set up and working."

• People describe Hermes as "OpenClaw that already works" -- they expect it to behave like the tool they came from. They want their repo's CLAUDE.md to be found automatically.

• The "orchestrator model" (Hermes plans, Claude Code executes) has virtually no public discussion. What exists is people using Hermes directly to edit files, run tests, and commit code -- the same way they'd use Claude Code.

• Use cases are broad: coding is number one, but personal productivity, self-hosting, and sysadmin are nearly as large. Many users run Hermes as a general-purpose agent, not a specialized coding orchestrator.

• A GitHub issue on the anthropics/claude-code repo (issue 53262) revealed that Claude Code was routing requests to "extra usage" billing whenever it detected "HERMES.md" in git commit messages -- an adversarial signal that these tools are seen as competitors, not complementary layers.

What this means for the feature

Walking CLAUDE.md / AGENTS.md / .cursorrules to git root does not conflict with the orchestrator model. The priority chain is unchanged -- .hermes.md still wins if present. The walk just extends the range at which each source is discoverable. If a user has .hermes.md at the repo root, nothing changes. If they have CLAUDE.md at the repo root and are cd'd into a subdirectory, they get their project context back.

The same logic applies to project-local skills. Scanning .hermes/skills/ from the git root is the obvious starting point. Optionally scanning .claude/skills/ bridges the migration gap further.

Proposed changes

1. Generalize _find_hermes_md() into a shared _find_project_file(names, cwd, stop_at_git_root=True) helper
2. Apply it to _load_agents_md, _load_claude_md, and _load_cursorrules
3. Add auto-discovery of skill directories from the git root (.hermes/skills/ and optionally .claude/skills/, .agent/skills/, etc)
4. Tests covering the new walking behavior

This makes Hermes immediately useful when pointed at an existing repo, regardless of which project context format the repo uses -- without sacrificing the native .hermes.md advantages. Happy to open a PR if this direction is endorsed.