.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
The most-cited frustration with Hermes's learning loop is the one where you carefully edit a skill, the agent regenerates it during a reflection pass and your edits vanish.
It's not a bug; it's the auto-skill-creation feature working as designed and it doesn't know which edits are your considered improvements versus which are stale state it should freshen up. The fix is a couple of frontmatter fields that mark a skill as user-owned, plus a workflow that keeps your edits and the auto-loop's edits from stepping on each other.
This guide covers the patterns that work: how to lock a skill against auto-regeneration, how to fork an auto-generated skill into a user-owned one, how to share skills across machines without losing local customisations and how to debug the case where a skill seems to misfire even though it looks correct on disk.
Where skills live and how they're structured
Skills are folders under ~/.hermes/skills/, one folder per skill. Each folder has at minimum a SKILL.md file with YAML frontmatter and a body. Optional supporting files can include scripts, templates, lookup tables.
A typical SKILL.md:
---
name: deploy-staging
description: Deploy the current branch to the staging environment
triggers:
- "deploy to staging"
- "push staging"
tools_required:
- shell
- filesystem
---
# Deploy to staging
When the user asks to deploy to staging:
1. Check git status; if dirty, ask the user to commit or stash first.
2. Run the staging deploy script at scripts/deploy-staging.sh.
3. Watch the output for the deployment URL; report it back.
4. If the script fails, capture the last 30 lines of output and summarise.The frontmatter declares when the skill applies. The body describes what to do. Hermes treats the body as natural-language instructions the agent follows when the skill matches.
Auto-generated vs user-written skills
Two paths get a skill into your skills folder.
You write it by hand. Direct, transparent, every line is your intent. You own the file completely; the auto-loop doesn't touch it.
Hermes generates it after recognising a recurring pattern. After three or four successful runs of similar work, the reflective phase produces a SKILL.md capturing the procedure. This is the auto-generated path. By default these skills are not user-locked, which means the loop may regenerate them later if it sees more successful runs of similar work and decides the procedure has evolved.
The two paths produce identical-looking files. The difference is in the frontmatter.
The user-locked frontmatter flag
Add this to any SKILL.md to mark it as user-owned:
---
name: deploy-staging
user_locked: true
---The reflective phase ignores user-locked skills. They never get regenerated. If the agent learns a new pattern that would update the skill, the loop creates a separate skill with a different name rather than overwriting the locked one.
The trade-off: a locked skill won't pick up new lessons the agent learns. If you carefully wrote a deploy-staging skill in March and the deploy process changed in May, the locked skill keeps describing the March process. You have to update it yourself.
For most heavily-edited skills, this is the right trade-off. Lock the ones you've put real thought into; let the auto-loop manage the boilerplate ones.
Forking an auto-generated skill
When you find an auto-generated skill that's mostly right but needs your edits, the safe pattern is to fork it.
cd ~/.hermes/skills/
cp -r deploy-staging deploy-staging-mine
cd deploy-staging-mineEdit SKILL.md inside the new folder. Change the name to deploy-staging-mine. Add user_locked: true. Edit whatever else you want to.
The original deploy-staging skill stays where it is; the auto-loop continues to manage it. Your forked version exists alongside. Both are matched against trigger phrases; you can tune which one fires first via the priority field:
---
name: deploy-staging-mine
user_locked: true
priority: 100
---Higher numbers win in trigger conflicts. The default is 50; bump your forked version to 100 and the agent picks yours over the auto-generated one when both match.
If you want the auto-generated one to never fire (you'd rather only have your forked version run), delete the original folder. The next reflective pass might recreate it; lock your forked version with a name that's similar enough that the loop sees the locked one and doesn't regenerate.
The override pattern via aliases
Sometimes you want your edited version to respond to the original skill's trigger phrases without forking. Use the aliases field:
---
name: deploy-staging-custom
user_locked: true
aliases:
- deploy-staging
priority: 100
---Now any prompt that would have triggered deploy-staging triggers deploy-staging-custom instead, because of the higher priority. The original skill is still there but inert as long as your override has higher priority and the same triggers.
Useful when you want to keep the auto-generated skill's name namespace clean while you experiment with your own version.
Skill conflicts during migration
If you migrated from OpenClaw via hermes claw migrate, some of your imported skills may collide with Hermes's built-in or auto-generated skills. The migration article covers the --skill-conflict flag (skip, overwrite, rename) that lets you choose how those collisions resolve.
Post-migration, you may have a mix of: imported skills under openclaw-imports/, Hermes built-in skills, auto-generated skills and your manually-written skills. The priority order Hermes uses by default:
Manually-locked user skills (highest).
Imported OpenClaw skills (medium).
Auto-generated skills (lower).
Hermes built-in skills (lowest).
This means your imports beat Hermes's defaults, but your manually-edited skills beat your imports. Tune with the priority field where the default order doesn't match your intent.
Sharing skills across machines
If you run Hermes on multiple machines (laptop, work box, VPS), keeping skills in sync is fiddly because each machine's auto-loop generates skills based on its own usage patterns.
The pattern that works: keep your manually-curated, locked skills in a git repo (private; some skills include sensitive context). Sync the repo across machines via clone-and-pull. Use a separate folder for these synced skills, like ~/.hermes/skills-shared/ and configure Hermes to load it as an additional skills directory:
hermes config set skills.search_paths "[~/.hermes/skills, ~/.hermes/skills-shared]"The auto-loop only writes to the first directory, so your shared skills don't get overwritten by per-machine learning. Pull the repo periodically to pick up changes from other machines; commit and push when you've made local changes worth sharing.
For team-shared skills (a team agent where everyone benefits from the same skills), the repo can be shared across users. The auto-loop generates per-user skills only if you give each user a separate ~/.hermes/skills/; the shared repo is read by all.
Debugging skills that don't fire
Sometimes you write a skill, save the file, send a prompt that should match it and the agent ignores the skill and answers from base capability instead.
Three checks.
First, is the SKILL.md syntactically valid? Run hermes with HERMES_LOG_LEVEL=debug, restart the gateway and look for "skill load failed" entries on startup. If your file has bad YAML frontmatter or a missing required field, the loader silently drops it.
Second, does the trigger match what you're prompting? The triggers field uses substring matching by default. If your trigger is "deploy to staging" but you prompted "let's push the staging deploy", neither phrase contains the other and the trigger doesn't fire. Add more trigger phrases or use regex triggers (triggers_regex: ["deploy.*stag", "push.*stag"]) for fuzzier matching.
Third, is another skill matching first? List active skills with the /skills slash command in a session. If you see two skills with overlapping triggers, the higher-priority one wins. Bump your skill's priority or rewrite triggers to be more specific.
Skill quality over quantity
The temptation with skills is to write a lot of them. Resist. Each enabled skill costs tokens (the SKILL.md gets included in active context when triggered) and increases the chance of trigger conflicts.
For a personal setup, ten to twenty actively-curated skills is plenty. Auto-generated ones add up over time; prune ones that don't fire much:
sqlite3 ~/.hermes/state.db "SELECT skill_name, COUNT(*) FROM skill_invocations WHERE created_at > date('now', '-30 days') GROUP BY skill_name ORDER BY COUNT(*)"Skills that fired zero or one time in the last 30 days are candidates for deletion. Either delete them or, if you suspect they'll be useful again, mark them disabled in frontmatter:
---
name: rare-skill
disabled: true
---Disabled skills don't get loaded but stay in your skills folder so you can re-enable later.
Building skills with the agent's help
The most efficient way to write a new skill is to ask the agent to write it. Walk through the procedure once, manually:
You: I want to deploy this branch to staging
Hermes: [walks through the steps, you correct it where it goes wrong]
You: That worked. Save this as a skill called deploy-staging-v2.The agent generates a SKILL.md based on the conversation, asks you to review and saves the skill to your skills folder. Faster than writing one from scratch and the result tends to be more useful because it's grounded in an actual run.
Edit the result for your specific phrasing, add user_locked: true, save. The skill is yours, the auto-loop won't touch it.
The OpenClaw skills equivalent
OpenClaw uses the same SKILL.md format and most of the same patterns translate. The OpenClaw skills guide covers OpenClaw's skill system in detail; the patterns above (lock, fork, prioritise, share via repo) apply equivalently. The migration tool brings your OpenClaw skills across to Hermes; once imported, you treat them as user-owned and apply the locking patterns from this article.
The 1-click route
The LumaDock Hermes Agent VPS template ships with a small set of useful starter skills installed (a deploy helper, a code-review helper, a daily-briefing helper) that you can fork and customise. Useful for getting a working baseline of skills you can edit rather than starting completely empty.
