Hermes Skill Git Automation

Small, self-hosted utilities for treating a Hermes skill library as a reviewed Git repository.

What is included

• locastic-skill_watcher.sh: watches the skill tree and auto-commits meaningful local changes.
• locastic-promote_skill.sh: validates and promotes staged/imported skills into the category layout.
• locastic-skill_health_check.py: report-only hygiene scan, with explicit opt-in archival.
• locastic-skill_validator.py: validates skill frontmatter and recursively scans the skill directory for high-risk content.
• locastic-skill_auditor.py: append/query JSONL mutation audit records.
• systemd/hermes-skill-watcher.service.in: systemd template with installation placeholders (Linux).

Safety model

• Local commits are automatic; remote push is manual by default.
• Runtime/cache/lock noise is filtered before every commit.
• Promotion copies sources into the active tree and always preserves the original source; cleanup is a separate manual review step.
• Health checks are report-only unless --archive is explicitly supplied.
• No credentials, remotes, logs, usage records, or machine-specific paths are included.
• Credential and high-risk-pattern scanning is best-effort defense-in-depth (a narrow heuristic), not a guarantee; always review before pushing.

Requirements

python3 -m pip install -r requirements.txt

The scripts run on both macOS and Linux (bash 3.2+, Python 3.9+, and Git 2.23+).

The continuous watcher can use a native file-watch tool when one is present; install one for lower latency:

# Debian/Ubuntu
sudo apt-get install inotify-tools

# macOS
brew install fswatch

If neither inotifywait nor fswatch is available, the watcher falls back to polling (see HERMES_WATCH_POLL_SECONDS). One-shot --once runs need neither tool.

Skill repository layout

~/.hermes/skills/<category>/<skill-name>/SKILL.md

Initialize it if needed:

git -C ~/.hermes/skills init
git -C ~/.hermes/skills branch -M main

Run manually

scripts/locastic-skill_health_check.py
scripts/locastic-skill_validator.py ~/.hermes/skills/example/example-skill/SKILL.md
scripts/locastic-skill_watcher.sh
# One scan/commit pass for CI or manual verification:
scripts/locastic-skill_watcher.sh --once

Promotion is intended only for staged/imported/manual drafts:

scripts/locastic-promote_skill.sh ~/.hermes/skills/staging/my-skill devops reviewer "Reviewed for activation"

Normal skills created by Hermes already live in the active category tree and do not need promotion.

Push policy

The watcher never pushes. Promotion also does not push unless explicitly enabled for that single invocation:

HERMES_PROMOTE_PUSH=1 scripts/locastic-promote_skill.sh ...

Recommended review flow:

git -C ~/.hermes/skills status --short --branch
git -C ~/.hermes/skills log --branches --not --remotes --oneline
git -C ~/.hermes/skills diff origin/main...HEAD
scripts/locastic-skill_health_check.py
git -C ~/.hermes/skills push origin main

Environment overrides

• HERMES_HOME, default: ~/.hermes
• HERMES_SKILLS_DIR, default: $HERMES_HOME/skills
• HERMES_SKILL_AUDIT_LOG, default: $HERMES_HOME/audit/skill-mutations.jsonl
• HERMES_WATCH_POLL_SECONDS, default: 10 (polling interval used when no file-watch tool is available)
• HERMES_PROMOTE_PUSH=1, optional one-shot promotion push

systemd (Linux)

Copy the unit template and replace:

• @USER@
• @HERMES_HOME@
• @SCRIPT_PATH@

Then install it as a system unit and verify the real process:

sudo systemctl daemon-reload
sudo systemctl enable --now hermes-skill-watcher.service
systemctl status hermes-skill-watcher.service --no-pager

On macOS there is no systemd; run locastic-skill_watcher.sh under a launchd agent or a persistent terminal/tmux session instead.

Public repository checklist

Before publishing:

1. Choose and add a license.
2. Run tests/smoke.sh.
3. Inspect git diff --cached.
4. Confirm no logs, .env, .usage.json, Git remotes, tokens, private hostnames, or home-directory paths are staged.

License

MIT. See LICENSE.