skill-retrieval

Skill Retrieval

This is a Hermes Agent plugin. It is not a Claude Code plugin and will not load in Claude Code — that runtime has no pre_llm_call event, no Python register() entry point, and reads .claude-plugin/plugin.json rather than plugin.yaml. Requires Hermes Agent >=0.21.1 (requires_hermes in plugin.yaml).

BM25-based progressive disclosure for Hermes Agent skills. Instead of dumping every skill description into the system prompt (~11.5K tokens), this plugin keeps a compact names-only index and injects only the top-K relevant descriptions per turn.

What it does

Two-phase progressive disclosure:

1. Phase 1 — System prompt compaction (an llm_request middleware): Rewrites the outgoing request's <available_skills> block so it lists skill names only (descriptions stripped). All skills remain discoverable by name (~2K tokens instead of ~11.5K). The system prompt Hermes builds is never modified — prompt caching is unaffected.

2. Phase 2 — Per-turn BM25 retrieval (pre_llm_call hook): Tokenizes the user message, ranks active skill descriptions with BM25 Okapi, and injects the top-K matches (~300 tokens) as context appended after the user message.

Architecture

Each turn (llm_request middleware)
    │
    ▼
Phase 1: rewrite <available_skills> → names only (~2K tokens, request only)

Each turn (pre_llm_call)
    │
    ▼
Phase 2: BM25Index.retrieve(user_message, top_k)
    └── inject "## Retrieved Skills ..." into user message (~300 tokens)

The BM25 index is built lazily on the first turn from standalone skills (~/.hermes/skills) and plugin-bundled skills (~/.hermes/plugins/*/skills), then cached per Hermes home, tool capability snapshot, session platform and resolved disabled-skill set (the same inputs Hermes keys its own skills prompt cache on). The cache is rebuilt without a restart when Hermes clears its skills prompt cache (skill_manage create/patch/delete, hub install, skill toggles) or when a cheap on-disk manifest changes (skill root and category dir mtimes, top-level SKILL.md files, config.yaml). Retrieval uses a pure-stdlib inverted index (term → posting list of precomputed BM25 weights) and is sub-millisecond for ~200 skills.