Skip to content

Commit 2f83f49

Browse files
teknium1nickdlkk
teknium1
authored and
nickdlkk
committed
docs: exclude per-skill pages from search, add curator feature page (NousResearch#17563)
Skill catalog pages (bundled/optional) were drowning out real user-guide and reference docs in search results. There are ~3100 of them and they match on almost every generic term. - Add `ignoreFiles` regexes to docusaurus-search-local for `user-guide/skills/bundled/` and `user-guide/skills/optional/`. The two human-written catalog indexes (`reference/skills-catalog`, `reference/optional-skills-catalog`) remain indexed. - Add a new feature page `user-guide/features/curator.md` covering the curator subsystem merged in NousResearch#16049 and refined in NousResearch#17307 (per-run reports): how it runs, config, CLI (`hermes curator status/run/pin/ restore/...`), `.usage.json` telemetry, archival semantics, and recovery. Slotted into the Core features sidebar next to Skills. Search index size dropped from 5822 docs to 2704 in the main section; `user-guide/features/curator` is indexed.
1 parent 85d5881 commit 2f83f49

3 files changed

Lines changed: 165 additions & 0 deletions

File tree

‎website/docs/user-guide/features/curator.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
sidebar_position: 3
3+
title: "Curator"
4+
description: "Background maintenance for agent-created skills — usage tracking, staleness, archival, and LLM-driven review"
5+
---
6+
7+
# Curator
8+
9+
The curator is a background maintenance pass for **agent-created skills**. It tracks how often each skill is viewed, used, and patched, moves long-unused skills through `active → stale → archived` states, and periodically spawns a short auxiliary-model review that proposes consolidations or patches drift.
10+
11+
It exists so that skills created via the [self-improvement loop](/docs/user-guide/features/skills#agent-managed-skills-skill_manage-tool) don't pile up forever. Every time the agent solves a novel problem and saves a skill, that skill lands in `~/.hermes/skills/`. Without maintenance, you end up with dozens of narrow near-duplicates that pollute the catalog and waste tokens.
12+
13+
The curator **never touches** bundled skills (shipped with the repo) or hub-installed skills (from [agentskills.io](https://agentskills.io)). It only reviews skills the agent itself authored. It also **never auto-deletes** — the worst outcome is archival into `~/.hermes/skills/.archive/`, which is recoverable.
14+
15+
Tracks [issue #7816](https://github.com/NousResearch/hermes-agent/issues/7816).
16+
17+
## How it runs
18+
19+
The curator is triggered by an inactivity check, not a cron daemon. On CLI session start, and on a recurring tick inside the gateway's cron-ticker thread, Hermes checks whether:
20+
21+
1. Enough time has passed since the last curator run (`interval_hours`, default **7 days**), and
22+
2. The agent has been idle long enough (`min_idle_hours`, default **2 hours**).
23+
24+
If both are true, it spawns a background fork of `AIAgent` — the same pattern used by the memory/skill self-improvement nudges. The fork runs in its own prompt cache and never touches the active conversation.
25+
26+
A run has two phases:
27+
28+
1. **Automatic transitions** (deterministic, no LLM). Skills unused for `stale_after_days` (30) become `stale`; skills unused for `archive_after_days` (90) are moved to `~/.hermes/skills/.archive/`.
29+
2. **LLM review** (single aux-model pass, `max_iterations=8`). The forked agent surveys the agent-created skills, can read any of them with `skill_view`, and decides per-skill whether to keep, patch (via `skill_manage`), consolidate overlapping ones, or archive via the terminal tool.
30+
31+
Pinned skills bypass all auto-transitions and the LLM is instructed not to touch them.
32+
33+
## Configuration
34+
35+
All settings live in `config.yaml` under `curator:` (not `.env` — this isn't a secret). Defaults:
36+
37+
```yaml
38+
curator:
39+
enabled: true
40+
interval_hours: 168 # 7 days
41+
min_idle_hours: 2
42+
stale_after_days: 30
43+
archive_after_days: 90
44+
auxiliary:
45+
provider: null # null = use main auxiliary client resolution
46+
model: null
47+
```
48+
49+
To disable entirely, set `curator.enabled: false`.
50+
51+
To use a cheaper aux model for the LLM review pass instead of your main model, set `curator.auxiliary.provider` and `curator.auxiliary.model` to something specific (e.g. `openrouter` + `google/gemini-3-flash-preview`).
52+
53+
## CLI
54+
55+
```bash
56+
hermes curator status # last run, counts, pinned list, LRU top 5
57+
hermes curator run # trigger a review now (background by default)
58+
hermes curator run --sync # same, but block until the LLM pass finishes
59+
hermes curator pause # stop runs until resumed
60+
hermes curator resume
61+
hermes curator pin <skill> # never auto-transition this skill
62+
hermes curator unpin <skill>
63+
hermes curator restore <skill> # move an archived skill back to active
64+
```
65+
66+
`hermes curator status` also lists the five least-recently-used skills — a quick way to see what's likely to become stale next.
67+
68+
The same subcommands are available as the `/curator` slash command inside a running session (CLI or gateway platforms).
69+
70+
## What "agent-created" means
71+
72+
A skill is considered agent-created if its name is **not** in:
73+
74+
- `~/.hermes/skills/.bundled_manifest` (skills copied from the repo on install), and
75+
- `~/.hermes/skills/.hub/lock.json` (skills installed via `hermes skills install`).
76+
77+
Everything else in `~/.hermes/skills/` is fair game for the curator. This includes:
78+
79+
- Skills the agent saved via `skill_manage(action="create")` during a conversation.
80+
- Skills you created manually with a hand-written `SKILL.md`.
81+
- Skills added via external skill directories you've pointed Hermes at.
82+
83+
If you want to protect a specific skill from ever being touched — for example a hand-authored skill you rely on — use `hermes curator pin <name>`. The pin is a hard guarantee enforced at the shared mutation helper; no code path that would archive, consolidate, or state-transition a skill can bypass it.
84+
85+
## Usage telemetry
86+
87+
The curator maintains a sidecar at `~/.hermes/skills/.usage.json` with one entry per skill:
88+
89+
```json
90+
{
91+
"my-skill": {
92+
"use_count": 12,
93+
"view_count": 34,
94+
"last_used_at": "2026-04-24T18:12:03Z",
95+
"last_viewed_at": "2026-04-23T09:44:17Z",
96+
"patch_count": 3,
97+
"last_patched_at": "2026-04-20T22:01:55Z",
98+
"created_at": "2026-03-01T14:20:00Z",
99+
"state": "active",
100+
"pinned": false,
101+
"archived_at": null
102+
}
103+
}
104+
```
105+
106+
Counters increment when:
107+
108+
- `view_count`: the agent calls `skill_view` on the skill.
109+
- `use_count`: the skill is loaded into a conversation's prompt.
110+
- `patch_count`: `skill_manage patch/edit/write_file/remove_file` runs on the skill.
111+
112+
Bundled and hub-installed skills are explicitly excluded from telemetry writes.
113+
114+
## Per-run reports
115+
116+
Every curator run writes a timestamped directory under `~/.hermes/logs/curator/`:
117+
118+
```
119+
~/.hermes/logs/curator/
120+
└── 20260429-111512/
121+
├── run.json # machine-readable: full fidelity, stats, LLM output
122+
└── REPORT.md # human-readable summary
123+
```
124+
125+
`REPORT.md` is a quick way to see what a given run did — which skills transitioned, what the LLM reviewer said, which skills it patched. Good for auditing without having to grep `agent.log`.
126+
127+
## Restoring an archived skill
128+
129+
If the curator archived something you still want:
130+
131+
```bash
132+
hermes curator restore <skill-name>
133+
```
134+
135+
This moves the skill back from `~/.hermes/skills/.archive/` to the active tree and resets its state to `active`. The restore refuses if a bundled or hub-installed skill has since been installed under the same name (would shadow upstream).
136+
137+
## Disabling per environment
138+
139+
The curator is on by default. To turn it off:
140+
141+
- **For one profile only:** edit `~/.hermes/config.yaml` (or the active profile's config) and set `curator.enabled: false`.
142+
- **For just one run:** `hermes curator pause` — the pause persists across sessions; use `resume` to re-enable.
143+
144+
The curator also refuses to run if `min_idle_hours` hasn't elapsed, so on an active dev machine it naturally only runs during quiet stretches.
145+
146+
## See also
147+
148+
- [Skills System](/docs/user-guide/features/skills) — how skills work in general and the self-improvement loop that creates them
149+
- [Memory](/docs/user-guide/features/memory) — a parallel background review that maintains long-term memory
150+
- [Bundled Skills Catalog](/docs/reference/skills-catalog)
151+
- [Issue #7816](https://github.com/NousResearch/hermes-agent/issues/7816) — original proposal and design discussion

‎website/docusaurus.config.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,19 @@ const config: Config = {
4040
// Disabled: appends ?_highlight=... to URLs (before the #anchor),
4141
// which makes copy/pasted doc links ugly. Ctrl+F on the page is fine.
4242
highlightSearchTermsOnTargetPage: false,
43+
// Exclude the auto-generated per-skill catalog pages from search.
44+
// There are hundreds of them and they dominate results for generic
45+
// terms, drowning out the real user-guide / reference docs.
46+
// The two human-written catalog indexes (reference/skills-catalog,
47+
// reference/optional-skills-catalog) remain indexed.
48+
//
49+
// Note: ignoreFiles matches `route` (baseUrl stripped, no leading
50+
// slash). With baseUrl '/docs/', `/docs/user-guide/skills/bundled/x`
51+
// becomes 'user-guide/skills/bundled/x'.
52+
ignoreFiles: [
53+
/^user-guide\/skills\/bundled\//,
54+
/^user-guide\/skills\/optional\//,
55+
],
4356
}),
4457
],
4558
],

‎website/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ const sidebars: SidebarsConfig = {
4444
items: [
4545
'user-guide/features/tools',
4646
'user-guide/features/skills',
47+
'user-guide/features/curator',
4748
'user-guide/features/memory',
4849
'user-guide/features/memory-providers',
4950
'user-guide/features/context-files',

0 commit comments

Comments
 (0)