All plugins

skill-layers

Preserve source skills, create writable derivatives, and review three-way source updates. Disclosure — publishing (only from the Desktop page, the dashboard or the `hermes skill-layers` CLI; the three agent tools are read-only) writes a new `sl-*` skill folder into the active profile's skills directory and never replaces an existing one; three-way source updates run the local `git merge-file` with a scrubbed environment; history is kept under the profile's plugin data and is not removed on uninstall.

asimons81Toolsv0.1.0Updated 3 hours ago

About

Preserve source skills, create writable derivatives, and review three-way source updates. Disclosure — publishing (only from the Desktop page, the dashboard or the `hermes skill-layers` CLI; the three agent tools are read-only) writes a new `sl-*` skill folder into the active profile's skills directory and never replaces an existing one; three-way source updates run the local `git merge-file` with a scrubbed environment; history is kept under the profile's plugin data and is not removed on uninstall.

Hermes Skill Layers

Skill Layers preserves an installed skill as a read-only source reference and lets you work in ordinary, writable copies. It can compare a copy with a later version of the installed source, show a reviewable candidate, and publish a new copy after you approve the exact revision and review hash.

Validation status

For the current validation record, see docs/QA_REPORT.md, the Actions run for the exact commit under review, and the release handoff. A green CI run alone does not establish Hermes Desktop acceptance for the release payload.

Each profile has its own installation, source selection, private layer history, and exported skills. The release gate exercises two real named profiles with physical plugin copies, plus the active-profile checks in the Desktop client.

What it does

  • Captures selected on-disk skills in the active Hermes profile, including support files, without rewriting the source.
  • Creates a distinctly named derivative skill in that profile. Derive, refresh, and rollback prepare candidates; publish is the action that creates a new export.
  • Compares source base, current derivative, and updated source. Conflicts require an explicit whole-file resolution.
  • Keeps old exports and checkpoints. A later edit to an old export stays there; it is not copied automatically into the new export.
  • Exposes only bounded, read-only agent tools: skill_layers_list, skill_layers_status, and skill_layers_diff.

The preferred export is a Skill Layers preference. It does not switch a running conversation. Select the exact published skill name when you want Hermes to use that copy.

Install

Install a reviewed 40-character release commit from the public repository:

hermes plugins install asimons81/hermes-skill-layers --ref <40-character-release-commit>

Replace the placeholder with the commit SHA published for the release. If Hermes stops at its community-source scan, follow the install trust review for that exact commit. Hermes may ask you to approve the declared Python dependency, ruamel.yaml; approve it to enable the plugin. Do not install from a dirty development checkout or symlink the project root into a profile: local work/ files and host checkouts are not plugin payload. Use a clean repository clone or the immutable Git commit above.

The contributed hermes skill-layers command requires Hermes plugin isolation mode in_process. Skill Layers reports this in doctor; it does not change plugins.isolation or managed policy. If your administrator pins plugins.isolation: host, the contributed CLI is unavailable. Follow that policy and ask the administrator about supported deployment options instead of changing the setting to enable this plugin.

Install and enable the plugin in each intended Hermes profile. The source package is a virtual dependency member, so separate physical copies do not require multiple installed distributions with the same Python package name.

git must be installed for merge preparation. Hermes plugin installation handles the declared Python dependency through its normal dependency consent flow; Skill Layers does not install dependencies declared by a skill.

Three-minute workflow

List eligible installed skills, then prepare a derivative:

hermes skill-layers sources --json
hermes skill-layers derive <source-id> --label "Release notes" --json

Derive returns a candidate ID and revision. Review its complete diff and use the exact publish_command and review_hash returned by diff:

hermes skill-layers diff <candidate-id> --json
hermes skill-layers publish <candidate-id> --revision <revision> --review-hash <review-hash> --json

If a candidate has conflicts, publication is rejected until you resolve every conflict. Choose a whole file from a side that exists, delete it explicitly, or provide a whole-file replacement:

hermes skill-layers resolve <candidate-id> --revision <revision> --path <relative-path> --take local --json
hermes skill-layers diff <candidate-id> --json

Resolution changes the candidate revision and review hash. Review the new diff before publishing; do not reuse an earlier review hash.

After publishing, use its exact native selector in Hermes. Native skill edit locks and approvals continue to apply to the derivative. A plugin publication is a separate, explicit operator action; it does not enter Hermes' native skill_manage approval queue. Never use plugin publication as a fallback for a denied native edit.

Update a source and keep local work

Update the original skill using your existing installation workflow. Skill Layers does not fetch or update the source. Then checkpoint the current derivative and prepare a refresh:

hermes skill-layers checkpoint <layer-id> --json
hermes skill-layers refresh <layer-id> --json
hermes skill-layers diff <candidate-id> --json

Review the proposed tree, resolve conflicts if needed, and publish using the returned revision and review hash. This creates a new skill name. Earlier exports remain usable and unchanged, including later edits made to them. A clean text merge does not prove the skill behaves correctly; inspect and test the resulting skill yourself.

To prepare a rollback copy from a checkpoint:

hermes skill-layers rollback <layer-id> --checkpoint <checkpoint-id> --json
hermes skill-layers diff <candidate-id> --json

Review and publish the rollback candidate like any other candidate. Rollback creates another new export; it does not replace an earlier one.

Limits and data

  • Sources must be ordinary on-disk skills discovered in the active profile. V1 does not accept plugin-registered skill bundles, arbitrary paths, or URLs as sources.
  • Capture limits are 256 files, 2 MiB per file, and 16 MiB per tree. Unsafe paths, links/reparse points, hard links where detectable, reserved names, and filesystem collisions are rejected.
  • A copied skill that relies on paths outside its own directory may need manual adaptation.
  • Raw snapshots preserve captured bytes. Normalized merge trees replace only the validated frontmatter name scalar; exports receive a new generated name.
  • Git's local merge-file command is used for text merging. It runs without a shell or network access. Missing Git blocks merge preparation.
  • The plugin stores profile-scoped history in Hermes plugin data. Disabling or removing the plugin does not remove exported skills. Removing the plugin also does not intentionally delete plugin history; that history is needed for future review and reconciliation.
  • Skill Layers does not guarantee that unrelated Hermes tools or other processes cannot modify a source. Existing native locks are the supported protection mechanism for those writers.

See installation, recovery, and security for details.

Uninstall

Disable or remove the plugin with Hermes:

hermes plugins disable skill-layers
hermes plugins remove skill-layers

Neither action deletes published skill copies. Keep the profile's Skill Layers plugin data if you may want its checkpoints, source history, or reconciliation records later. Do not manually delete that data while operations are pending.

README from the reviewed commit 4ae841a; it updates when the author re-pins.

More by asimons81

2 plugins by asimons81 in the catalog.

asimons81hermes-cruxExplore explicit assumptions, exact affine decision thresholds, hard-constraint conflicts, and a live visual atlas.CommunityDesktop app