How I optimized skill and tool-schema injection in the Hermes Agent

Conclusion

The largest injected block in the Hermes Agent system prompt was the tool schema (about 43,000 chars), and the second was the skills index (4,807 chars). Both must be reduced based on "actual usage data," not a one-line setting, to be safe.

• Skills index: 32 (4,807 chars, about 1,296 tokens) to 8 (2,643 chars, about 661 tokens), about 45% reduction
• Tool schema: 20 (43,264 chars) to 15 (30,016 chars), about 13,248 chars (about 3,300 tokens) reduction

All figures below are measured in the operator's local environment (Hermes Agent, Linux, cl100k_base) and are single-environment results. Do not generalize them.

Why skills and the tool schema are a problem

The system prompt is resent in full every turn. Within it, the skills list (name + description) and the tool schema (JSON) take up a large share. In fact, in this environment, out of a 21,213-char system prompt, the skills index was about 4,807 chars and the tool schema about 43,000 chars (outside the system prompt, in the tools array).

The point is "why describe what you do not use every turn?" But what is unused must not be guessed; it must be checked against usage records.

Authoritative data on skill usage

Hermes records skill usage in a sidecar JSON.

• Location: ~/.hermes/skills/.usage.json
• Managing code: tools/skill_usage.py
• Recording: on a successful skill_view, view_count increments; on actual use, use_count increments
• Fields: view_count, use_count, pinned, state, origin

Watch out for protected built-in skills. In tools/skill_usage.py, PROTECTED_BUILTIN_SKILLS = {"plan"} is the only one, and plan is wired to a slash command, so it must never be disabled.

Skill auto-discovery needs no manual registration. tools/skills_tool.py scans by the skills directory mtime and the signature of the skills.disabled set (cache TTL 30 seconds), and a new skill is auto-enabled if it is not in skills.disabled.

Step 1: Disable skills based on usage

I grew the skills.disabled list in ~/.hermes/config.yaml from 55 to 79. The 24 added items fall into these categories.

When turning off code/debugging skills, you must also clean up their forced references in SOUL.md. Leaving them causes calls to nonexistent skills and a "Skill not found" error. In fact, earlier logs had cases of linux-basics not found and remote-server not found.

Result:

Verification command (from the source directory):

HERMES_SESSION_PLATFORM=desktop ./venv/bin/python -c \
"from agent.prompt_builder import build_skills_system_prompt; print(build_skills_system_prompt())"

Step 2: Shrink the tool schema

The tool schema cannot be turned off per individual tool. Only at the toolset level. This is the most important point.

One more: built-in core tools are not subject to progressive disclosure. The tool search in tools/tool_search.py lazily loads only MCP and non-core plugin tools through a bridge, while built-in tools defined in toolsets._HERMES_CORE_TOOLS are always exposed eagerly. In this environment, tools.tool_search.enabled was false.

So the only lever to reduce built-in tools is to add toolset names to agent.disabled_toolsets.

How to measure

Reproduce the production path exactly. _get_platform_tools(config, 'cli') resolves platform_toolsets['cli'] (= ['hermes-cli']) into an individual toolset set, then subtracts agent.disabled_toolsets at the end.

HERMES_SESSION_PLATFORM=desktop ./venv/bin/python -c \
"from hermes_cli.tools_config import _get_platform_tools; \
 from tools.model_tools import get_tool_definitions; \
 import yaml; cfg=yaml.safe_load(open('config.yaml')); \
 print(len(get_tool_definitions(...)))"

When measuring, passing only disabled_toolsets to get_tool_definitions produces an artifact where web_search is wrongly removed. Always verify through the production path via _get_platform_tools.

Toolsets disabled

Turning off the vision toolset still keeps attached image handling. config.yaml has supports_vision: false and auxiliary.vision: {provider: xiaomi, model: mimo-v2.5}, so image analysis is delegated to MiMo through a separate auxiliary path. What disappears is only the explicit vision_analyze tool-call ability, which had 0 uses.

Result

The final 15 injected tools:

delegate_task, execute_code, memory, patch, process, read_file,
search_files, skill_manage, skill_view, skills_list, terminal,
web_extract, web_search, write_file, youtube_search

Cache deletion (required)

The skills index is cached in ~/.hermes/.skills_prompt_snapshot.json. If you do not delete this file after changing settings, the old list keeps being injected.

rm -f ~/.hermes/.skills_prompt_snapshot.json

Summary

• Turn off skills based on the use_count in .usage.json, protecting only plan as an exception.
• Tools can only be turned off at the toolset level, not individually.
• Built-in core tools are not lazily loaded by tool search.
• Vision/video have a separate MiMo delegation path, so turning off the toolset does not affect attachment handling.
• Always delete the skills snapshot cache after changing settings.