The Curator Lifecycle

Skills accumulate. Hermes writes them after solving complex tasks. You write them to standardize procedures. The Skills Hub installs them. After a few weeks of active use, your ~/.hermes/skills/ directory is a graveyard of skills you haven't used in a month alongside ones you use every day, with no way to tell which is which.

The curator is the background process that manages this accumulation. It tracks which skills get used, marks idle ones as stale, archives the ones nobody touches anymore, and, optionally, consolidates overlapping skills into cleaner umbrella skills. Everything it does is reversible. It never deletes a skill, only archives it with a tar.gz backup. Its purpose is to keep your skill library useful without you having to curate it by hand.

What you'll learn

• The curator tracks every skill's usage (hits, views, patches) in a .usage.json sidecar, no guessing which skills are dead
• Stale skills are archived, not deleted, a tar.gz backup is created before any archive operation, and pinned skills are exempt from every automatic transition
• The consolidate pass (opt-in, uses an auxiliary model) merges overlapping skills into umbrella skills, it costs tokens only when you explicitly run it
• Day-to-day curation (usage tracking, staleness detection, auto-archive) costs zero tokens, it's deterministic, no LLM involved

The problem

You've been using Hermes for two months. hermes skills list shows 47 skills. Some you wrote, some Hermes wrote, some came from the Skills Hub. You haven't touched at least half of them since the week they were created. When Hermes scans the skill list at session start, those 47 entries add bulk to the system prompt without adding value, and worse, stale skills with vague descriptions sometimes match queries they shouldn't, steering Hermes toward outdated procedures.

You could manually audit your skills every month, but that's the kind of maintenance task people mean to do and never get around to. The curator does it automatically.

How the curator works

The curator runs as a background loop with four stages:

[Track Usage] → [Detect Stale] → [Auto-Archive] → [Backup]
                                              ↘ (opt-in)
                                              [Consolidate]

Stage 1: Usage tracking

Every interaction with a skill, loading it (skill_view), listing it (skills_list), editing it (skill_manage patch or edit), increments counters in ~/.hermes/skills/.usage.json. This file is a JSON sidecar that tracks per-skill:

Field	What it counts
use_count	Times Hermes loaded the skill during a session
view_count	Times the skill was viewed (via skill_view or listing)
patch_count	Times the skill was modified (via skill_manage)
last_activity_at	ISO timestamp of the most recent interaction
state	active, stale, or archived
pinned	Boolean, pinned skills are exempt from all automatic transitions

This tracking is passive and deterministic. It doesn't use an LLM to decide if a skill is useful, it counts usage. If a skill hasn't been loaded, viewed, or modified in 30 days, the data says it's idle regardless of how important you feel it is.

Stage 2: Stale detection

The curator checks .usage.json on its configured interval (default: every 24 hours). Any skill in active state whose last_activity_at is older than stale_after_days (default: 30 days) gets marked stale.

A stale skill is still available. Hermes still lists it, can still load it, and you can still use it. The stale state is a signal, not a restriction. It tells you "this skill hasn't been touched in a month, it might be worth reviewing or archiving."

Stage 3: Auto-archive

Skills that stay stale for longer than archive_after_days (default: 60 days, so 90 days total from last activity) get archived. Archiving means:

1. A tar.gz backup is created in ~/.hermes/skills/.archive/ (controlled by curator.backup.* config)
2. The skill is moved from ~/.hermes/skills/<name>/ to ~/.hermes/skills/.archive/<name>/
3. The skill is removed from the Level 0 skills list, it no longer appears in hermes skills list or the system prompt
4. .usage.json is updated to reflect state: archived

A skill can be restored from archive at any time with hermes curator restore <name>. The tar.gz backup means even if something goes wrong during archival, the original files exist. The curator's maximum destructive action is archiving, it never deletes.

Stage 4: Backup

Before any archive operation, the curator creates a full tar.gz snapshot of ~/.hermes/skills/ (configured in curator.backup.*). This is a safety net: if an archive operation somehow corrupts a skill, or if you realize six months later that you needed a skill you archived, the backup has the original.

Stage 5: Consolidate (opt-in)

The consolidate pass scans overlapping skills, skills with similar descriptions, overlapping domains, or redundant procedures, and merges them into umbrella skills. For example, three skills covering "Docker CI for Python," "Docker CI for Node.js," and "Docker CI for Go" might be consolidated into a single "Docker CI pipeline" skill with language-specific subroutines.

Consolidation uses an auxiliary model and costs tokens. It is off by default. Enable it with:

hermes config set curator.consolidate true

Or run it manually when you want to review:

hermes curator run --consolidate

The consolidator proposes merges but doesn't execute them automatically, you review the proposal before anything changes. Pinned skills are exempt from consolidation review.

Options & when to use each

Configuration	What it changes	When to use it
curator.enabled: true (default)	Enables the background curator loop	You have more than 10 skills and want automatic lifecycle management
curator.enabled: false	Disables the curator entirely	You have fewer than 10 skills, or you prefer to manage skills entirely by hand
curator.interval_hours: 24	How often the curator checks for stale skills	Default is fine for most users. Reduce to 12 if you create skills rapidly; increase to 168 (weekly) if skills evolve slowly
curator.stale_after_days: 30	Days of inactivity before a skill is marked stale	Default. Increase to 90 for skills in infrequently used domains
curator.archive_after_days: 60	Days in stale state before archival	Default. Set to 0 to archive immediately on stale detection, or to a large number (365) to keep stale skills around indefinitely
curator.consolidate: false	Whether the curator runs the LLM consolidation pass	Keep off unless you have dozens of skills and notice significant overlap. Turn on, run once, review results, turn off

Pinning a skill

Pinned skills are immune to every automatic curator transition. They never go stale, never get archived, and never appear in consolidation proposals. Pin a skill when it's critical infrastructure that should survive any cleanup:

hermes curator pin docker-pipeline
hermes curator pin python-project-init

Pinned skills still appear in .usage.json with tracking data, pinning doesn't hide them from telemetry. It only prevents automatic state changes.

Unpin when a skill is no longer critical:

hermes curator unpin docker-pipeline

Build it

Step 1: Check curator status

Query the current state of the background curator daemon to see active, stale, and archived counts along with the next execution window.

hermes curator status

Output shows whether the curator is enabled, the next scheduled run, how many skills are in each state (active, stale, archived), and the archive directory location.

Step 2: Run the curator manually

Trigger a synchronous, out-of-band sweep. This bypasses the schedule and forces an immediate evaluation of all usage metrics across the skill registry.

hermes curator run

This runs the full deterministic sweep: usage check, stale detection, auto-archive, backup. No LLM calls, no tokens consumed. It processes all skills immediately instead of waiting for the scheduled interval.

The output lists:

• Skills that transitioned from active to stale
• Skills that transitioned from stale to archived
• Backup location and size
• Any errors (permissions, missing files)

Step 3: Pin important skills

Identify skills you want protected from archival:

hermes curator pin docker-pipeline
hermes curator pin python-project-init

Verify they're pinned:

Confirm the immutable state flag has been set on your critical skills, effectively shielding them from archival logic.

hermes curator status

Pinned skills show as active [pinned] in the status output.

Step 4: Restore an archived skill

Archived skills live in ~/.hermes/skills/.archive/:

hermes curator restore docker-pipeline

The skill is moved back to its original location, its state is set back to active, and it reappears in the Level 0 skills list. The tar.gz backup is not deleted, it stays as a historical snapshot.

Step 5: Configure curator timing

Adjust when skills go stale and get archived:

# Mark inactive skills stale after 60 days instead of 30
hermes config set curator.stale_after_days 60

# Archive stale skills after 30 days in stale state (90 days total)
hermes config set curator.archive_after_days 30

# Check curator runs every 12 hours instead of 24
hermes config set curator.interval_hours 12

Step 6: Prune old backups

Backups accumulate over time. The curator can prune backups older than a certain threshold:

hermes curator prune --older-than 90

This removes tar.gz backups older than 90 days. Pruning only affects backups, not archived skills, you can still restore a skill from its .archive/ directory even after its backup is pruned.

What goes wrong

Mistake	How you notice it	The fix
A skill you need was archived	hermes skills list doesn't show it, and Hermes doesn't reference it	The skill isn't gone, it's in ~/.hermes/skills/.archive/. Restore it: hermes curator restore <name>. Then pin it: hermes curator pin <name> to prevent future archival
Curator archives a skill you used yesterday	A recently used skill disappears	Check ~/.hermes/skills/.usage.json for that skill. The last_activity_at timestamp might be stale because skill_view calls through a different path (e.g., loaded via bundle rather than directly). If the timestamp is wrong, unpin and re-pin the skill to reset its state, then file a bug report, the tracking should catch all access paths
Consolidate pass proposes merging skills that aren't actually overlapping	The proposal suggests combining "Docker CI" with "Systemd Service Setup" because both mention "configuration"	The auxiliary model running consolidation sees surface-level word overlap. Review proposals before accepting, the consolidator suggests, it doesn't auto-apply. Decline merge proposals that don't make sense
Backup directory fills the disk	df -h shows ~/.hermes/skills/.archive/ consuming gigabytes	Old backups accumulate. Prune them: hermes curator prune --older-than 90. Or disable backups entirely: hermes config set curator.backup.enabled false. Backups are safety nets, not archives, you don't need every weekly backup from the past year
Curator is disabled but skills still get archived	Skills disappear despite curator.enabled: false	The curator runs inside the Hermes process, not as a separate service. If you disabled the curator but Hermes is still running from a previous config, the old setting persists until the next restart. Check: hermes curator pause to explicitly pause, or restart Hermes after config changes

Confirm it worked

Validate the lifecycle management by explicitly defining a test skill, manually invoking the curator, and monitoring the telemetry output.

# 1. Check curator status
hermes curator status

# 2. If the curator is disabled, enable it:
hermes config set curator.enabled true

# 3. Create a skill to test the lifecycle:
mkdir -p ~/.hermes/skills/curator-test
cat > ~/.hermes/skills/curator-test/SKILL.md << 'EOF'
---
name: curator-test
description: "Test skill for curator lifecycle verification"
version: 1.0.0
platforms: [linux]
---

# Curator Test Skill
This skill exists to verify curator functionality.
EOF

# 4. Run the curator manually:
hermes curator run

# 5. Verify the skill appears in the usage tracking:
cat ~/.hermes/skills/.usage.json | python3 -m json.tool | grep -A5 curator-test

# 6. Pin the skill to protect it from archival:
hermes curator pin curator-test

# 7. Verify the pin:
hermes curator status | grep curator-test

# 8. Clean up:
hermes curator unpin curator-test
rm -rf ~/.hermes/skills/curator-test

If step 5 shows the skill in .usage.json with tracking fields, the curator's usage tracking is working. If step 7 shows the skill as active [pinned], pinning is working. Both should work out of the box with the default curator configuration.

Next: Skills Hub Ecosystem, installing community skills, trust levels, security scanning, and publishing your own skills.