hermes - 💡(How to fix) Fix Feature: policy-driven local skill overlays and profile sync preflight

Feature request

Add first-class support for policy-driven local skill overlays and profile skill sync preflight.

This is related to, but more focused than, broader skill lifecycle/status work. It covers the operational gap for users who run multiple Hermes profiles and need a safe way to keep selected shared skills consistent without losing local customizations or accidentally shadowing delegated skill directories.

Motivation

Multi-profile Hermes setups can have several legitimate skill layers:

1. Bundled/upstream skills shipped by Hermes
2. User-authored local skills
3. Local overlays/pins for update-sensitive customizations
4. Profile-local skill copies or forks
5. External skill dirs shared across profiles
6. Disabled/absorbed skills that should stay present but not load

Today, it is difficult to answer these questions before an update or profile sync:

• Is this skill bundled, user-authored, locally modified, overlaid, profile-copied, or profile-forked?
• Will hermes update skip upstream improvements because a bundled skill was locally edited?
• Which profile copies have drifted from the intended canonical skill?
• Which differences are intentional forks vs stale copies?
• Will syncing bundled skills into a profile collide with skills.external_dirs and create duplicate skill names?
• Can I check this in CI/watchdog mode without mutating anything?

Proposed shape

1. Explicit local overlay layer

Add a supported local overlay/pin mechanism, for example:

skills:
  overlay_dirs:
    - ~/.hermes/skill-overlays

Desired semantics:

• overlays are explicit and visible, not silent hand-edits to bundled skills;
• overlays survive hermes update;
• if upstream changes a bundled skill that has an overlay, Hermes reports the conflict and offers inspect/merge/keep-local/accept-upstream flows;
• overlays are for deliberate local pins/customizations, not a replacement for normal bundled skill updates.

2. Policy-driven profile skill sync

Support an optional profile skill sync policy file, conceptually:

canonical_skill_root: ~/.hermes/skills
profile_root: ~/.hermes/profiles
overlay_skill_root: ~/.hermes/skill-overlays
sync_profiles:
  - dev
  - reviewer
sync_skills:
  - github-pr-workflow
  - requesting-code-review
never_sync_skills:
  - project-specific-review
profile_disabled:
  reviewer:
    - some-noisy-skill
disabled_everywhere:
  - superseded-skill

Core requirements:

• sync must be allowlisted, not wholesale mirroring;
• compare full skill directories, not just SKILL.md;
• preserve deliberate profile forks via never_sync_skills or equivalent;
• back up before mutation;
• prefer reversible disablement over deleting skills;
• detect skills.external_dirs collision risk before writing profile-local shadow copies.

3. CLI modes: check/apply/verify

Expose non-mutating and mutating modes:

hermes skills sync --check
hermes skills sync --apply
hermes skills sync --verify

Expected behavior:

• --check: report drift/collisions and exit nonzero; no writes
• --apply: apply reviewed allowlisted changes with backups
• --verify: assert clean post-sync state

This enables quiet cron/CI watchdogs that alert on drift without auto-overwriting user files.

4. Integrate with lifecycle visibility

This should interoperate with the broader skill lifecycle/status surface:

hermes skills status
hermes skills diff <skill>

Useful status states might include:

• bundled/up-to-date
• bundled/user-modified
• bundled/overlaid
• local-only
• profile-copy/in-sync
• profile-copy/drifted
• profile-fork/ignored
• shadowed-by-external-dir
• deprecated-upstream

Related issues / PRs

• #28213 — hermes skills status + diff lifecycle transparency
• #16852 — skills overlay architecture: separate bundled/upstream from custom/user layers
• #8302 — propagate upstream improvements to locally modified skills
• #18402 — hermes update should show changed skill names and reset options
• #20352 — skills are unversioned hand-edited markdown; need diff/rollback path
• #27997 — declarative skill protection policy across skill operations
• #28126 — sync_skills + external_dirs collision causing duplicate skill names
• #28187 — PR to skip bundled skills already provided by external_dirs
• #26987 — dedupe heavy shared skill directories across profiles
• #27128 — PR for symlink-based profile skill dedupe
• #21485 — profile cloning duplicates large GStack skill payload
• #25120 — profile install/update destructively replaces local skills despite distribution ownership
• #16176 — hermes update skips bundled skill sync for active profile
• #29013 — skills.auto_sync_bundled config to disable bundled auto-copy

Non-goals

• Do not auto-merge arbitrary Markdown skill conflicts with no review.
• Do not make every profile mirror the default profile's full skill library.
• Do not erase profile-local forks silently.
• Do not solve all skill lifecycle UX in one PR; this can build on status/diff incrementally.

Why this matters

Hermes' skill system is powerful because it learns and adapts locally. But once users run multiple profiles or customize bundled skills, the lifecycle model needs guardrails similar to package managers and config management:

• visible provenance;
• explicit overlays;
• drift detection;
• safe preflight;
• backups;
• review before mutation.

A minimal first version could be just status/diff plus overlay detection. A later version could add policy-driven sync --check/apply/verify for advanced multi-profile setups.