Problem or Use Case

Hermes' core value proposition is the learning loop: skills improve through use via skill_manage (patch/edit actions). However, the current update lifecycle for hub-installed and bundled skills has a blind spot: hermes skills update reinstalls upstream content based on content hash drift detection against lock.json, with no awareness of whether the local copy was modified by the agent since installation.

This means:

1. Agent adapts a hub-installed skill via skill_manage patch: improving a procedure, adding a pitfall it discovered, refining trigger conditions
2. Upstream provider publishes an update
3. hermes skills check detects hash drift (upstream hash ≠ lock.json hash)
4. hermes skills update reinstalls the upstream version, silently overwriting all agent learnings

The same applies to bundled skills on hermes update (git pull), since bundled skills are seeded from the repo into ~/.hermes/skills/ via .bundled_manifest with no local-modification tracking.

This creates a perverse incentive: the more Hermes improves an externally-sourced skill, the more value is destroyed on the next update. In practice, this undermines self-improvement for any skill the agent didn't create from scratch.

Related: Issue #861 (provenance mislabeling) surfaces part of the same gap: if the system can't reliably distinguish where a skill came from, it also can't know what changed locally.

Proposed Solution

Introduce a lightweight diff/merge layer into the skill update lifecycle:

1. Snapshot on install/update: When a hub skill is installed or updated, store the upstream content hash and a copy of the original content (or a hash of it) in .hub/lock.json or a parallel manifest. This becomes the "common ancestor" for future merges.
2. Detect local modifications on update: Before reinstalling, compare the current local SKILL.md against the stored install-time snapshot. If they differ, the skill has been locally adapted (by the agent or user).
3. Three-way merge for non-conflicting changes: When both upstream and local have changed, diff each against the common ancestor. Apply non-overlapping changes from both sides automatically.
4. Conflict handling: For overlapping changes, either:

• Flag the conflict and present both versions to the user/agent for resolution
• Let the agent re-evaluate its local adaptations against the new upstream context (a scoped self-improvement pass)
• Fall back to keeping the local version with the upstream diff available for manual review

5. Metadata extension: Add fields to the lock entry: installed_content_hash (what was installed), local_content_hash (current state), locally_modified: bool. This also helps skills list mislabels local skills as builtin #861 by making provenance and modification state explicit.

Alternatives Considered

No response

Feature Type

Other

Scope

Medium (few files, < 300 lines)

Contribution

• I'd like to implement this myself and submit a PR