# NousResearch/hermes-agent · Skill index size reduction and retrieval strategies

## Open now

- 9 issues, 4 PRs open on GitHub.
- #2045: \[Feature\]: Lazy skill loading: remove skill listing from system prompt, use on-demand tool instead
- #17649: Feature: Semantic Skill Retrieval with SQLite FTS5 — Replace 4500-token broadcast with on-demand search
- #22620: Feature Request: Skill list bloat causes massive context window inflation — need vector-based skill routing or lazy loading
- #26786: perf: two-level skill index in system prompt to reduce fixed token overhead
- #26806: \[Feature\] Suppress <available_skills> system_prompt injection for scripted/oneshot use
- #34823: Feature Request: Semantic / Per-Message Skill Retrieval
- #37227: \[Feature\]: Category-Aware Smart Skill Indexing with Automatic Scenario Matching + Lazy Loading (fusing #3879's trigger keywords)
- #49967: \[Feature\]: Skill Graph — optional dynamic skill discovery mode to reduce system prompt size
- #63153: \[Feature\]: Add Dynamic Skill Retrieval System (Skill-RAG) for Hermes Agent
- PR #12379: feat: Lazy skill loading — skills.loading config option
- PR #13980: Add skills.loading: lazy config option (#2045)
- PR #50057: feat(skill-graph): add bundled plugin, skill_graph_mode config, and companion skills
- PR #64528: Feat/hybrid skill retrieval

These issues and PRs explore various approaches to reducing token overhead from skill listings in system prompts, including lazy loading, category-level indexing, semantic/FTS5 retrieval, skill graphs, and options to suppress skill injection entirely.

## TL;DR

- 23 member(s): 9 open issue(s), 1 closed issue(s), 4 open PR(s), 0 merged PR(s), 9 PR(s) closed without merging.
- No fix has been merged to main; one or more PRs were attempted (see below).
- **Recommended:** review the prior/competing PR(s) below. A fix was attempted but not merged; your case may extend or revive that work.

## Maintainer resolution verdict

- Internal-tracker verdict over this cluster's issue members: `unresolved`. This is distinct from the fix status above. Weigh it yourself.

## How this cluster was grouped

- Link evidence (`STRUCTURAL_PARTIAL`): some members are connected by structural evidence (shared changed files, or a closing/superseded reference); the rest are joined by an automated relevance judgement over their text.
- Members outside that structural core may belong to a different underlying problem.
- Pairwise link density `0.07`: the share of member pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. `1.00` means every pair is linked.

## Open related issues

- #2045: \[Feature\]: Lazy skill loading: remove skill listing from system prompt, use on-demand tool instead
- #17649: Feature: Semantic Skill Retrieval with SQLite FTS5 — Replace 4500-token broadcast with on-demand search
- #22620: Feature Request: Skill list bloat causes massive context window inflation — need vector-based skill routing or lazy loading
- #26786: perf: two-level skill index in system prompt to reduce fixed token overhead
- #26806: \[Feature\] Suppress <available_skills> system_prompt injection for scripted/oneshot use
- #34823: Feature Request: Semantic / Per-Message Skill Retrieval
- #37227: \[Feature\]: Category-Aware Smart Skill Indexing with Automatic Scenario Matching + Lazy Loading (fusing #3879's trigger keywords)
- #49967: \[Feature\]: Skill Graph — optional dynamic skill discovery mode to reduce system prompt size
- #63153: \[Feature\]: Add Dynamic Skill Retrieval System (Skill-RAG) for Hermes Agent

## Closed / duplicate issues

- #28902: OAuth Anthropic Max: <available_skills> system-prompt injection on every turn triggers "out of extra usage" 400 when skills/session_search toolsets are active

## Prior & competing PRs

- **#28929: fix(anthropic): default skills catalog to names-only to reduce prompt token usage**. closed without merge · fix tier `suggested`
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `f64e4f4f57`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#2089: feat(skills): add lazy skill loading to reduce system prompt tokens**. closed without merge
  - maintainer direction: category `uncategorized`; implication `needs_llm`
- **#2420: feat: docker_extra_args, message timestamps, and lazy skill loading**. closed without merge
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `ebf2ea584`, `#23599`
- **#12379: feat: Lazy skill loading — skills.loading config option**. open
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#13980`, `#2045`
  - files: `agent/prompt_builder.py`, `hermes_cli/config.py`, `run_agent.py`
- **#13980: Add skills.loading: lazy config option (#2045)**. open
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#12379`
  - files: `agent/prompt_builder.py`, `hermes_cli/config.py`, `website/docs/user-guide/features/skills.md`
- **#18316: feat: semantic skill retrieval with FTS5 + hybrid selector + skill enforcement**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`
- **#26815: feat(agent): add --no-skills-index to suppress <available_skills> system-prompt block**. closed without merge
  - maintainer direction: category `stale_abandoned`; implication `active`
- **#26842: perf(skills): list categories in system prompt**. closed without merge
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `ee1a744ac`, `#72813`
- **#35345: feat(skills): add category-level skill index to reduce per-turn token overhead by 90%**. closed without merge
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `ee1a744ac`, `#26842`
- **#50057: feat(skill-graph): add bundled plugin, skill_graph_mode config, and companion skills**. open
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `#82173`, `#49967`, `#26806`, `#82173`
  - files: `agent/agent_init.py`, `agent/agent_init_session.py`, `agent/prompt_builder.py`, `agent/system_prompt.py`, `cli-config.yaml.example`, `docs/skill-graph/gateway-skills.md`, `docs/skill-graph/workflow-organization.md`, `hermes_cli/config_defaults.py`, `hermes_cli/config_defaults_auxiliary.py`, `plugins/skill-graph/__init__.py`, `plugins/skill-graph/plugin.yaml`, `skills/hermes/skill-graph/SKILL.md`, `tests/hermes_cli/test_config_defaults_auxiliary.py`, `tests/hermes_cli/test_skill_graph_gating.py`, `tests/plugins/test_skill_graph_early_health.py`
- **#64528: Feat/hybrid skill retrieval**. open
  - maintainer direction: category `partial_fix`; implication `needs_llm`; refs `0f7403b2a9e4`, `#34823`, `#64528`, `#64528`, `#34823`, `#17649`, `#22620`, `#18316`, `#64528`, `#374151`, `#34823`, `#64528`
  - files: `agent/conversation_loop.py`, `agent/prompt_builder.py`, `agent/skill_retrieval.py`, `agent/turn_context.py`, `tests/agent/test_prompt_builder.py`, `tests/agent/test_skill_retrieval.py`, `tools/skill_manager_tool.py`, `tools/skills_hub.py`, `tools/skills_sync.py`
- **#83314: feat(skills): add configurable skill index injection**. closed without merge
  - maintainer direction: category `wontfix_bydesign`; implication `wontfix`
- **#130118: feat: skill-rag plugin — dynamic skill retrieval via embeddings (implementation for #63153)**. closed without merge
  - maintainer direction: category `wontfix_bydesign`; implication `wontfix`

## Fix status

- No merged fix on record.
- Subsystem: `agent`