feat(skills): add Hermes-format skill under skills/hermes/, extend vetting sweeps to cover it

[ashutoshsinghpr7]

Summary

Adds a Hermes-format skill for ripwire — a distilled Hermes-native counterpart to the ripwire-orient family — and extends the two vetting sweeps so a namespaced skill like it is scanned like the flat set, not silently skipped.

No C++ or behavior change. Diff: 2 new files + 2 sweep-glob lines.

Why a Hermes skill

Hermes Agent is a shell-capable coding agent ("if your agent can run shell commands, it is set up"): its skills are agentskills.io-style SKILL.md files under ~/.hermes/skills/. The added skill teaches a Hermes agent when to reach for ripwire instead of grep-and-read: orienting in an unfamiliar repo, the --for task lens, --callers blast radius, --test-gate before committing, resuming work after context compaction. Its honesty-signals section mirrors ripwire's own disclosure model (confidence=/margin_pct=, --skipped, amb=) so an agent reads a map the way the tool wants it read.

Why skills/hermes/ and not skills/ripwire-*

skills/install.sh symlinks every skills/ripwire-* directory into Claude Code / Codex skill roots. A Hermes-format file must not be auto-installed into those agents — wrong frontmatter dialect for them, and it would pollute the routed ripwire-* set. The hermes/ namespace is invisible to that glob (verified: for d in "$src"/ripwire-*/), so Claude/Codex installs are untouched.

Sweep coverage (the second half of this PR)

skillscan.sh check 9 and deckcheck.sh globbed only skills/*/SKILL.md, so skills/hermes/ripwire-repo-map/SKILL.md would have silently escaped both gates — the green-while-inert shape deckcheck.sh's own header exists to prevent. Both now include the depth-3 pattern skills/*/*/SKILL.md.

Verified locally against a plain cmake build (macOS arm64):

• bash test/skillscan.sh → ALL PASS, 19/19 shipped skills scan clean — the new file is swept and scans attack-clean.
• bash test/deckcheck.sh → ALL PASS — 55 prose sources, 272 distinct --flag tokens, 0 fabricated, 0 bad values.

Notes for review

• The frontmatter description is intentionally one line: Hermes indexes skill descriptions into every session's system prompt, so the trigger matrix lives in the body. allowed-tools is omitted for the same reason — Hermes validates against a fixed frontmatter key set.
• Not added to the release-tarball packaging (the release lane copies ripwire-* only); Hermes users install from the repo as documented in skills/hermes/README.md. Happy to include it in the tarball if you'd prefer.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 8ae0c257-4d93-4866-8d5d-6b7bed5b8b6e

📥 Commits

Reviewing files that changed from the base of the PR and between 6488f6f and ac18da4.

📒 Files selected for processing (4)

• skills/hermes/README.md
• skills/hermes/ripwire-repo-map/SKILL.md
• test/deckcheck.sh
• test/skillscan.sh

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• New Features

  • Added Hermes-compatible documentation for the ripwire-repo-map skill, including setup instructions, supported commands, usage guidance, and troubleshooting details.
  • Added instructions for installing the skill into a Hermes profile.

• Bug Fixes

  • Skill validation now detects and counts skills stored in nested, agent-specific directories, ensuring Hermes-format skills are included in shipped-skill checks.

Walkthrough

Adds a Hermes-format ripwire-repo-map skill, documents its installation and usage, and updates skill validation scripts to scan nested skill paths.

Changes

Hermes skill support

Layer / File(s)	Summary
Define the Hermes ripwire skill skills/hermes/README.md, skills/hermes/ripwire-repo-map/SKILL.md	Documents the Hermes namespace, installation, ripwire commands, output signals, pitfalls, and references.
Scan nested skill files test/deckcheck.sh, test/skillscan.sh	Updates skill scans to include nested SKILL.md files.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to ac18d

This adds a Hermes repository-mapping skill and ensures nested skills are included in the existing validation sweeps. No concrete current-head merge risk remains.

Suggested reviewers: joyful-ii-v-i

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the new Hermes skill and the related vetting-sweep updates.
Description check	✅ Passed	The description directly explains the Hermes skill, its namespace, sweep changes, rationale, and verification results.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[joyful-ii-V-I]

Thank you for this, and apologies for the silence — you deserved a status note before now rather than an open PR with nothing on it.

Where it stands honestly: this is queued, not ignored, and it is not blocked on anything wrong with the PR. Skill-activation targets touch how the installer writes configuration outside its own prefix, so the order we add them in is a decision I want to make deliberately rather than in the order PRs arrive. There is also a sequencing question on our side that isn't mine alone to answer, and I'd rather tell you that than invent a technical reason.

I'm not going to give you a date I can't keep. What I can say is that nothing here is a rejection, the PR stays open, and when the ordering question is settled this gets a real review — the same one #57 is getting today: full gate battery, sanitizers, and an adversarial pass rather than just the happy path.

If you'd rather not wait on that, say so and I'll prioritise differently. Leaving a contributor hanging is the failure mode I'm most trying to avoid here.

[ashutoshsinghpr7]

Thanks for the status note — honestly appreciated, and no apology needed. This kind of transparency is exactly what keeps contributors around.

To make the sequencing decision easier: nothing in this PR requires installer integration. The skill is namespaced under skills/hermes/ specifically so the ripwire-* glob in skills/install.sh can never touch it, and the README documents a plain cp -r install into ~/.hermes/skills/. So if the open question is the order in which agent-activation targets get added, this can land without committing you to any Hermes-aware installer change — or hold until that's settled, either works for us. We're not blocked: the skill is already live in my own Hermes setup, so this PR is purely about co-location and discoverability for other Hermes users.

And no rush on prioritising differently — the PR can sit in the queue until the sequencing question is resolved.

[joyful-ii-V-I]

One factual question, and it changes the shape of what I land rather than anything about your PR.

I am refactoring the agent wiring in src/wrap.h into a table — one row per agent, because agent identity is currently branched on in ~30 places across 7 files and your PR and #51 both had to touch most of them. Adding an agent should be a row, not a branch, and that makes both of yours smaller.

One column is whether the agent can shell out. Where it can, we recommend the CLI over MCP, because the CLI costs zero context until it is invoked while a registered MCP server's verb schemas sit in the model's context every turn whether a verb is called or not (measured, docs/EVALS.md §5). That is why the opencode recipe leads with the shell path.

Does Hermes have a shell/terminal/exec tool available to the agent at run time?

Your SKILL.md says "Invoke it via the terminal tool", which suggests yes — but that is your text, and I would rather ask than infer a platform fact from a sentence I am about to build a recommendation on. If yes, Hermes joins codex, opencode and openclaw on a shared CLI-first recipe rather than getting its own. If no, it stays MCP-wired and that is fine too.

Also useful if you know it: does Hermes ignore unknown frontmatter keys? Your skill carries version, author, license, platforms, metadata.hermes.* and prerequisites, where ripwire's existing eighteen skills carry only name: and description:. If the extras are optional, the eighteen work in Hermes unchanged, and I would rather install those than maintain a nineteenth hand-written copy that will drift from them.

No rush, and nothing here is a criticism of the PR — the hook-slot detail #51 found is exactly the kind of platform fact this table needs.

[joyful-ii-V-I]

Merged — thank you, this is a well-judged contribution.

Three calls here were the right ones, and none of them are obvious:

The namespace decision. Putting this under skills/hermes/ rather than skills/ripwire-* keeps skills/install.sh from ever symlinking a Hermes-format skill into a Claude Code or Codex skill root. Verified rather than assumed: a --codex install into a throwaway HOME deploys 0 Hermes directories. You reasoned about a glob's blast radius before writing the file, which is the step most people skip.

Extending the sweeps in the same PR. A namespaced skill that the vetting sweeps silently skipped would have been strictly worse than no skill — it would ship unvetted while looking covered. Landing the skills/*/*/SKILL.md globs alongside the file is exactly the house rule.

The prose is honest. "Do NOT use for trivial single-file lookups (plain rg/search_files wins)" and "--help is authoritative" are the two sentences that make a skill trustworthy rather than promotional. I checked all 19 flags the skill names against --help expecting to find a fabrication — every one is real.

---

One thing I fixed on the way in, so you know it happened. The full gate battery caught skillevalcheck.sh failing: it enumerates skills with find -maxdepth 1 -type d, so it counted the namespace hermes as a skill, found it had zero labelled rows in the routing corpus, and went red. Third of three sweeps — you updated the two that were greppable for skills/*; this one's glob didn't look like the others.

Landed as a separate commit (5e96a6a5) rather than folded into yours: a skill is now defined as a directory that contains a SKILL.md, which is correct for any future namespace without another edit there.

One integration note, not a change request. #51 adds a --hermes installer mode deploying skills/ripwire-* into ${HERMES_HOME:-~/.hermes}/skills. That glob does not match skills/hermes/, so once both land, --hermes installs the Claude/Codex-format skills into a Hermes profile while the skill purpose-built for Hermes still needs the manual cp from your README. A seam between two PRs rather than a defect in either — better resolved when #51 lands. Views very welcome; you and @AnkitArya know Hermes' skill loading far better than I do.

Worth saying plainly: nobody maintaining this repo runs Hermes. Everything we ship for it is verified against documentation, not against a running agent. If you're ever able to run the two prompts from that skill against real Hermes and tell us what actually happened — especially if it goes badly — that is the single most useful thing anyone could contribute to this corner of the repo right now.

[ashutoshsinghpr7]

It's merged, but for the question's and live run on hermes:

Q1 — Shell/terminal: yes, natively. Hermes agents have a first-class terminal tool; the agent that ran this whole exchange (fork, gates, sweep edits, this test) executed every command through it. MCP is also supported natively (hermes mcp), so Hermes can be MCP-wired — but CLI-first is the better fit for the same reason your table column exists: a skill is just instructions the agent loads on demand, and ripwire costs zero context until the agent actually runs it via the shell. Hermes belongs in the codex/opencode/openclaw column.

Q2 — Unknown frontmatter keys: yes, ignored; name + description is the full legal minimum. I didn't infer this — I tested it. Fresh isolated HERMES_HOME, every ripwire-* skill on current main copied verbatim (their exact frontmatter — name, folded long description, allowed-tools):

17/17 loaded, all enabled, zero warnings or parse errors. allowed-tools is silently tolerated.

So the flat set works in Hermes unchanged (17 on current main — the v0.4.0 tarball shipped 18; ripwire-efficient has since been consolidated), and installing them beats a hand-written nineteenth on drift — agreed. Three findings from the test that a docs-only pass wouldn't have surfaced, for the --hermes work in #51:

• Description length is a routing constraint, not just style. Hermes lists every installed skill's description in the agent's context each session, truncated at ~57 chars + …. ripwire-orient's is 325 chars — it survives because it opens with the trigger ("Landing COLD in an unfamiliar repo…"). Skills whose first 57 chars are boilerplate would route poorly. This is also why the Hermes skill's description is deliberately one line.

• Flat companion files are invisible to a Hermes agent. Four of the seventeen ship companions beside SKILL.md (fresh-eyes/lint-rules.md, mcp/mcp-reference.md, quality-bar/quality-metrics.md, orient/compress-ladder.md + map-before-you-read.md) — and all four bodies reference theirs by name. Hermes auto-exposes only references/, templates/, scripts/ subdirs as loadable files. Bodies inline enough to work standalone, but --hermes would serve better mapping companions into references/.

• Several bodies carry client-isms. ripwire-mcp leads with ripwire wrap claude → claude mcp add + mcp__ripwire__ tool names; router/navigate describe install.sh symlinking into ~/.claude/skills. Harmless dead text in Hermes — but it's exactly the noise that argues for a Hermes-shaped entry point on top of the 17: in Claude, ripwire-router does the cross-skill routing; in Hermes, routing happens in the skill index, and what the agent sees matters more than what's installed.

On the seam: once #51 lands, I'd suggest having its --hermes mode install the distilled skill alongside the 17 (all proven loadable above). The installer's ripwire-* glob deliberately skips skills/hermes/, so the mode would need to name it explicitly — worth it because the distilled skill is the client-agnostic entry point (no claude mcp add/hook text, description sized for Hermes' 57-char index) that routes into the family for depth. Drift risk is real but bounded: it defers to --help and the family skills, so its maintenance surface is small. If you'd rather not carry a nineteenth at all, happy to retire it in favor of the 17 — your call.

And the prompts challenge — done, live. A real Hermes agent ran both core invocations from the skill against a real repo (Vibe-Trading 77k edges):

• --report → full architecture map (modules, god-files, cycles, top symbols) in 1.17s wall.

• --for="place an order through a broker connector and track fills" → ranked place_order 1, TradingPlaceOrderTool 2, execute_live_order 3, est_tokens=3644 for the whole bundle. The lens itself labels that head confidence=low (flat ranking — the tool's own honesty signal for "starting point, not answer").

One wobble worth reporting rather than hiding: a shell+docs-only repo mapped with zero call-graph edges — disclosed in the output itself (0 edges, isolates listed), so no agent can mistake the map for a connected codebase.