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_public_surfaces.py
View on GitHub"""Public-surface contract extras: llm_request rewrite shapes and lifecycle."""
import types
import bm25_retriever as br
def _load_plugin():
import importlib.util
from pathlib import Path
plugin_dir = Path(__file__).resolve().parent.parent
spec = importlib.util.spec_from_file_location(
"skill_retrieval_public_surfaces", plugin_dir / "__init__.py"
)
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)
return mod
def _skills_prompt(extra=""):
return (
"preamble\n"
"<available_skills>\n"
" tools:\n"
" - demo: Performs several operations.\n"
" - other: Another tool.\n"
"</available_skills>\n"
+ extra
)
def test_llm_request_chat_completions_rewrites_system_message():
mod = _load_plugin()
prompt = _skills_prompt()
tools = [{"name": "skill_view"}]
req = {
"messages": [{"role": "system", "content": prompt}, {"role": "user", "content": "hi"}],
"tools": tools,
}
result = mod._on_llm_request(request=req, session_id="s1", platform="cli")
assert result is not None
new = result["request"]
text = new["messages"][0]["content"]
assert mod._COMPACT_SENTINEL in text
assert "- demo" in text
assert "Performs several operations" not in text
assert new["tools"] is tools
assert req["messages"][0]["content"] == prompt # original not mutated
snap = mod._session_capability_snaps["s1"]
assert snap[1] == frozenset({"demo", "other"})
assert mod._session_platforms["s1"] == "cli"
def test_llm_request_codex_rewrites_instructions_and_system_message():
mod = _load_plugin()
prompt = _skills_prompt()
req = {
"instructions": prompt,
"messages": [{"role": "system", "content": prompt}],
}
result = mod._on_llm_request(request=req, session_id="")
assert result is not None
assert mod._COMPACT_SENTINEL in result["request"]["instructions"]
assert mod._COMPACT_SENTINEL in result["request"]["messages"][0]["content"]
def test_llm_request_anthropic_preserves_cache_control_identity():
mod = _load_plugin()
prompt = _skills_prompt()
cache_control = {"type": "ephemeral"}
block = {"type": "text", "text": prompt, "cache_control": cache_control}
req = {"system": [block], "messages": [{"role": "user", "content": "hi"}]}
result = mod._on_llm_request(request=req, session_id="anth")
assert result is not None
new_block = result["request"]["system"][0]
assert new_block["cache_control"] is cache_control
assert mod._COMPACT_SENTINEL in new_block["text"]
assert block["text"] == prompt
def test_llm_request_missing_block_returns_none():
mod = _load_plugin()
assert mod._on_llm_request(
request={"messages": [{"role": "system", "content": "no skills here"}]},
session_id="",
) is None
def test_llm_request_does_not_touch_tools():
mod = _load_plugin()
tools = [{"name": "terminal", "desc": "run"}]
req = {
"messages": [{"role": "system", "content": _skills_prompt()}],
"tools": tools,
}
result = mod._on_llm_request(request=req, session_id="")
assert result["request"]["tools"] is tools
def test_register_installs_three_surfaces():
mod = _load_plugin()
seen = {"hooks": [], "mw": []}
class Ctx:
def register_hook(self, name, func):
seen["hooks"].append(name)
def register_middleware(self, name, func):
seen["mw"].append(name)
mod.register(Ctx())
assert "pre_llm_call" in seen["hooks"]
assert "on_skill_lifecycle" in seen["hooks"]
assert seen["mw"] == ["llm_request"]
def test_lifecycle_unknown_action_invalidates(monkeypatch):
mod = _load_plugin()
called = []
monkeypatch.setattr(mod, "clear_index_cache", lambda: called.append(1))
mod._on_skill_lifecycle(action="brand-new-action", skill_name="x")
assert called == [1]
mod._on_skill_lifecycle(action="loaded", skill_name="x")
assert called == [1]
def test_get_index_visible_names_filters_corpus(monkeypatch, tmp_path):
br._indexes_by_home.clear()
br._skills_by_home_and_id.clear()
br._manifest_by_key.clear()
root = tmp_path / "skills"
for rel, name, desc in (
("a", "alpha", "alpha token zebra"),
("b", "beta", "beta token yak"),
("c", "gamma", "gamma filler words"),
):
d = root / rel
d.mkdir(parents=True)
(d / "SKILL.md").write_text(
f'---\nname: {name}\ndescription: "{desc}"\n---\n\n# {name}\n'
)
pb = types.ModuleType("agent.prompt_builder")
pb._current_session_platform_hint = lambda: ""
pb.extract_skill_conditions = lambda fm: {}
pb._skill_should_show = lambda *a, **k: True
pb._parse_skill_file = lambda f: (True, {"name": br._parse_skill_md(f)[0]}, br._parse_skill_md(f)[1])
pb._build_snapshot_entry = lambda f, r, fm, desc: {
"category": "general",
"skill_name": f.parent.name,
"frontmatter_name": fm["name"],
"description": desc,
}
su = types.ModuleType("agent.skill_utils")
su.get_disabled_skill_names = lambda platform=None: set()
su.get_project_skills_dirs = lambda: []
su.get_all_skills_dirs = lambda: [root]
su.iter_project_skill_files = lambda r: sorted(r.rglob("SKILL.md"))
su.iter_skill_index_files = lambda r, filename: sorted(r.rglob(filename))
monkeypatch.setitem(__import__("sys").modules, "agent", types.ModuleType("agent"))
monkeypatch.setitem(__import__("sys").modules, "agent.prompt_builder", pb)
monkeypatch.setitem(__import__("sys").modules, "agent.skill_utils", su)
idx = br.get_index(visible_names=frozenset({"alpha", "gamma"}))
ids = [i for i, _ in idx.retrieve("alpha token beta token")]
assert "a" in ids
assert "b" not in ids
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 |