\n<\/p>\n
AgentSkillOS-powered semantic skill retrieval for Hermes Agent.<\/p>\n
Pre-filters 1,200+ skills (998 community corpus + 211 Hermes skills) organized in a 10,000-category capability taxonomy to the top-5 most relevant per query. Runs as a Hermes pre_llm_call plugin \u2014 zero core modification, zero additional API cost (borrows your existing Hermes LLMs via borrow-mode).<\/p>\n
Pure semantic retrieval prioritizes textual similarity and misses skills that look unrelated in embedding space but are crucial for solving the task. Our LLM + Skill Tree navigates the capability hierarchy to surface non-obvious but functionally relevant skills.<\/p>\n
Left: Pure semantic retrieval is narrow and myopic. Right: Skill Tree navigation surfaces functionally relevant skills the embedding space hides.<\/p>\n
Skills are organized into a coarse-to-fine capability hierarchy. At scale, this is the difference between finding the right skill and drowning in an invisible pile.<\/p>\n
The 10,000-category capability tree \u2014 the structure our 1,200 skills are mapped into.<\/p>\n
User Query
\n \u2502
\n \u25bc
\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
\n\u2502 pre_llm_call hook (plugin) \u2502
\n\u2502 Checks DISABLE flag, skips short Qs \u2502
\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
\n \u2502
\n \u25bc
\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
\n\u2502 Searcher.search() \u2502
\n\u2502 1. Load capability tree from YAML \u2502
\n\u2502 2. LLM-navigate tree (select nodes) \u2502
\n\u2502 3. Parallel child search (ThreadPool)\u2502
\n\u2502 4. LLM prune (dedup + rank) \u2502
\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
\n \u2502
\n \u25bc
\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
\n\u2502 Hint Injection \u2502
\n\u2502 Prepends top-5 skill hints as \u2502
\n\u2502 natural-language block. LLM may call \u2502
\n\u2502 skill_view(name) to load any. \u2502
\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518<\/p>\n
Why not just use Hermes OOTB?
\nHermes already ships with skill discovery \u2014 every user-installed skill appears in the block of the system prompt. The LLM scans this flat list every turn and calls skill_view() when needed. For small sets it works fine.
\nskill-retriever adds a semantic retrieval layer that transforms skill discovery from “read the catalog” into “search for what you need”:<\/p>\n
Dimension
\nHermes OOTB
\nskill-retriever<\/p>\n
Skill source
\nYour local ~\/.hermes\/skills\/ only (~100-200)
\nCommunity corpus (998) + Hermes skills (200) = 1,198 total<\/p>\n
Discovery
\nFlat name+desc list in system prompt every turn
\nLLM-navigated taxonomy tree \u2192 top-5 relevant injected as hints<\/p>\n
Token cost
\nEvery turn burns tokens for all skills, even irrelevant ones
\nZero system prompt overhead \u2014 hints only in user message, only when found<\/p>\n
Categorization
\nFilesystem directory names
\n10,000-category AgentSkillOS capability taxonomy<\/p>\n
Scales to
\n~200 skills before prompt bloat
\n10K+ (tree handles it)<\/p>\n
Latency per turn
\n0 (passive \u2014 always visible)
\n+1-3 cheap LLM calls for tree traversal (when it has results)<\/p>\n
Community corpus
\nNo
\nYes \u2014 998 community skills alongside yours<\/p>\n
The difference: OOTB gives you a flat skill catalog you read every turn. skill-retriever turns it into a search engine \u2014 describe what you need, the tree navigates to the right category, and only relevant suggestions appear. The tradeoff is a small latency cost per turn vs constant system prompt bloat.<\/p>\n
git clone https:\/\/github.com\/ChonSong\/skill-retriever.git
\ncd skill-retriever
\nbash scripts\/install.sh
\nhermes gateway restart<\/p>\n
Every skill carries a source tag and a safety scan result:<\/p>\n
Badge
\nMeaning<\/p>\n
\ud83d\udd12hermes
\nInstalled via Hermes \u2014 trusted<\/p>\n
\ud83c\udf10community
\nFrom AgentSkillOS corpus \u2014 unreviewed<\/p>\n
\u26a0\ufe0f (suffix)
\nFlagged by safety scan \u2014 review before loading<\/p>\n
All 1,200 skills were scanned for dangerous patterns (rm -rf \/, curl | sh to raw IPs, base64 payloads, crypto miners). Zero flagged \u2014 every match was standard installer documentation inside code blocks.<\/p>\n
python -m skill_retriever search “set up CI\/CD pipeline”
\npython -m skill_retriever build # rebuild capability tree
\npython -m skill_retriever list # list all skills in corpus
\npython -m skill_retriever info # system info + tree stats<\/p>\n
All settings via environment variables \u2014 no config files needed.<\/p>\n
Env Variable
\nDefault
\nDescription<\/p>\n
SKILL_RETRIEVER_DISABLE
\n\u2014
\nSet 1 to disable entirely<\/p>\n
SKILL_RETRIEVER_LLM_MODEL
\ngpt-4o
\nLLM model for skill gate<\/p>\n
SKILL_RETRIEVER_LLM_API_KEY
\nOPENAI_API_KEY
\nAPI key<\/p>\n
SKILL_RETRIEVER_LLM_BASE_URL
\nOPENAI_BASE_URL
\nBase URL<\/p>\n
SKILL_RETRIEVER_BRANCHING_FACTOR
\n3
\nTree branching (search)<\/p>\n
SKILL_RETRIEVER_MAX_PARALLEL
\n5
\nParallel search branches<\/p>\n
SKILL_RETRIEVER_TEMPERATURE
\n0.3
\nLLM temperature<\/p>\n
SKILL_RETRIEVER_PRUNE
\ntrue
\nEnable dedup\/ranking step<\/p>\n
SKILL_RETRIEVER_TREE_PATH
\nbundled tree_10000.yaml
\nOverride capability tree<\/p>\n
See ARCHITECTURE.md for a technical deep-dive covering:<\/p>\n
Capability tree structure and build process
\nLLM node selection algorithm
\nSearcher internals (parallel search, early stop, pruning)
\nPlugin hook integration
\nDirectory layout<\/p>\n
Hermes Agent v0.18+
\nPython 3.10+
\n~500MB for capability tree index
\n~4GB for full skill corpus (optional, for rebuilding tree)<\/p>\n
skill-retriever\/
\n\u251c\u2500\u2500 plugin\/ # Hermes plugin (pre_llm_call hook)
\n\u251c\u2500\u2500 src\/
\n\u2502 \u251c\u2500\u2500 skill_retriever\/ # Core engine
\n\u2502 \u2502 \u251c\u2500\u2500 cli.py # CLI (search, build, list, info)
\n\u2502 \u2502 \u251c\u2500\u2500 search\/ # Searcher (multi-level LLM tree search)
\n\u2502 \u2502 \u251c\u2500\u2500 tree\/ # Tree builder, schema, prompts, scanner
\n\u2502 \u2502 \u2514\u2500\u2500 capability_tree\/# Pre-built trees (YAML + HTML)
\n\u2502 \u2514\u2500\u2500 scanner.py # Hermes skills scanner
\n\u251c\u2500\u2500 data\/ # Skill corpus (gitignored)
\n\u251c\u2500\u2500 tests\/ # 40 tests
\n\u251c\u2500\u2500 scripts\/install.sh # One-click Hermes plugin install
\n\u2514\u2500\u2500 ARCHITECTURE.md<\/p>\n