| name | post-hermes-files-edit |
| description | Classify edits to non-persistent Hermes Agent files and convert durable local customizations into patch modules. Use after changing Hermes checkout files, Docker image-layer files, or other non-persistent Hermes source files that may be lost on update. |
| version | 2.0.0 |
| author | Hermes local patchkeeper |
| license | MIT |
| metadata | {"hermes":{"tags":["hermes","local-patches","file-edits","patchkeeper","source-checkout"]}} |
post-hermes-files-edit
Use this skill after a user edits Hermes Agent files that may be replaced by hermes update, a git reset, a native reinstall, or a Docker image update.
Do not use it for persistent user state such as $HERMES_HOME, ~/.hermes/config.yaml, .env, auth stores, memories, cron definitions, normal custom skills, or Docker volumes such as /opt/data.
Classification
Inspect changed files with commands like:
git status --short
git diff --stat
git diff --name-status
Classify each edit as:
persistent-user-state: lives in $HERMES_HOME, ~/.hermes, or a Docker volume; no patch module needed.temporary-discardable: experiment or debug-only change; no patch module needed.local-customization: important source/image change that should survive updates; create a patch module.upstreamable-local-patch: should be proposed upstream, but needs a local patch until merged.
Capture Workflow
For each durable local customization, record:
- short patch id;
- target files;
- public-safe purpose;
- how to detect that upstream already includes the behavior;
- exact anchors required for compatibility;
- idempotent apply steps;
- tests or smoke checks;
- secret-safety review.
Use the design note template:
cp skills/post-hermes-files-edit/templates/patch_design_note.md /tmp/my_patch_design_note.md
Then create a module:
POST_HERMES_UPDATE_DIR=/path/to/post-hermes-update
cp "$POST_HERMES_UPDATE_DIR/templates/patch_template.py" "$POST_HERMES_UPDATE_DIR/scripts/patches/my_patch.py"
$EDITOR "$POST_HERMES_UPDATE_DIR/scripts/patches/my_patch.py"
python "$POST_HERMES_UPDATE_DIR/scripts/patchkeeper.py" --repo "$HERMES_HOME/hermes-agent" --check --only my-patch-id
Patch Requirements
Every patch module must:
- keep
--check read-only; patchkeeper will fail with exit code 3 if it detects repo mutation during check;
- require explicit
--apply;
- be idempotent;
- detect upstream presence before patching;
- check exact compatibility anchors before editing;
- avoid fuzzy edits when anchors are missing;
- use only repo-relative
TARGET_FILES and changed_files; absolute paths, ~, and .. traversal are rejected;
- ensure
changed_files exactly matches files actually modified during --apply;
- avoid secrets, tokens, private identifiers, environment dumps, and sensitive diffs;
- report changed files and recommended tests.
Updating post-hermes-update
Add only generic, user-owned patch modules under skills/post-hermes-update/scripts/patches/. Do not hard-code private operational rules in SKILL.md; keep patch-specific behavior inside the module with public-safe descriptions.
When upstream incorporates a customization, confirm is_present() returns true, then disable or remove the local patch module.
