# Skill Retriever semantic skill discovery for AI agents via 10K-category taxonomy > Source: > Published: 2026-07-08 05:36:19+00:00 AgentSkillOS-powered semantic skill retrieval for Hermes Agent. 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 — zero core modification, zero additional API cost (borrows your existing Hermes LLMs via borrow-mode). 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. *Left: Pure semantic retrieval is narrow and myopic. Right: Skill Tree navigation surfaces functionally relevant skills the embedding space hides.*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. *The 10,000-category capability tree — the structure our 1,200 skills are mapped into.* ``` User Query │ ▼ ┌──────────────────────────────────────┐ │ pre_llm_call hook (plugin) │ │ Checks DISABLE flag, skips short Qs │ └──────────────┬───────────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ Searcher.search() │ │ 1. Load capability tree from YAML │ │ 2. LLM-navigate tree (select nodes) │ │ 3. Parallel child search (ThreadPool)│ │ 4. LLM prune (dedup + rank) │ └──────────────┬───────────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ Hint Injection │ │ Prepends top-5 skill hints as │ │ natural-language block. LLM may call │ │ skill_view(name) to load any. │ └──────────────────────────────────────┘ ``` Hermes already ships with skill discovery — 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. skill-retriever adds a **semantic retrieval layer** that transforms skill discovery from "read the catalog" into "search for what you need": | Dimension | Hermes OOTB | skill-retriever | |---|---|---| Skill source | Your local `~/.hermes/skills/` only (~100-200) | Community corpus (998) + Hermes skills (200) = 1,198 total | Discovery | Flat name+desc list in system prompt every turn | LLM-navigated taxonomy tree → top-5 relevant injected as hints | Token cost | Every turn burns tokens for all skills, even irrelevant ones | Zero system prompt overhead — hints only in user message, only when found | Categorization | Filesystem directory names | 10,000-category AgentSkillOS capability taxonomy | Scales to | ~200 skills before prompt bloat | 10K+ (tree handles it) | Latency per turn | 0 (passive — always visible) | +1-3 cheap LLM calls for tree traversal (when it has results) | Community corpus | No | Yes — 998 community skills alongside yours | **The difference:** OOTB gives you a flat skill catalog you read every turn. skill-retriever turns it into a **search engine** — 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. ``` git clone https://github.com/ChonSong/skill-retriever.git cd skill-retriever bash scripts/install.sh hermes gateway restart ``` Every skill carries a **source tag** and a **safety scan result**: | Badge | Meaning | |---|---| `🔒hermes` | Installed via Hermes — trusted | `🌐community` | From AgentSkillOS corpus — unreviewed | `⚠️` (suffix) | Flagged by safety scan — review before loading | All 1,200 skills were scanned for dangerous patterns (`rm -rf /` , `curl | sh` to raw IPs, base64 payloads, crypto miners). **Zero flagged** — every match was standard installer documentation inside code blocks. ``` python -m skill_retriever search "set up CI/CD pipeline" python -m skill_retriever build # rebuild capability tree python -m skill_retriever list # list all skills in corpus python -m skill_retriever info # system info + tree stats ``` All settings via environment variables — no config files needed. | Env Variable | Default | Description | |---|---|---| `SKILL_RETRIEVER_DISABLE` | — | Set `1` to disable entirely | `SKILL_RETRIEVER_LLM_MODEL` | `gpt-4o` | LLM model for skill gate | `SKILL_RETRIEVER_LLM_API_KEY` | `OPENAI_API_KEY` | API key | `SKILL_RETRIEVER_LLM_BASE_URL` | `OPENAI_BASE_URL` | Base URL | `SKILL_RETRIEVER_BRANCHING_FACTOR` | `3` | Tree branching (search) | `SKILL_RETRIEVER_MAX_PARALLEL` | `5` | Parallel search branches | `SKILL_RETRIEVER_TEMPERATURE` | `0.3` | LLM temperature | `SKILL_RETRIEVER_PRUNE` | `true` | Enable dedup/ranking step | `SKILL_RETRIEVER_TREE_PATH` | bundled `tree_10000.yaml` | Override capability tree | See [ARCHITECTURE.md](/ChonSong/skill-retriever/blob/master/ARCHITECTURE.md) for a technical deep-dive covering: - Capability tree structure and build process - LLM node selection algorithm - Searcher internals (parallel search, early stop, pruning) - Plugin hook integration - Directory layout - Hermes Agent v0.18+ - Python 3.10+ - ~500MB for capability tree index - ~4GB for full skill corpus (optional, for rebuilding tree) ``` skill-retriever/ ├── plugin/ # Hermes plugin (pre_llm_call hook) ├── src/ │ ├── skill_retriever/ # Core engine │ │ ├── cli.py # CLI (search, build, list, info) │ │ ├── search/ # Searcher (multi-level LLM tree search) │ │ ├── tree/ # Tree builder, schema, prompts, scanner │ │ └── capability_tree/# Pre-built trees (YAML + HTML) │ └── scanner.py # Hermes skills scanner ├── data/ # Skill corpus (gitignored) ├── tests/ # 40 tests ├── scripts/install.sh # One-click Hermes plugin install └── ARCHITECTURE.md ``` MIT. Built on [AgentSkillOS](https://github.com/ynulihao/AgentSkillOS) (MIT).