Hermes Agent 스킬·도구 스키마 주입 최적화 과정
결론
Hermes Agent 시스템 프롬프트의 최대 주입 블록은 도구 스키마(약 43,000자)였고, 두 번째가 스킬 인덱스(4,807자)였다. 둘 다 설정 한 줄이 아니라 "실제 사용량 데이터"를 근거로 감축해야 안전하다.
- 스킬 인덱스: 32개(4,807자, 약 1,296토큰) → 8개(2,643자, 약 661토큰), 약 45% 감소
- 도구 스키마: 20개(43,264자) → 15개(30,016자), 약 13,248자(약 3,300토큰) 감소
아래 수치는 모두 운영자 로컬 환경(Hermes Agent, Linux, cl100k_base 기준) 측정값이며 단일 환경 결과다. 일반화하면 안 된다.
왜 스킬·도구 스키마가 문제인가
시스템 프롬프트는 매 턴 통째로 재전송된다. 그 안에서 스킬 목록(이름 + 설명)과 도구 스키마(JSON)가 큰 비중을 차지한다. 실제로 이 환경에서 시스템 프롬프트 21,213자 중 스킬 인덱스가 약 4,807자, 도구 스키마가 약 43,000자(시스템 프롬프트 외부, tools 배열)를 차지했다.
핵심은 "안 쓰는 것을 왜 매 턴 설명하느냐"이다. 다만 무엇이 안 쓰이는지는 추측하지 말고 사용량 기록으로 확인해야 한다.
스킬 사용량의 권위 데이터
Hermes는 스킬 사용량을 사이드카 JSON에 기록한다.
- 위치:
~/.hermes/skills/.usage.json - 관리 코드:
tools/skill_usage.py - 기록 시점:
skill_view성공 시view_count증가, 실제 사용 시use_count증가 - 필드:
view_count,use_count,pinned,state,origin
주의할 점은 보호 대상 빌트인 스킬이다. tools/skill_usage.py의 PROTECTED_BUILTIN_SKILLS = {"plan"} 하나뿐이며, plan은 슬래시 커맨드와 연결되어 있어 절대 비활성화하면 안 된다.
스킬 자동 발견은 수동 등록이 필요 없다. tools/skills_tool.py가 스킬 디렉토리 mtime과 skills.disabled 집합의 서명으로 스캔하고(캐시 TTL 30초), 신규 스킬은 skills.disabled에 없으면 자동 활성화된다.
1단계: 사용량 기준 스킬 비활성화
~/.hermes/config.yaml의 skills.disabled 목록을 55개에서 79개로 늘렸다. 추가한 24개는 다음과 같이 성격이 나뉜다.
| 구분 | 개수 | 예시 | 판단 근거 |
|---|---|---|---|
| 미사용 내장 스킬 | 15 | arxiv, computer-use, docx, xlsx, openhue, python-debugpy, test-driven-development | use_count=0, 순정 번들 |
| 미사용 커스텀 스킬 | 5 | agent-blog-optimization, touch-command, omh-code-review, remote-server, deepseek-analysis | 사용 이력 없음 |
| 코드·디버깅 계열 | 4 | code-reference, delegate-coding, delegate-debugging, systematic-debugging | 이 작업 공간에서 미사용 |
코드·디버깅 계열을 끌 때는 SOUL.md의 강제 참조를 함께 정리해야 한다. 그대로 두면 존재하지 않는 스킬을 호출해 "Skill not found" 오류가 난다. 실제로 이전 로그에 linux-basics not found, remote-server not found 사례가 있었다.
결과:
| 항목 | 이전 | 이후 |
|---|---|---|
| 주입 스킬 수 | 32개 | 8개 |
| 인덱스 크기 | 4,807자 (약 1,296토큰) | 2,643자 (약 661토큰) |
검증 명령(소스 디렉토리에서):
HERMES_SESSION_PLATFORM=desktop ./venv/bin/python -c \
"from agent.prompt_builder import build_skills_system_prompt; print(build_skills_system_prompt())"
2단계: 도구 스키마 감축
도구 스키마는 개별 도구 단위로 끌 수 없다. 툴셋(toolset) 단위만 가능하다. 이 점이 가장 중요하다.
또 하나: 빌트인 코어 도구는 지연 로드(progressive disclosure) 대상이 아니다. tools/tool_search.py의 tool search는 MCP 및 비핵심 플러그인 도구만 브릿지로 지연시키며, toolsets._HERMES_CORE_TOOLS에 정의된 빌트인 도구는 항상 eager로 노출된다. 이 환경의 tools.tool_search.enabled는 false였다.
따라서 빌트인 도구를 줄이는 유일한 레버는 agent.disabled_toolsets에 툴셋 이름을 추가하는 것이다.
측정 방법
생산 경로를 그대로 재현해서 측정한다. _get_platform_tools(config, 'cli')가 platform_toolsets['cli'](= ['hermes-cli'])를 개별 툴셋 집합으로 해석한 뒤, 마지막에 agent.disabled_toolsets를 감산하기 때문이다.
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(...)))"
측정 시 get_tool_definitions에 disabled_toolsets만 넘기면 web_search가 잘못 제거되는 아티팩트가 생긴다. 반드시 _get_platform_tools를 거친 생산 경로로 확인해야 한다.
비활성화한 툴셋
| 툴셋 | 스키마 크기 | 사용 횟수 | 비고 |
|---|---|---|---|
| browser | (다수) | - | 이전부터 비활성 |
| session_search | 6,424자 | 0 | 단일 최대 스키마. 과거 대화 검색 도구 |
| vision | 924자 | 0 | 첨부 이미지는 MiMo로 위임되므로 무관 |
| video | 752자 | 0 | cli 툴셋 집합에 미포함이라 실효 없음 |
| clarify | 2,404자 | 0 | 진행 전 되묻기 도구 |
| tts | 1,834자 | 0 | 텍스트→음성 |
| todo | 1,372자 | 0 | 세션 작업 목록 |
vision 툴셋을 꺼도 첨부 이미지 처리는 유지된다. config.yaml에 supports_vision: false, auxiliary.vision: {provider: xiaomi, model: mimo-v2.5}가 설정되어 있어 이미지 분석은 별도 auxiliary 경로로 MiMo에 위임되기 때문이다. 사라지는 것은 명시적 vision_analyze 도구 호출 능력뿐이고, 사용 0회였다.
결과
| 항목 | 이전 | 이후 |
|---|---|---|
| 주입 도구 수 | 20개 | 15개 |
| 스키마 크기 | 43,264자 | 30,016자 |
| 제거된 도구 | - | clarify, session_search, text_to_speech, todo, vision_analyze |
최종 주입 도구 15개:
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
캐시 삭제 (필수)
스킬 인덱스는 ~/.hermes/.skills_prompt_snapshot.json에 캐시된다. 설정 변경 후 이 파일을 지우지 않으면 이전 목록이 계속 주입된다.
rm -f ~/.hermes/.skills_prompt_snapshot.json
정리
- 스킬은
.usage.json의 use_count를 근거로 끄고,plan만 예외로 보호한다. - 도구는 개별이 아니라 툴셋 단위로만 끌 수 있다.
- 빌트인 코어 도구는 tool search로 지연되지 않는다.
- 비전·비디오는 MiMo 위임 경로가 따로 있으므로 툴셋을 꺼도 첨부 처리에 영향이 없다.
- 설정 변경 후 스킬 스냅샷 캐시를 반드시 삭제한다.