Wiki · Features in depth
Skill curator
The curator never deletes — it archives, and an archive can be restored. What it does, when it runs and how to review your library.
🗂️
The curator never deletes. The harshest thing it does is archive — and that is one command away from coming back.
It solves one annoying fact: when the agent saves a new skill for every novel problem, half a year
later the library is full of narrow near-duplicates. The curator keeps that in check, but leaves the
decisions to you — and it does not touch the library before you have had a chance to look.
What the curator does
It tracks how often each skill was viewed, used and patched, and moves it through three states: active → stale → archived. With the consolidation phase enabled it occasionally runs a short review on a cheaper model that proposes merges or patches drift.
| Phase | What it does | Does it cost money? |
|---|---|---|
| Automatic transitions | Unused for 14 days = stale; 30 days = archived | No (always on while the curator is enabled) |
| LLM consolidation | Surveys the skills, proposes merging near-duplicates and fixes drifted text | Yes, but it can run on a cheap model |
Only agent-created skills are managed automatically. Skills installed from the hub (agentskills.io) are always off-limits.
When it runs
Not on a cron schedule, but on inactivity. Hermes checks at CLI start, during gateway housekeeping and on the Desktop maintenance timer whether both are true:
| Condition | Default |
|---|---|
| Time since the last run | interval_hours = 168 (7 days) |
| The agent has been idle long enough | min_idle_hours = 2 hours |
The first run is deferred by a full interval: on a fresh install it just records “now” and the first real pass happens a week later. That is deliberate — you get time to review the library and pin anything important.
Configuration
curator:
enabled: true
interval_hours: 168 # 7 days
min_idle_hours: 2
stale_after_days: 14
archive_after_days: 30
consolidate: false # LLM consolidation — off
prune_builtins: false # also archive unused bundled skills
| Key | Purpose |
|---|---|
consolidate | Enables the consolidation pass. It is the only phase that rewrites skill content — which is why Hermes snapshots the library before it |
prune_builtins | Archive unused bundled skills too. Optional, because bundled skills disappearing looks like a broken install |
auxiliary.curator | Which model runs the review. Leave auto (main model) or pin a cheap one |
# cheaper model for the review (config.yaml)
auxiliary:
curator:
provider: openrouter
model: google/gemini-3-flash-preview
timeout: 600
Commands worth knowing
| Command | What it does |
|---|---|
hermes curator status | Last run, counts, pinned skills, least-used skills |
hermes curator run --dry-run | Start here — prints what the curator would do and changes nothing |
hermes curator run | Runs a pass now (prune-only unless consolidation is on) |
hermes curator pin <skill> | Never auto-transition or archive this skill |
hermes curator backup / rollback | Manual snapshot of the library and returning to it |
hermes curator restore <skill> | Moves an archived skill back to active |
hermes curator ledger | Who changed what and when; rollback <id> undoes one change |
What never happens
| Worry | Reality |
|---|---|
| “It will delete my skills” | It does not delete. Archiving moves a skill to ~/.hermes/skills/.archive/ |
| “It will touch hub skills” | No, those are always excluded |
| “It will archive a skill a cron job uses” | No. A skill referenced by any scheduled job (even a paused one) is treated as pinned |
| “It will drop a skill nobody used yet” | No. A skill with zero uses gets a grace period — it is not archived before it is as old as stale_after_days |
How we do it
| Habit | Why |
|---|---|
run --dry-run first, then clean up by hand | With a library that grew over months it is better to see the proposal and decide yourself |
| Turn consolidation on only after the first pass | Clean up first, merge afterwards — otherwise you merge skills that merely share a name |
| Keep skills in git | Versions, diffs and rollback without relying on the curator's snapshot |
| Archive, never delete | Months later a “useless” skill turns out to hold one recipe you need |
Common mistakes
| Symptom | Cause and fix |
|---|---|
| The curator never runs | Both conditions must hold: the interval has passed and the agent is idle. On a fresh install the first run waits a full interval |
| Something is missing after consolidation | hermes curator rollback --list and restore a specific snapshot; the ledger also records the pre-merge content |
| Bundled skills are disappearing | You have prune_builtins: true — turn it off and bring archived skills back with restore |
| The review is expensive | Point auxiliary.curator at a cheap model; the archival pass itself costs nothing |