moonlight-lupin/agent-skills / plugins/skill-retrieval
skill-retrieval
VerifiedBM25-based skill retrieval plugin for Hermes Agent. Replaces the full skill list in the system prompt with a names-only compact view (~2K tokens) and injects top-K relevant skill descriptions per turn via BM25 retrieval (~300 tokens). Saves ~9K tokens/turn. Use when system prompt token overhead from skills is a concern, or when skill discovery quality matters.
tests/test_index_cache.py
View on GitHub"""BM25 index cache correctness (v0.3.1).
Bug 1: the cache key omitted the session platform. The corpus depends on it
(``skills.platform_disabled.<platform>`` and ``session_platforms`` gates), so
an index built by a discord session was reused by a telegram session and
suggested skills disabled for telegram.
Bug 2: the index was never invalidated for the process lifetime. New or
patched skills (``skill_manage``) and ``hermes skills disable`` were ignored
until restart. A zero-skill install also rescanned every root each turn.
"""
import importlib
import importlib.util
import logging
import pathlib
import sys
import types
import yaml
import bm25_retriever as br
_PLUGIN_DIR = pathlib.Path(__file__).resolve().parent.parent
def _load_fresh():
importlib.reload(br)
return br
def _load_plugin_init():
spec = importlib.util.spec_from_file_location(
"skill_retrieval_init_cache_test", _PLUGIN_DIR / "__init__.py"
)
mod = importlib.util.module_from_spec(spec)
sys.modules["skill_retrieval_init_cache_test"] = mod
spec.loader.exec_module(mod)
return mod
def _write_skill(root, rel, name, description):
skill_dir = root / rel
skill_dir.mkdir(parents=True, exist_ok=True)
(skill_dir / "SKILL.md").write_text(
f'---\nname: {name}\ndescription: "{description}"\n---\n\n# {name}\n'
)
def _install_hermes_stubs(monkeypatch, tmp_path, *roots):
"""Stub agent.prompt_builder / agent.skill_utils over a temp Hermes home.
``get_disabled_skill_names`` reads config.yaml on every call, like
Hermes (global list ∪ ``platform_disabled.<platform>``).
"""
home = tmp_path / "home"
home.mkdir(exist_ok=True)
monkeypatch.setenv("HERMES_HOME", str(home))
pb = types.ModuleType("agent.prompt_builder")
pb._current_session_platform_hint = lambda: ""
pb.extract_skill_conditions = lambda fm: {}
pb._skill_should_show = lambda conditions, tools, toolsets, platform=None: True
def _parse(skill_file):
name, desc, _body = br._parse_skill_md(skill_file)
return True, {"name": name}, desc
def _entry(skill_file, root, frontmatter, description):
return {
"category": "general",
"skill_name": skill_file.parent.name,
"frontmatter_name": frontmatter["name"],
"description": description,
}
pb._parse_skill_file = _parse
pb._build_snapshot_entry = _entry
pb.build_skills_system_prompt = lambda *a, **kw: ""
pb.clear_calls = []
pb.clear_skills_system_prompt_cache = (
lambda *, clear_snapshot=False: pb.clear_calls.append(clear_snapshot)
)
def _disabled(platform=None):
cfg_path = home / "config.yaml"
if not cfg_path.exists():
return set()
skills_cfg = (yaml.safe_load(cfg_path.read_text()) or {}).get("skills") or {}
out = set(skills_cfg.get("disabled") or [])
if platform:
out |= set((skills_cfg.get("platform_disabled") or {}).get(platform) or [])
return out
su = types.ModuleType("agent.skill_utils")
su.get_disabled_skill_names = _disabled
su.get_project_skills_dirs = lambda: []
su.get_all_skills_dirs = lambda: list(roots)
su.iter_project_skill_files = lambda root: sorted(root.rglob("SKILL.md"))
su.iter_skill_index_files = lambda root, filename: sorted(root.rglob(filename))
agent_pkg = types.ModuleType("agent")
agent_pkg.prompt_builder = pb
agent_pkg.skill_utils = su
monkeypatch.setitem(sys.modules, "agent", agent_pkg)
monkeypatch.setitem(sys.modules, "agent.prompt_builder", pb)
monkeypatch.setitem(sys.modules, "agent.skill_utils", su)
return {"pb": pb, "su": su, "home": home}
def _seed(root):
_write_skill(root, "a", "secret-skill", "zorblat payroll")
_write_skill(root, "b", "f1", "filler one")
_write_skill(root, "c", "f2", "filler two things")
def _ids(index, query):
return [skill_id for skill_id, _ in (index.retrieve(query) if index else [])]
# ─── Bug 1: platform-scoped cache key ────────────────────────────────────────
def test_platform_disabled_skill_not_reused_across_platforms(monkeypatch, tmp_path):
br = _load_fresh()
root = tmp_path / "skills"
_seed(root)
stubs = _install_hermes_stubs(monkeypatch, tmp_path, root)
(stubs["home"] / "config.yaml").write_text(
"skills:\n platform_disabled:\n telegram: [secret-skill]\n"
)
plat = {"v": "discord"}
stubs["pb"]._current_session_platform_hint = lambda: plat["v"]
assert "a" in _ids(br.get_index(), "zorblat") # built by a discord session
plat["v"] = "telegram" # skill is platform_disabled here
assert "a" not in _ids(br.get_index(), "zorblat")
plat["v"] = "discord"
assert "a" in _ids(br.get_index(), "zorblat")
def test_skill_info_uses_platform_scoped_key(monkeypatch, tmp_path):
"""get_skill_info must resolve against the same corpus as get_index."""
br = _load_fresh()
root = tmp_path / "skills"
_seed(root)
stubs = _install_hermes_stubs(monkeypatch, tmp_path, root)
(stubs["home"] / "config.yaml").write_text(
"skills:\n platform_disabled:\n telegram: [secret-skill]\n"
)
plat = {"v": "discord"}
stubs["pb"]._current_session_platform_hint = lambda: plat["v"]
br.get_index()
assert br.get_skill_info("a")["name"] == "secret-skill"
plat["v"] = "telegram"
br.get_index()
assert br.get_skill_info("a") is None
def test_platform_key_failure_degrades(monkeypatch, tmp_path):
"""A failing platform hint / disabled lookup must not raise from the key."""
br = _load_fresh()
stubs = _install_hermes_stubs(monkeypatch, tmp_path)
def boom(*_a, **_kw):
raise RuntimeError("no session context")
stubs["pb"]._current_session_platform_hint = boom
stubs["su"].get_disabled_skill_names = boom
assert br._session_platform_key_parts() == (None, None)
# ─── Bug 2: invalidation ─────────────────────────────────────────────────────
def test_new_skill_picked_up_without_restart(monkeypatch, tmp_path):
br = _load_fresh()
root = tmp_path / "skills"
_seed(root)
_install_hermes_stubs(monkeypatch, tmp_path, root)
assert _ids(br.get_index(), "quuxify") == []
# Dropped in by hand / another process: no clear_skills_system_prompt_cache.
_write_skill(root, "c-new", "quuxify-helper", "quuxify widgets")
assert "c-new" in _ids(br.get_index(), "quuxify")
assert br.get_skill_info("c-new")["name"] == "quuxify-helper"
def test_skill_disabled_via_config_dropped(monkeypatch, tmp_path):
br = _load_fresh()
root = tmp_path / "skills"
_seed(root)
stubs = _install_hermes_stubs(monkeypatch, tmp_path, root)
assert "a" in _ids(br.get_index(), "zorblat")
(stubs["home"] / "config.yaml").write_text("skills:\n disabled: [secret-skill]\n")
assert "a" not in _ids(br.get_index(), "zorblat")
def test_nested_skill_md_content_edit_invalidates_via_manifest(monkeypatch, tmp_path):
"""A content-only edit of a nested SKILL.md must rebuild without a hook.
Recursive ``_corpus_manifest`` stats SKILL.md files (not just directory
mtimes), so a nested rewrite is visible on the next get_index().
"""
br = _load_fresh()
root = tmp_path / "skills"
_seed(root)
_write_skill(root, "cat/deep", "deep-skill", "original words")
_install_hermes_stubs(monkeypatch, tmp_path, root)
assert "deep" in _ids(br.get_index(), "original")
_write_skill(root, "cat/deep", "deep-skill", "frobnicate spreadsheets")
assert "deep" in _ids(br.get_index(), "frobnicate")
assert "frobnicate" in br.get_skill_info("deep")["description"]
def test_on_skill_lifecycle_clears_index_except_loaded(monkeypatch, tmp_path):
"""on_skill_lifecycle observer drops the BM25 cache for mutations, not loads."""
br = _load_fresh()
root = tmp_path / "skills"
_seed(root)
_install_hermes_stubs(monkeypatch, tmp_path, root)
mod = _load_plugin_init()
calls = []
monkeypatch.setattr(mod, "clear_index_cache", lambda: calls.append("clear"))
monkeypatch.setattr(br, "clear_index_cache", lambda: calls.append("clear"))
mod._on_skill_lifecycle(action="loaded", skill_name="a")
assert calls == []
mod._on_skill_lifecycle(action="patched", skill_name="a")
assert calls == ["clear"]
mod._on_skill_lifecycle(action="created", skill_name="b")
assert calls == ["clear", "clear"]
def test_empty_corpus_cached_and_warned_once(monkeypatch, tmp_path, caplog):
br = _load_fresh()
root = tmp_path / "skills"
root.mkdir()
_install_hermes_stubs(monkeypatch, tmp_path, root)
calls = []
real_loader = br.load_active_skills
def counting_loader(*a, **kw):
calls.append(1)
return real_loader(*a, **kw)
monkeypatch.setattr(br, "load_active_skills", counting_loader)
with caplog.at_level(logging.WARNING, logger=br.logger.name):
for _ in range(5):
assert br.get_index() is None
assert len(calls) == 1
assert sum("No active skills" in r.getMessage() for r in caplog.records) == 1
_seed(root)
assert "a" in _ids(br.get_index(), "zorblat")
assert len(calls) == 2
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |