How to Keep Your AI Agent’s Skill Library Clean: A Deep Dive into the Hermes Curator

Core question this article answers: When your AI agent keeps creating new skills, how do you prevent the skill library from turning into unmaintained technical debt?

If you have been using Hermes Agent for any length of time, you have probably noticed a pattern. Every time the agent solves a novel problem, it packages that solution into a new “skill” and drops it into ~/.hermes/skills/. At first, this feels magical. Your agent is getting smarter, building a reusable knowledge base from experience. But after a few months, you open that directory and find dozens of narrowly scoped, overlapping, and potentially outdated skill files. They clutter the catalog, waste context-window tokens, and slow down the agent’s retrieval process.

This is exactly why the Hermes Curator exists. It is not a flashy feature announcement. It is a pragmatic background maintenance mechanism designed to keep your agent-created skills organized, relevant, and performant over time.

What Is the Curator and What Problem Does It Solve?

Core question: Why does an AI agent need an automated skill maintenance system?

Think of the Curator as a diligent librarian for your agent’s self-authored knowledge base. Without it, the skills generated through the self-improvement loop would accumulate indefinitely. You would end up with a graveyard of near-duplicate, overly specific, and drifted skills that pollute the catalog and consume unnecessary tokens every time the agent loads its skill context.

The Curator addresses this by performing three core duties:

Tracking usage telemetry — It monitors how often each skill is viewed, used, and patched, and records when these events last occurred.
Automating state transitions — It moves long-unused skills through a lifecycle from active to stale to archived.
Running intelligent reviews — It periodically spawns an auxiliary model to survey the skill library and propose consolidations, patches, or archival actions.

Author’s reflection: When I first grasped the Curator’s purpose, I realized it solves a problem that many AI systems simply ignore: knowledge decay. Humans forget, reorganize notes, and archive old files. AI agents, left to their own devices, only append. The Curator introduces something akin to human memory maintenance into Hermes, and in my view, this is not a nice-to-have feature. It is essential infrastructure for any agent system expected to operate at scale over weeks or months.

Importantly, the Curator never touches bundled skills that ship with the Hermes repository, nor does it interfere with skills installed from the community hub at agentskills.io. Its jurisdiction is strictly limited to skills the agent itself has authored. It also never auto-deletes anything. The most severe outcome is archival into ~/.hermes/skills/.archive/, which is fully recoverable.

How the Curator Runs: Idle-Time Maintenance Without Disrupting Your Workflow

Core question: When does the Curator run, and will it interrupt my active conversations?

The Curator is triggered by an inactivity check, not by a traditional cron daemon. This is a deliberate design choice. On CLI session startup, and on a recurring tick inside the gateway’s cron-ticker thread, Hermes evaluates two conditions:

Condition	Default Value	Purpose
`interval_hours`	168 hours (7 days)	Has enough time passed since the last Curator run?
`min_idle_hours`	2 hours	Has the agent been idle long enough to justify spawning a background task?

Both conditions must be satisfied for a run to trigger. If they are, Hermes forks a background instance of AIAgent — the same pattern used by the memory and skill self-improvement nudges. This fork operates in its own prompt cache and never interacts with the active conversation.

Application scenario: Imagine you are running Hermes on a development workstation. You are actively coding and querying the agent throughout the day. Because min_idle_hours is set to 2 hours by default, the Curator will not trigger while you are working. Instead, it waits for a lull — perhaps during your lunch break or after you have stepped away for the evening. This ensures that the LLM review phase, which consumes model inference resources, only runs when the system is quiet.

A single Curator run consists of two distinct phases:

Phase 1: Automatic Transitions (Deterministic, No LLM)

This phase is pure rule enforcement. The Curator scans the usage telemetry and applies hard thresholds:

Skills unused for stale_after_days (default: 30 days) are marked as stale.
Skills unused for archive_after_days (default: 90 days) are moved to ~/.hermes/skills/.archive/.

These transitions require no model inference and complete almost instantly.

Phase 2: LLM Review (Single Auxiliary-Model Pass, Max 8 Iterations)

This is where the intelligence comes in. The forked agent surveys all agent-created skills, can read any of them using the skill_view tool, and makes per-skill decisions:

Keep: The skill is healthy and requires no action.
Patch: Update the skill via skill_manage to fix drift or improve clarity.
Consolidate: Merge two or more overlapping skills into a single, more general one.
Archive: Manually move a skill to the archive directory, overriding the automatic schedule if the LLM judges it to be redundant or obsolete.

Application scenario: Suppose your agent created a skill called parse-csv-simple in January, and later created load-csv-with-headers in March. Both skills overlap significantly. During the LLM review phase, the auxiliary agent reads both files, recognizes the redundancy, and proposes consolidating them into a single csv-utils skill with optional parameters. This kind of semantic judgment is exactly what rules alone cannot do.

Configuration: Tuning the Curator to Your Environment

Core question: What configuration options does the Curator offer, and how do I customize them?

All Curator settings live in config.yaml under the curator: key. The system does not use environment variables for these settings because none of them are secrets.

The default configuration is:

curator:
  enabled: true
  interval_hours: 168          # 7 days
  min_idle_hours: 2
  stale_after_days: 30
  archive_after_days: 90
  auxiliary:
    provider: null             # null = use main auxiliary client resolution
    model: null

Key Configuration Options

Option	Default	What It Controls
`enabled`	`true`	Master switch. Set to `false` to disable the Curator entirely.
`interval_hours`	`168`	Minimum hours between Curator runs.
`min_idle_hours`	`2`	Minimum idle time before a run can trigger.
`stale_after_days`	`30`	Days of inactivity before a skill becomes stale.
`archive_after_days`	`90`	Days of inactivity before a skill is archived.
`auxiliary.provider`	`null`	Model provider for the LLM review phase.
`auxiliary.model`	`null`	Specific model name for the LLM review phase.

Using a Cheaper Model for Reviews

If your main auxiliary model is an expensive frontier model like GPT-4 or Claude 3 Opus, you can route the Curator’s LLM review to a more cost-effective option:

curator:
  auxiliary:
    provider: openrouter
    model: google/gemini-3-flash-preview

This keeps the automatic transition phase at zero inference cost while minimizing the expense of the intelligent review phase.

Author’s reflection: I appreciate the clarity of this configuration design. Everything is centralized in one YAML node, and the separation between scheduling policy (interval_hours, min_idle_hours) and execution policy (auxiliary.provider, auxiliary.model) is intuitive. In many systems, these concerns get tangled across environment variables, config files, and runtime flags. Hermes keeps it simple, which makes operational tuning straightforward.

CLI Commands: Your Curator Control Panel

Core question: How do I manually interact with the Curator outside of its automatic schedule?

Hermes exposes a complete set of CLI commands for managing the Curator:

# View status: last run time, skill counts, pinned list, and top 5 least-recently-used skills
hermes curator status

# Trigger a review immediately (runs in the background by default)
hermes curator run

# Trigger a review and block until the LLM phase completes
hermes curator run --sync

# Pause Curator runs until explicitly resumed
hermes curator pause

# Resume Curator runs
hermes curator resume

# Pin a skill to prevent automatic transitions and agent modifications
hermes curator pin <skill>

# Unpin a previously pinned skill
hermes curator unpin <skill>

# Restore an archived skill back to active status
hermes curator restore <skill>

These same subcommands are also available as the /curator slash command inside a running session, whether you are using the CLI or a gateway platform.

Reading the Status Output

Running hermes curator status gives you a quick health check of your skill library. It shows:

When the Curator last ran
How many skills are active, stale, and archived
Which skills are currently pinned
The five least-recently-used skills

Application scenario: You notice your agent has been slower to respond recently. You run hermes curator status and see that you have 62 active skills, 15 stale skills, and the LRU list shows temp-script-feb2026 and draft-api-client at the top — both untouched for over 80 days. You realize your skill library has bloated. You could wait for the next automatic run, or you could manually trigger hermes curator run to clean things up immediately.

What “Agent-Created” Means: Defining the Curator’s Jurisdiction

Core question: Which skills does the Curator manage, and which are off-limits?

A skill is considered agent-created if its name is not present in either of two manifest files:

~/.hermes/skills/.bundled_manifest — Skills copied from the Hermes repository during installation.
~/.hermes/skills/.hub/lock.json — Skills installed via hermes skills install from the community hub.

Everything else in ~/.hermes/skills/ falls under the Curator’s purview, including:

Skills the agent saved automatically via skill_manage(action="create") during conversations.
Skills you created manually by writing a SKILL.md file by hand.
Skills added via external skill directories that you have pointed Hermes to.

Application scenario: Your team maintains a custom internal-deploy-pipeline skill that you wrote manually. It resides in ~/.hermes/skills/ but is not in either manifest file. The Curator will treat it as agent-created and subject it to the same usage tracking and state transitions. If this skill is critical, you should pin it using hermes curator pin internal-deploy-pipeline.

Pinning a Skill: Locking Down Your Critical Knowledge

Core question: How do I protect important skills from being modified or archived?

Pinning is one of the most practical features of the Curator system. Once a skill is pinned, it receives dual protection:

Protection Layer	Behavior
Curator automatic transitions	The skill is skipped during `active → stale → archived` state changes.
Curator LLM review	The review prompt explicitly instructs the auxiliary model to leave pinned skills alone.
Agent’s `skill_manage` tool	All write actions (`edit`, `patch`, `delete`, `write_file`, `remove_file`) are refused. The agent is told to ask the user to unpin the skill first.

This second layer is particularly important. It prevents the agent from silently rewriting a skill mid-conversation — a scenario that could otherwise corrupt carefully crafted instructions.

How to Pin and Unpin

hermes curator pin <skill>
hermes curator unpin <skill>

The pinned flag is stored as "pinned": true in the skill’s entry within ~/.hermes/skills/.usage.json, so it persists across sessions.

Updating a Pinned Skill

Pinning guards the tool path, not the filesystem. You can still edit the skill directly:

vim ~/.hermes/skills/<name>/SKILL.md

Your changes take effect immediately, and the pin remains in place.

Limitation: Only Agent-Created Skills Can Be Pinned

If you attempt to pin a bundled or hub-installed skill, the command will refuse and explain that these skills are never subject to Curator mutation in the first place.

Application scenario: You have spent hours refining a production-security-checklist skill that enforces your company’s compliance requirements. The last thing you want is for the agent to “helpfully” patch it during a conversation, or for the Curator to archive it after 90 days of low usage. hermes curator pin production-security-checklist gives you peace of mind. The agent cannot modify it without your explicit permission, and the Curator will never touch it.

Usage Telemetry: The Curator’s Ledger

Core question: What data does the Curator track to make its decisions?

The Curator maintains a sidecar file at ~/.hermes/skills/.usage.json. Each skill has an entry that looks like this:

{
  "my-skill": {
    "use_count": 12,
    "view_count": 34,
    "last_used_at": "2026-04-24T18:12:03Z",
    "last_viewed_at": "2026-04-23T09:44:17Z",
    "patch_count": 3,
    "last_patched_at": "2026-04-20T22:01:55Z",
    "created_at": "2026-03-01T14:20:00Z",
    "state": "active",
    "pinned": false,
    "archived_at": null
  }
}

What Each Counter Means

Field	Trigger Condition
`view_count`	The agent calls `skill_view` to read the skill’s content.
`use_count`	The skill is loaded into a conversation’s prompt context.
`patch_count`	A `skill_manage` write operation (`patch`, `edit`, `write_file`, `remove_file`) is executed on the skill.

Bundled and hub-installed skills are explicitly excluded from telemetry writes. This reduces I/O overhead and maintains logical consistency, since the Curator does not manage those skills anyway.

Author’s reflection: The distinction between view_count and use_count is subtle but valuable. A skill might be frequently viewed during retrieval — meaning the agent sees it in search results — but rarely actually loaded into context. This pattern suggests a “discovery problem”: the skill is findable but not compelling enough to use. The Curator’s LLM review can use this signal to prioritize skills that may need better documentation or clearer scope.

Per-Run Reports: Full Auditability

Core question: Can I review what the Curator did after it runs?

Every Curator run generates a timestamped directory under ~/.hermes/logs/curator/:

~/.hermes/logs/curator/
└── 20260429-111512/
    ├── run.json      # Machine-readable: full fidelity, statistics, LLM output
    └── REPORT.md     # Human-readable summary

REPORT.md provides a concise overview of what happened during that run:

Which skills transitioned between states
What the LLM reviewer recommended
Which skills were patched or consolidated

run.json contains the complete machine-readable record, including the full LLM output and detailed statistics.

Application scenario: On Monday morning, you discover that a skill you expected to find is missing from the active directory. You check ~/.hermes/logs/curator/ and open the most recent REPORT.md. It shows that legacy-api-wrapper was archived during the weekend run because the LLM determined it overlapped with a newer modern-api-client skill. You can now make an informed decision: either restore the old skill if it still has unique value, or update the new skill to incorporate anything missing.

Restoring an Archived Skill: Recovery Made Simple

Core question: What if the Curator archives a skill I still need?

Recovery is straightforward:

hermes curator restore <skill-name>

This command:

Moves the skill from ~/.hermes/skills/.archive/ back to the active tree.
Resets its state to active.
Updates its usage record to reflect the restoration.

Safety Guard

The restore command will refuse if a bundled or hub-installed skill has since been installed under the same name. This prevents a restored user skill from shadowing an upstream skill, which could lead to confusing behavior.

Application scenario: Three months ago, the Curator archived your custom-logger skill. You did not notice at the time because you were using a different logging approach. Now you are starting a new project and want that old configuration back. A single hermes curator restore custom-logger brings it back, state reset to active, ready for immediate use.

Disabling the Curator: Per-Environment Control

Core question: How do I turn off the Curator for specific environments or use cases?

The Curator is enabled by default, but you have multiple ways to disable it:

Method	Command / Configuration	Persistence	Best For
Profile-level disable	Set `curator.enabled: false` in `~/.hermes/config.yaml`	Cross-session	Environments where automatic maintenance is unnecessary
Temporary pause	`hermes curator pause`	Cross-session, resumable	Critical work periods when you want to prevent any background activity
Natural suppression	Keep the agent active	Per-check	Active development machines where the agent rarely idles for 2+ hours

The min_idle_hours threshold provides a natural safeguard: on a busy development machine, the Curator will only run during genuinely quiet stretches.

Application scenario: You are running Hermes in a CI/CD pipeline where each invocation is short-lived and stateless. The Curator would never have time to trigger meaningfully, and its logs would clutter the environment. Setting curator.enabled: false in the pipeline’s configuration keeps things clean.

Relationship to Other Hermes Systems

Core question: Where does the Curator fit within the broader Hermes architecture?

The Curator does not operate in isolation. It is part of a cohesive maintenance ecosystem:

Related System	Relationship
Skills System	The Curator’s governance target. The self-improvement loop creates skills; the Curator maintains them.
Memory	A parallel background review system that maintains long-term memory. It uses the same fork-agent architecture as the Curator.
Bundled Skills Catalog	Official skills shipped with Hermes. The Curator has no authority here.
Hub (agentskills.io)	Community skill distribution platform. Hub-installed skills are outside the Curator’s scope.

Author’s reflection: The fact that both Curator and Memory use the same fork-agent pattern reveals a consistent architectural philosophy in Hermes: maintenance tasks and interactive tasks are strictly separated. The main conversation thread responds to the user. All housekeeping — whether skill curation or memory consolidation — happens in isolated background instances. This separation protects user experience and allows maintenance logic to evolve independently.

Action Checklist / Implementation Steps

If you are setting up or tuning the Curator, follow these steps in order:

[ ] Check current status: Run hermes curator status to assess your skill library’s health.
[ ] Identify critical skills: Review the LRU top 5 list and determine if any skills need pinning.
[ ] Pin important skills: Protect team standards, production workflows, and manually crafted skills with hermes curator pin.
[ ] Adjust thresholds: Modify stale_after_days and archive_after_days to match your team’s cadence.
[ ] Optimize review costs: Assign a cheaper auxiliary model to the LLM review phase.
[ ] Establish audit habits: Periodically review ~/.hermes/logs/curator/REPORT.md to understand Curator decisions.
[ ] Know the restore path: Ensure your team understands hermes curator restore for recovering archived skills.
[ ] Configure per environment: Set curator.enabled: false in CI/CD or other contexts where automatic maintenance is unnecessary.

One-Page Overview

Question	Answer
What is the Curator?	A background maintenance system for Hermes Agent that prevents skill library bloat.
When does it run?	When the agent has been idle for at least 2 hours and at least 7 days have passed since the last run.
Does it delete skills?	No. The worst outcome is archival to `.archive/`, which is fully reversible.
Which skills does it manage?	Only agent-created skills. Bundled and hub-installed skills are never touched.
How do I protect a critical skill?	Use `hermes curator pin <skill>` to block automatic transitions and agent modifications.
Where are run records stored?	`~/.hermes/logs/curator/<timestamp>/REPORT.md` for humans, `run.json` for machines.
How do I restore an archived skill?	`hermes curator restore <skill-name>` moves it back and resets its state to active.
How do I disable it?	Set `curator.enabled: false` in `config.yaml`, or use `hermes curator pause`.
Which model runs the LLM review?	Defaults to the main auxiliary model; configurable via `curator.auxiliary.provider` and `model`.
Where is the configuration?	`~/.hermes/config.yaml`, under the `curator:` key.

Frequently Asked Questions

Q1: Can the Curator accidentally delete my skills?

No. The Curator never deletes anything. Its most severe action is moving a skill to the ~/.hermes/skills/.archive/ directory. You can restore it at any time using hermes curator restore <skill>.

Q2: Will the Curator affect skills I installed from the community hub?

No. Hub-installed skills are tracked in .hub/lock.json and are explicitly outside the Curator’s jurisdiction. The same applies to bundled skills listed in .bundled_manifest.

Q3: If I pin a skill, can I still edit it myself?

Yes. Pinning only blocks the agent’s skill_manage tool from making changes. You can edit the SKILL.md file directly with any text editor, and the skill will remain pinned.

Q4: How much does the LLM review phase cost in terms of tokens?

It depends on the size of your skill library and the model you configure. By default, the Curator uses your main auxiliary model, but you can specify a cheaper alternative (such as Gemini Flash) under curator.auxiliary to reduce costs. The review is a single pass with a maximum of 8 iterations.

Q5: Can I see exactly what decisions the Curator made during a run?

Yes. Every run writes a timestamped directory to ~/.hermes/logs/curator/. REPORT.md provides a human-readable summary, while run.json contains the full machine-readable record including the LLM’s output.

Q6: What happens if I try to restore a skill whose name now conflicts with a hub-installed skill?

The restore command will refuse. It checks whether a bundled or hub-installed skill already exists with the same name, and if so, it prevents the restoration to avoid shadowing upstream skills.

Q7: How is the Curator different from the Memory system?

Both systems use the same background fork-agent architecture, but they serve different purposes. The Curator manages skills, while the Memory system maintains long-term conversational memory. They run independently and do not interfere with each other.

Q8: My skill library is still small. Should I keep the Curator enabled?

Yes. Even with a small library, the Curator’s overhead is minimal, and it will automatically scale its value as your skill collection grows. If you truly do not want it, you can disable it with curator.enabled: false, but there is little downside to leaving it on.