[Feature Proposal]: .library — Protected Cold Storage for Skills + Intelligent Librarian + Curator Compactor

Related issues:

• #2045 (Lazy skill loading — remove full skill listing from system prompt)
• #18900, #26451, #18809 (skill discovery leaks into .archive and hidden dirs)
• Curator implementation (agent/curator.py and docs)

Edit note (2026-05-31): Original draft contained specific personal skill names. This version has been sanitized for privacy.

Summary

Introduce a new protected, hard-excluded directory ~/.hermes/skills/.library/ (and support for it under external_dirs and shared skill repos).

• Skills placed here are completely invisible to the normal skill index that gets injected into every system prompt.
• Hermes gains a "Librarian" behavior that activates when the agent or user refers to a skill that isn't currently available in the active catalog.
• The existing Curator gets a new "compactor" mode that identifies long-dormant skills (across user, shared, and agent-created) and proposes (or executes) moves into .library to reclaim prompt tokens.
• Activation is always explicit user approval (move/copy from .library into a real category folder).

This directly attacks the skill catalog bloat problem that power users (especially those syncing large shared-skills repos with 50-100+ niche skills) experience today.

The Core Problem (Beyond #2045)

Even with lazy body loading (SKILL.md content only read on skill_view), the skill index (name + description for every skill) still gets dumped into the prompt on every turn for many users.

Current reality for heavy users:

• Bundled skills + optional skills + external_dirs from shared skill collections (covering categories such as devops, github, lifestyle, creative, integrations with external tools, etc.).
• Dozens of highly specific, occasionally useful skills: hardware and machine maintenance tools, creative/content generation skills, game server and VTT tooling, document/PDF processing variants, social media and service monitors, integration families for third-party applications, and many narrow one-off utilities.
• Many of these are used once every few months or only in specific contexts (cron/no_agent scripts, one-off maintenance, specialized campaign prep).

Result: the <available_skills> block keeps growing. Every message on Discord/Telegram pays the tax. The Curator helps a little (only for agent-authored skills, moves to .archive), but:

• .archive still leaks in some discovery paths.
• No systematic way for the agent to know "this skill exists but is parked".
• No good UX when a user says "use the creative generator skill" or "we need a skill that does X" and it isn't in the active list.

Proposed Design

1. .library/ as a First-Class Protected Exclusion

• Hardcoded exclusion in all skill discovery code paths:

  • iter_skill_index_files
  • _find_skill / rglob walks
  • skills_list
  • Any prompt construction for <available_skills>
  • skill_view by bare name (must use explicit path or go through librarian)

• .library can contain the same category structure as the main skills/ (e.g. .library/devops/, .library/creative/my-content-tool/, .library/productivity/document-processor/).

• Optional: support for a top-level README.md or INDEX.md in .library for human browsing.

• Git behavior: .library/ should be .gitignore'd by default in ~/.hermes/ (recoverable via shared repo or explicit backup). Users who want versioned libraries can opt-in via config or place a pointer in their shared skill repo under .library/.

• Stronger protection than .archive: even direct skill_view("/full/path/to/.library/...") should perhaps warn or require explicit librarian gate for safety.

2. The Skill Librarian (the "when to search" intelligence)

The agent should automatically consider the library in these situations (without the descriptions ever being in the base prompt):

Detection triggers (examples):

• User directly references a skill by name that is not in the current active index: "Use the creative-content skill for this", "Run the hardware maintenance skill", "The document processing one you had before".
• User proposes a capability: "We should build a skill for monitoring free game weekends on X" or "I need something that parses complex documents with layout preservation".
• Agent self-reflection during planning: "I don't have a skill for VTT world migration state tracking. Checking if one exists..."
• Explicit command: hermes skills library search "pdf ocr" or in-chat "search my skill library for pdf stuff".

Librarian behavior:

1. Perform name + keyword + semantic match against all SKILL.md files under .library/ (and any configured skills.library.external_paths).

2. For promising candidates, read the full SKILL.md (cheap, on-demand, not pre-loaded).

3. Optionally peek at references/, templates/, or first few lines of scripts/ to understand scope.

4. Present a crisp proposal to the user:

   Found 2 candidates in .library:
   
   1. creative-content-generator (creative/)
      Last used: 2025-11-14 (moved by curator 6 months ago)
      Description: Handles branded content generation with specific image prompt rules and data output contracts.
      Matches your request because: user mentioned "creative content" + branding rules.
      Move to skills/creative/creative-content-generator/ and activate? [y] / view full SKILL.md / skip
   
   2. social-media-monitor (devops/)
      ...

5. On approval: perform the move (with safety: copy to temp first? or direct move with git-friendly handling). Update any references in shared sync scripts, crons, etc. if detected.

6. Log the activation so future curator passes know it was recently revived.

Config knobs (in ~/.hermes/config.yaml or skills section):

skills:
  library:
    enabled: true
    search_paths:
      - ~/.hermes/skills/.library
      - /mnt/c/git/shared-skills-repo/.library   # example for shared
    auto_propose_on_missing_ref: true
    semantic_search: true   # or keyword-only for lighter

3. Curator Compactor (the proactive "free space in system prompt" agent)

Enhance the existing Curator (or add a parallel "Compactor" pass) with these capabilities:

• Track usage for all skills, not just agent-created ones (views via skill_view, invocations via tool gateway, references in crons/no_agent scripts, etc.).

• Configurable thresholds:

  • curator.library_compaction_days: default e.g. 90 or 120
  • curator.library_min_invocations: e.g. < 5 lifetime

• On a compaction pass (inactivity-triggered background fork, same pattern as current curator):

  • Identify candidates across user skills + external/shared.

  • Produce a batch proposal (never silent auto-move for non-agent-created skills):

    Curator Compaction Proposal (2026-05-31)
    
    These 9 skills have seen zero activity in 120+ days and <3 total invocations:
    
    | Skill                              | Category     | Last View | Lifetime Uses | Notes |
    |------------------------------------|--------------|-----------|---------------|-------|
    | machine-maintenance-tool           | devops       | 2026-01-12| 2             | Specialized hardware fixes mostly superseded by newer tools |
    | third-party-integration-lifecycle  | integrations | 2025-12-03| 1             | ...
    | niche-game-tool-family             | creative     | 2026-02-20| 4             | ...
    | ... (more)
    
    Recommended action: Move the above to .library/ (preserving category structure).
    
    Approve batch? [y] / review individually / adjust thresholds / never for these

• "Direct move" option for power users (like --yolo): hermes curator --compaction --execute

• After move, the skill is still fully recoverable via librarian.

• Special handling for skills referenced in active crons or no_agent scripts (flag them, don't auto-propose).

This turns the curator from "garbage collection for agent slop" into a general "prompt token hygiene" system.

Rich Examples (the surface was only scratched)

Example 1 — Direct user reference to a parked skill (most common trigger)

User: "Hermes, the creative content generator one you made for me last year — can you generate a new set using the latest branding prompt style?"

Current behavior (today): Agent either hallucinates or says "I don't have that skill loaded" and the user has to remember where they put it or manually skill_view a path.

Proposed: Agent detects the referenced skill not in active index. Librarian scans .library/creative/. Finds it (name + description keywords). Reads the SKILL.md (which contains the full prompt rules, output contracts, etc.). Replies:

"I have 'creative-content-generator' parked in .library/creative/ since the curator moved it after 7 months of inactivity. It knows the full branding rules, theming, variants, and data output contract.

Last activation: 2025-10. Move it back to skills/creative/creative-content-generator/ so it's always available? (y/n/view full file)"

Example 2 — User proposes a capability that already exists in library (from shared skills or old experiment)

User (in a planning session): "We need something that watches X.com for free game weekends and posts nicely formatted drops to Telegram, with the weekend flag logic."

Agent: "No active skill matches that exactly. Scanning library + shared...

Found 'social-media-free-games-watcher' in .library/devops/ (originally from a shared skill sync).

It already implements the weekend flag field, Telegram delivery, and state tracking you described in the watcher crons.

Description excerpt: [..]

This was archived after low usage. Activate by moving to skills/devops/social-media-free-games-watcher/ ?"

Example 3 — Batch compactor proposal during a quiet period

(Background curator fork, delivered via cron or on next session)

"Compactor pass complete. Prompt bloat reduction opportunity:

12 skills qualify under current thresholds (120 days no views, <4 lifetime tool calls):

• github-issue-monitor (github/)
• third-party-debug-tool (integrations/)
• translation-family (3 skills)
• document-processor-installer (productivity/)
• ...

These are solid but narrow. Moving them to .library/ would remove ~280-350 tokens from every future system prompt while keeping them one librarian query away.

Batch move to .library preserving categories? [Approve] [Review list] [Skip for 30 days] [Change thresholds]"

Example 4 — Librarian helps during self-improvement / skill creation

Agent is about to create a new skill for "VTT world migration between instances with COPY not MOVE semantics".

Before writing a duplicate, it checks library:

"Similar capability exists in .library/foundry/vtt-migration-manager/SKILL.md (last touched 2026-04). It documents the exact COPY-not-MOVE rule + config patching + restart sequence you were about to implement.

Recommend: revive that one instead of creating a near-dupe?"

(This prevents the very skill drift the curator exists to fight.)

Example 5 — Category move + rename during activation

User had an old document-parser in library. Librarian finds it.

User: "Yeah, activate it but put it under productivity/ as 'advanced-document-processor' and update the description to match current standards (60 char dense)."

Librarian handles the move + light normalization.

Example 6 — Shared repo + multi-machine .library

User has a shared skill collection checked out.

Config points librarian at both local ~/.hermes/skills/.library and the repo's .library/ subtree.

When a skill is activated on one machine, the move happens locally; the shared sync script (or a future hermes skill) can optionally promote it back into the "active" part of the shared repo on next sync.

Example 7 — Safety and collision handling

• Name collision between active skill and one in library: librarian surfaces both and asks which to use / whether to rename the library one.
• Attempt to run a library skill directly: "This skill lives in .library. Use the librarian to activate it first (or call with full path for one-off)."
• Skills in .library that reference deleted external tools or old env vars: librarian can surface warnings when proposing activation ("This one declares env var FOO that is no longer in your central .env.").

Example 8 — Deep usage telemetry for better decisions

Over time the system tracks not just "last_view" but:

• Invocations via the tool gateway
• References inside cron prompts / no_agent scripts
• Mentions in user messages vs agent-initiated
• Whether the skill was patched after activation

This makes the compactor much smarter than simple time-based rules.

Implementation Notes & Questions for Maintainers

1. Discovery hardening: Make the exclusion list for .library (and keep .archive) truly leak-proof. Update every rglob/os.walk/Path iteration site. Consider a single is_skill_path_excluded() helper.

2. Usage tracking surface: Expose a lightweight, append-only usage log (or extend whatever the curator already uses) that the librarian and compactor can query efficiently. Should not require full conversation history.

3. Librarian as a tool vs. always-on behavior: Probably both. A dedicated skill_librarian tool that the agent can call explicitly, plus automatic triggering logic in the main loop / planning stages when a "missing skill" pattern is detected in user input or internal reasoning.

4. Move vs Copy semantics: Default to move (clean). Offer --copy or config for users who want the safety net of keeping the library copy (aligns with some existing migration preferences in the ecosystem).

5. CLI surface (important for power users):

   • hermes skills library list [--category X]
   • hermes skills library search "keyword or phrase"
   • hermes skills library activate <name-or-path> [--to-category productivity] [--copy]
   • hermes curator compaction --dry-run
   • hermes curator compaction --execute

6. Integration with existing user skills:

   • User-built skill management and lifecycle skills that already exist in the ecosystem should be able to delegate to the new core librarian/compactor instead of reinventing wheels.
   • Update skill description standards doc to mention .library placement rules.

7. Performance: Scanning a .library with hundreds of skills should be fast (index the library separately? or just rglob + cheap frontmatter parse on demand).

8. Backward compat: Existing .archive behavior unchanged. .library is additive.

Open questions:

• Should bundled skills ever be eligible for library compaction? (Probably never — they ship with the agent.)
• Hub-installed skills from agentskills.io?
• How deep should semantic matching be on first pass (simple keyword + description embedding vs full LLM re-rank)?
• Should there be a "pinned" or "never-compact" flag per skill (maybe a top-level field in SKILL.md frontmatter)?

Why This Is High Leverage

• Directly reduces per-message token cost for the users who need Hermes most (heavy customization + many categories).
• Makes the "agent that grows with you" actually sustainable as the skill graph grows over years.
• Turns accidental skill loss / "where did that thing go" into a delightful, low-friction retrieval experience.
• Builds naturally on the excellent Curator foundation instead of fighting it.
• Gives power users (the ones maintaining large shared skill collections, dozens of category-specific tools) a first-class place to park the long tail without constant manual hygiene.

This feels like the natural next evolution after lazy loading (#2045) and the initial Curator.

Ready to discuss scoping for an MVP (hard exclusion + basic name/keyword librarian + CLI + one compaction proposal path) vs full semantic version.

Labels suggestion: enhancement, skills, performance, ux, curator

Milestone? Skills system v2 or token efficiency track.

This proposal is grounded in real usage patterns from the shared-skills ecosystem and heavy daily operators. Happy to provide more telemetry or concrete (anonymized) skill counts from a real install if helpful.