hermes - 💡(How to fix) Fix perf: two-level skill index in system prompt to reduce fixed token overhead [1 pull requests]

build_skills_system_prompt() in agent/prompt_builder.py currently lists every individual skill under each category inside <available_skills>. With 83+ skills, this consumes about 1.5K–2.5K tokens per session regardless of whether those skills are ever used.

Proposed Solution

Replace the flat listing with a two-level index:

- Level 1 (system prompt): Only category names + descriptions (~300–400 tokens)
- Level 2 (on-demand): Agent calls skills_list(category=...) to drill down, then skill_view(name) to load full content

Already-supported infrastructure:
- skills_list already accepts an optional category parameter
- skill_view already loads full SKILL.md on demand
- Categories already have DESCRIPTION.md support

Code Change in agent/prompt_builder.py (~lines 830–846)

Current (generates 1.5K+ tokens):
python
index_lines = []
for category in sorted(skills_by_category.keys()):
    cat_desc = category_descriptions.get(category, "")
    if cat_desc:
        index_lines.append(f"  {category}: {cat_desc}")
    else:
        index_lines.append(f"  {category}:")
    seen = set()
    for name, desc in sorted(skills_by_category[category], key=lambda x: x[0]):
        if name in seen:
            continue
        seen.add(name)
        if desc:
            index_lines.append(f"    - {name}: {desc}")
        else:
            index_lines.append(f"    - {name}")


Proposed (~300 tokens):
python
index_lines = []
for category in sorted(skills_by_category.keys()):
    cat_desc = category_descriptions.get(category, "")
    count = len(skills_by_category[category])
    if cat_desc:
        index_lines.append(f"  {category} ({count} skills): {cat_desc}")
    else:
        index_lines.append(f"  {category} ({count} skills)")


Also update the instruction text (lines 848–874) to tell the agent to use skills_list(category=...) to drill down.

Benefits

- ~80% reduction in fixed token overhead for skill index
- No loss of discoverability — on-demand query
- Backward compatible — tools unchanged

Affected Files

- agent/prompt_builder.py
- tests/agent/test_prompt_builder.py (update assertions)