hermes-skills/skill-library-maintenance/SKILL.md

name, description, version, author, license, platforms, metadata

name	description	version	author	license	platforms	metadata
skill-library-maintenance	Triage, disable, and clean up the Hermes skill library AND manage all Hermes maintenance settings (sessions, checkpoints, cron, logging, updates, curator). Covers classification methodology, bulk disable via rename, stale-skill cron jobs, toolset management, and the full maintenance config landscape.	1.1.0	agent	MIT	linux	hermes tags skills maintenance cleanup triage devops

Skill Library Maintenance

Triage, disable, and clean up the Hermes skill library. Use when the user wants to reduce token bloat from unused skills, audit what's installed, or set up automated stale-skill cleanup.

Trigger Conditions

• User asks to disable skills/tools
• User wants to trim the skill library
• User asks "which skills do I actually use?"
• User wants automated stale-skill cleanup

Classification Methodology

When triaging skills, group into four buckets:

1. HAVE USED — clear evidence from session history or memory. Keep.
2. LIKELY USE — fits the user's known workflow but no direct evidence. Keep unless user says otherwise.
3. MAYBE — plausible but uncertain. Present to user for decision.
4. UNLIKELY — doesn't fit user's domain, platform, or preferences. Safe to disable.

Also filter: any skill requiring an API key the user doesn't have configured should be disabled.

How to Disable a Skill

Rename SKILL.md to SKILL.md.disabled in the skill directory. This removes it from the <available_skills> block without deleting it.

# Per-skill
mv ~/.hermes/profiles/dev/skills/<category>/<skill-name>/SKILL.md \
   ~/.hermes/profiles/dev/skills/<category>/<skill-name>/SKILL.md.disabled

# Restore
mv ~/.hermes/profiles/dev/skills/<category>/<skill-name>/SKILL.md.disabled \
   ~/.hermes/profiles/dev/skills/<category>/<skill-name>/SKILL.md

This is profile-scoped — only affects the profile whose skills directory you touch.

Nuke-and-Restore Pattern (bulk removal with selective keep)

When the user wants to strip a profile down to a small, known set of keepers, the nuke-and-restore pattern is faster and cleaner than selective removal:

# 1. Nuke everything
rm -rf ~/.hermes/profiles/<profile>/skills/*

# 2. Recreate category dirs and copy only keepers from a source profile
mkdir -p ~/.hermes/profiles/<profile>/skills/{cat1,cat2,...}
cp -r ~/.hermes/profiles/<source>/skills/<cat>/<skill> ~/.hermes/profiles/<profile>/skills/<cat>/
# ... repeat for each keeper

# 3. Verify
find ~/.hermes/profiles/<profile>/skills -name "SKILL.md" | wc -l

Pitfall: rm -rf skills/* nukes everything including keepers. Have the restore commands ready to run immediately after — don't leave the profile in an empty state. If the user says "remove all," confirm whether they mean "remove all EXCEPT the keepers we just discussed" before nuking.

How to Disable Tools

Tools are managed via hermes tools enable/disable (interactive TUI) or by editing platform_toolsets in config.yaml. The TUI requires an interactive terminal — can't be scripted.

Automated Stale-Skill Cleanup

Use a script-only cron job that reads .usage.json and disables skills unused for N days. See scripts/disable-stale-skills.sh for the reference implementation.

Key design decisions:

• no_agent: true — script-only, no LLM cost
• deliver: local — output saved, no messaging spam
• Script reads last_used_at from .usage.json, compares against cutoff, renames SKILL.md → SKILL.md.disabled
• Already-disabled skills are skipped
• Only touches the target profile's skills directory

Hermes Maintenance Config Landscape

Beyond skills, Hermes has several auto-maintenance systems controlled via config.yaml. These should be audited and aligned across profiles. See references/hermes-maintenance-settings.md for the full reference.

Settings to audit per profile

Section	Key	What it does	Default
sessions	auto_prune	Auto-delete ended sessions	false
sessions	retention_days	Days to keep ended sessions	90
sessions	vacuum_after_prune	Reclaim disk after prune	true
sessions	min_interval_hours	Min hours between sweeps	24
curator	enabled	Background skill maintenance	true
curator	interval_hours	Days between curator runs	168
curator	stale_after_days	Mark skill stale after N days	30
curator	archive_after_days	Archive skill after N days	90
curator	consolidate	LLM umbrella-building pass	false
curator	prune_builtins	Archive unused bundled skills	true
curator.backup	keep	Number of curator snapshots	5
checkpoints	auto_prune	Auto-delete old checkpoints	varies
checkpoints	retention_days	Days to keep checkpoints	varies
checkpoints	max_snapshots	Max checkpoint snapshots	50
cron	output_retention	Max cron outputs to keep	varies
logging	max_size_mb	Log file max size	5
logging	backup_count	Rotated log files to keep	3
updates	backup_keep	Pre-update backups to keep	5
model_catalog	ttl_hours	Model catalog cache TTL	1

Base config inheritance pattern

The cleanest approach: set all maintenance values once in ~/.hermes/config.yaml (base), then strip those keys from every profile config. Profiles inherit from base — if a key isn't in the profile config, it falls through to the base value. One place to change, all profiles follow.

To audit current state across all profiles, use execute_code to read and diff all configs. See references/hermes-maintenance-settings.md for the audit script.

Applying changes across profiles

When making config changes across all profiles, do them one at a time — individual hermes -p <name> config set calls per profile. Do not batch or script them. The user wants to see each one complete.

hermes -p <profile> config set sessions.auto_prune true
hermes -p <profile> config set sessions.retention_days 1
# ... repeat per profile

Pitfall: retention_days minimum

sessions.retention_days only accepts whole days. The minimum is 1 (24 hours). There is no hours-level granularity. If the user wants sessions pruned faster than 1 day, that's not possible via this setting — manual hermes sessions prune is the only path.

• The Curator only manages agent-created skills. It won't touch bundled, hub-installed, or manually-created skills. Manual disable via rename is the only path for those.
• hermes skills config requires an interactive terminal. Can't run it from a subprocess or script.
• Cron job scripts must live in ~/.hermes/scripts/, not profile-specific directories. The scheduler enforces this. If you write a script to a profile directory, copy it to ~/.hermes/scripts/ before creating the cron job.
• Disabling a skill doesn't remove it from the Curator's scope. The .usage.json entry persists. If you want it fully gone, uninstall hub skills or delete local ones.
• Tool changes need a /reset — they don't apply mid-conversation.
• Directory name ≠ SKILL.md name mismatch. Some skills have different directory names than their name field in SKILL.md frontmatter (e.g., directory audiocraft → name audiocraft-audio-generation, directory vllm → name serving-llms-vllm). When bulk-disabling by name, walk the filesystem and read each SKILL.md's frontmatter name field — don't assume the directory name matches. A find_skill_dir() that searches by directory basename will miss these.
• hermes skills list output uses directory names, not SKILL.md name fields. Cross-reference both when auditing.

Verification

After bulk-disabling skills:

# Count active vs disabled
find ~/.hermes/profiles/dev/skills -name "SKILL.md" | wc -l
find ~/.hermes/profiles/dev/skills -name "SKILL.md.disabled" | wc -l

# Verify no missing deps in kept skills
hermes skills list | grep -c enabled

After any triage session, produce an inventory file (e.g., dev_skill.md) listing every skill with state and disable reason. This catches mismatches between the intended keep/disable list and actual disk state. See references/dev-skill-inventory-example.md for the format.