The user flagged that nowhere in the documentation do we guide users
through installing and configuring Hermes Agent itself with our skills.
PR #678 covered the technical integration but missed this user-facing
step.
Additions to docs/integrations.md Hermes Agent section:
**Step 1 — Install Hermes Agent itself (NEW)**
- macOS/Linux: 5-step setup (clone → venv → deps → .env → first run)
- Windows: WSL2 guidance
- Docker: one-liner with $HOME/.hermes volume mount
- Provider note: works with Nous, OpenAI, Anthropic, or any
OpenAI-compatible endpoint (no Nous account required)
**Step 3 — First-run walkthrough (NEW)**
- Complete dry-run from cold install to first skill invocation
- Examples: /skills, /research <query>, /skill_view, /skills search
- Shows how our orchestrator routing surfaces in Hermes UX
**Configuration tips (NEW)**
- Sample ~/.hermes/config.yaml block with our skill paths
- auto_load recommendations (karpathy-coder always-on, grill-me sparingly)
- display: show_category for grouping by claude-skills/<domain>/
**Troubleshooting (NEW — 6 Q&A entries)**
1. /skills shows 0 results after sync (target path + permissions)
2. Symlinks point to wrong path (cross-machine portability — relative
symlinks per v2.7.2+)
3. Slash command collisions (Hermes built-ins vs claude-skills)
4. ModuleNotFoundError on Python tools (3.10+ requirement)
5. SKILL.md not found despite file existing (nested-plugin flatten via
sync script)
6. How to unsync (rm -rf ~/.hermes/skills/claude-skills/)
Also bumped verify count: 198+ → 303 (v2.7.2+) so the post-sync
sanity check now expects accurate numbers.
https://claude.ai/code/session_01FEUmeuYhmnxVFq7EZM8ZSw
The user flagged that we advertise Hermes Agent as a tier-1 supported
platform in the "Works with:" list, but the actual integration was
significantly thinner than Codex/Gemini/OpenClaw:
- No committed .hermes/ tree (other platforms ship pre-generated trees)
- sync-hermes-skills.py DOMAIN_DIRS missing the 3 v2.7.0 top-level
domains (productivity, marketing, research) — running it today would
silently skip all 13 v2.7.0 skills
- Discover function only handled the flat `<domain>/<skill>/` pattern,
missing the nested-plugin pattern `<domain>/<plugin>/skills/<skill>/`
used by all v2.7.0 skills + many older plugins
- Doc count stale at "198+ skills" / "246 skills"
- 35 Hermes mentions vs Codex 1010 / Gemini 622 / OpenClaw 572 —
under-documented relative to the marketing claim
This commit upgrades Hermes to first-class technical support while
labeling it BYO-sync in marketing (honest about the workflow:
pre-generated tree shipped, but user runs sync into ~/.hermes/ once).
**scripts/sync-hermes-skills.py changes:**
1. DOMAIN_DIRS extended with `productivity`, `marketing`, `research`
(the 3 v2.7.0 top-level domains)
2. `discover_skills()` rewritten to handle all 3 SKILL.md location
patterns (same logic as sync-codex-skills.py):
- Pattern 1: `<domain>/<skill>/SKILL.md` (flat legacy)
- Pattern 2: `<domain>/skills/<skill>/SKILL.md` (flat with skills/)
- Pattern 3: `<domain>/<plugin>/skills/<skill>/SKILL.md` (nested plugin)
Dedupes by SKILL.md path.
3. `sync_skill()` now creates RELATIVE symlinks (via os.path.relpath)
instead of absolute. Critical for committed .hermes/ tree to work
across machines. Falls back to absolute if cross-device.
**.hermes/skills/claude-skills/ tree committed:**
- 289 relative symlinks across 12 domains
- skills-index.json (303 skills documented with descriptions)
- All v2.7.0 skills present: productivity (4), marketing (1),
research (8)
**Documentation refresh:**
- docs/integrations.md:
- Header count: 246 → 311 skills
- Hermes section: NEW "Tier: BYO-sync" tip box explaining the
pre-generated tree + the one-line install step
- Install table: "198+ skills" → "303 skills (12 domains)"
- README.md:
- Hermes Agent entry in "Works with:" line now flagged with [^hermes]
footnote explicitly labeling it BYO-sync tier with link to the
sync script
Verification:
- Script smoke-test: `python3 sync-hermes-skills.py --target .hermes/skills --verbose`
→ 303 skills discovered, 289 new symlinks, 14 skipped (pre-existing)
- All v2.7.0 symlinks resolve correctly:
`.hermes/skills/claude-skills/research/research → ../../../../research/research/skills/research`
- 12 domains present in tree (was 9 before)
Per CLAUDE.md ClawHub rules: this PR does NOT update marketplace.json
(Hermes is not on ClawHub). The .hermes/ tree is repo-side
infrastructure only.
https://claude.ai/code/session_01FEUmeuYhmnxVFq7EZM8ZSw
