[My Agent]9. Hermes 에이전트 MCP · 스킬 설정

목차(클릭하세요)

Hermes Agent도 MCP와 skill 적용하기

[참고사이트]

Quickstart | Hermes Agent

Your first conversation with Hermes Agent — from install to chatting in under 5 minutes

https://hermes-agent.nousresearch.com/docs/getting-started/quickstart#mcp-servers

hermes-agent

nousresearch

1. Hermes 스킬 시스템

1-1. 스킬이란?

"이런 작업을 할 때는 이렇게 해라"는 절차서. 에이전트가 복잡한 작업을 성공적으로 완료하면 그 과정을 스킬로 저장하고, 다음에 비슷한 작업이 오면 더 빠르고 정확하게 처리함.

•

~/.hermes/skills/ 디렉터리에 저장되는 마크다운 지식 문서

•

agentskills.io 오픈 표준을 따름

•

파워셀에서는 다음 명령어로 확인가능

hermes skills list
Bash
복사

•

hermes 실행중에는 설치된 모든 스킬은 슬래시 명령어로 자동 등록됨 

◦

(/스킬명으로 실행)

1-2. 스킬은 어디에 설치되나?

스킬은 모두 ~/.hermes/skills/ 아래에 평평하게 설치됨

•

스킬이 설치되는 방식은 크게 3가지

•

번들: Hermes 설치본과 함께 따라오는 스킬

◦

 hermes update 시 자동 동기화되고, 사용자가 직접 수정한 스킬은 보호됨

◦

 자세한 절차는 「업데이트」 절 참고.

•

Skills Hub로 설치: hermes skills install <name>으로 Hub에서 내려받아 사용자가 직접 설치하는 방법

◦

다운로드 직후 보안 스캔(tools/skills_guard.py)을 거치며, 통과하면 ~/.hermes/skills/<name>/ 폴더형태로 저장됨

•

에이전트 자동 생성: 사용자가 같은 작업을 반복하면 에이전트가 백그라운드로 스스로 SKILL.md를 만들어 같은 위치에 저장함

각 스킬 디렉터리에는 최소한 SKILL.md 파일이 들어 있고, 필요에 따라 scripts/·templates/·references/·assets/ 같은 하위 폴더가 함께 존재할 수도 있음

1-3. 자동과 수동

[자동]3단계 로딩 (Progressive Disclosure)

•

기본적으로 토큰 절약을 위해 단계적으로 로딩됨

•

스킬을 한꺼번에 다 로딩하면 매 대화마다 수십만 토큰이 소비될 수 있기에, 3단계 로딩 구조를 가짐

skills_list와 skill_view는 Hermes Agent가 내부적으로 자동으로 호출하는 에이전트 내장 도구

단계	내용	토큰 소비	실제 동작방식
Level 0	시스템 프롬프트에 스킬 이름·설명만 포함된 목록을 보여줌	skill당 약 50토큰	항상 로딩
Level 1	skills_list 도구 호출 → 트리거 조건·사용 예시 반환	skill킬당 수백 토큰 (트리거·예시만)	필요 시만
Level 2	skill_view 도구 호출 → SKILL.md 전체 내용 로딩	skill 크기에 따라 수천~수만 토큰	실제 사용 시

 스킬 100개여도 Level 0에서는 약 5,000토큰이면 충분함

[수동] 사용자가 직접 개입

•

사용자가 특정 스킬명을 입력해 강제 실행하게 할 수도 있음

[예시] 스킬명을 직접 입력

Bash
복사

/powerpoint    # powerpoint 스킬 강제 로딩
/llm-wiki      # llm-wiki 스킬 강제 로딩
Bash
복사

1-4. SKILL.md 작성 규칙과 예시

•

예시파일은 번들skill로 확인가능

•

이것만은 꼭!

◦

파일명은 무조건 SKILL.md — 대소문자 포함 정확히 일치해야 함. SKILL.md가 아니면 인식 안 됨

◦

YAML frontmatter 문법 엄격 — 들여쓰기 스페이스 2칸, 콜론 뒤 공백 필수. 틀리면 스킬 로딩 실패

◦

description은 짧고 명확하게 — Level 0에서 에이전트가 이 설명만 보고 스킬 선택 여부를 판단하기 때문

•

알아두면 좋은 스킬 작성 규칙

◦

영어 작성 권장 — description, trigger, examples 필드는 영어로 써야 에이전트가 더 정확하게 트리거를 인식함. 본문 내용은 한글 가능

◦

examples 필드가 트리거 정확도를 높임 — 사용자가 실제로 입력할 법한 문장을 넣을수록 Level 1 매칭이 정확해짐

◦

trigger 필드와 ## When to Use 섹션 둘 다 쓰면 더 안정적 — YAML의 trigger는 Level 1용, 본문의 ## When to Use는 Level 2용으로 이중 보험

◦

pinned: true 설정 가능 — 백그라운드 큐레이터가 자동으로 스킬을 수정하지 못하게 막음. 공들여 만든 커스텀 스킬엔 필수

---
name: 스킬명
version: 1.0.0
author: 작성자
description: Level 0 시스템 프롬프트에 표시되는 설명
trigger: Level 1에서 반환되는 트리거 조건
examples:
  - "트리거 예시 문장 1"
  - "트리거 예시 문장 2"
trust: builtin  # builtin | official | trusted | community
platforms: [windows]
---

## 스킬 내용
...
YAML
복사

스킬 디렉터리 구조

skills/스킬명/
├── SKILL.md          # 필수
├── references/       # 참조 문서
├── templates/        # 템플릿 파일
├── scripts/          # 스크립트
└── assets/           # 이미지 등
Plain Text
복사

1-5. 스킬 관리 명령어

•

모두 파워셀에서 확인가능

hermes skills list                    # 설치된 스킬 목록
hermes skills browse                  # 사용 가능한 스킬 탐색
hermes skills search <검색어>          # 스킬 검색
hermes skills install <이름>           # 이름으로 설치
hermes skills install <URL>           # URL에서 직접 설치
hermes skills inspect <이름>           # 설치 전 내용 미리 보기
hermes skills check                   # 업데이트 확인
hermes skills update                  # 스킬 업데이트
hermes skills audit                   # 보안 감사
PowerShell
복사

•

만약 슬랙(slack)에서 변경스킬을 반영하고 싶다면?

◦

 @양비서 /reload-skills → 재시작 없이 즉시 반영

1-6. 자동 스킬 생성

hermes 에이전트가 스스로 스킬을 생성하는 자기 개선 메커니즘

스킬 관리 동작

대화 중 도구 호출이 충분히 누적되면 리뷰 플래그 활성화

사용자에게 응답 완료 후 백그라운드 스레드에서 리뷰 에이전트 실행

재사용 가능한 워크플로 발견 시 skill_manage 도구로 스킬 자동 생성

메인 대화에 전혀 간섭하지 않음

동작	설명
create	새 스킬 생성
patch	특정 섹션만 수정
edit	전체 재작성
delete	스킬 삭제

•

헤르메스 에이전트가 스스로 자동생성한 스킬 확인방법

◦

파워셀에서 다음 명령어 실행 후 확인가능: Source 컬럼이 builtin이면 기본 스킬, local이면 자동 생성되었거나사용자가 생성한 스킬

◦

SKILL.md 열어서 author 필드 확인

▪

자동 생성 스킬: Hermes가 만들 때 author: Hermes Agent 자동 기입

▪

수동 추가 스킬: 사람이 만들면 author 필드 자체가 없거나 직접 작성한 이름

▪

그래서 커스텀 스킬 만들 때 author 필드를 꼭 넣는 것을 권장

hermes skills list
Bash
복사

 로컬 LLM(Gemma4 등 소형 모델)에서는 자동 생성 판단 품질이 떨어질 수 있음. 수동 생성 권장.

1-7. Skills Hub과 핀기능

•

커뮤니티 스킬 마켓플레이스. 7개 소스 어댑터 지원

•

아래주소에서 확인가능

hermes-agent.nousresearch.com

https://hermes-agent.nousresearch.com/docs/ko/skills

•

핀(Pin) 기능: 스킬을 pinned 상태로 표시하면 백그라운드 큐레이터가 자동으로 수정 불가

◦

스킬을 pinned 상태로 표시하면, 자동 백그라운드 큐레이터(7-6절)가 함부로 손대지 못하고 skill_manage도 쓰기를 거부

◦

사람이 손으로 잘 다듬어 둔 스킬을 보호할 때 사용

•

Pin 상태는 ~/.hermes/skills/.usage.json에 저장 → 세션 재시작해도 유지

hermes curator pin 스킬명      # 핀 설정
hermes curator unpin 스킬명    # 핀 해제
PowerShell
복사

2. Hermes MCP 연동

2-1. MCP란?

hermes에서의 MCP는 두 가지 전송 방식을 지원

Stdio (로컬 프로세스): command, args, env 필드를 사용

•

 로컬에서 서브프로세스로 실행되며 stdin/stdout으로 통신합니다. 지연 시간이 짧아 대부분의 경우 권장됨

HTTP (원격 서버): url, headers 필드를 사용

•

 네트워크를 통해 원격 서버에 연결합니다. 클라우드 기반 MCP 서비스에 적합함

Hermes Agent 3계층 도구 구조:

┌─────────────────────────────────┐
│ 1계층: 빌트인 도구 (40+개)       │ ← 터미널, 파일, 웹 등 항상 사용 가능
├─────────────────────────────────┤
│ 2계층: 스킬 (SKILL.md)           │ ← 절차적 지식, 3단계 지연 로딩
├─────────────────────────────────┤
│ 3계층: MCP (외부 서비스 연결)     │ ← CLI 없는 SaaS, DB, 인증 API
└─────────────────────────────────┘
Plain Text
복사

MCP가 적합한 경우

•

CLI가 없는 SaaS 서비스 (Jira, Notion, Linear 등)

•

인증이 필요한 DB 연결 (PostgreSQL, MongoDB 등)

•

여러 에이전트가 같은 도구를 표준화된 방식으로 공유

빌트인 도구가 더 나은 경우:

•

git, docker, curl 등 셸 명령어 → MCP로 감싸면 비효율

•

CLI 명령어 한 줄로 되는 작업

 토큰 주의: CLI는 약 1,400토큰 vs MCP는 약 44,000토큰 소비 가능

2-2. config.yaml 기본 설정법

경로: C:\Users\ysj\AppData\Local\hermes\config.yaml

Stdio 방식 (로컬, 권장):

HTTP 방식 (원격):

mcp_servers:
  서버이름:
    type: stdio
    command: "명령어"     # 실행할 바이너리 (예: "npx", "uvx")
    args: ["인수"]        # command에 전달할 인수 배열
    env:                  # 자식 프로세스에 전달할 환경변수
      KEY: "value"
    timeout: 60           # 도구 호출 타임아웃 (초, 기본 60)
    connect_timeout: 120  # 초기 연결 타임아웃 (초, 기본 120)
    enabled: true         # 활성화 여부
YAML
복사

mcp_servers:
  서버이름:
    type: http
    url: "https://mcp.example.com/sse"
    headers:
      Authorization: "Bearer ${MCP_TOKEN}"
    timeout: 60           # 도구 호출 타임아웃 (초, 기본 60)
    connect_timeout: 120  # 초기 연결 타임아웃 (초, 기본 120)
    enabled: true         # 활성화 여부
YAML
복사

도구 필터링 (토큰 절약 필수)

mcp_servers:
  github:
    type: stdio
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    tools:
      include:            # 이 도구만 사용
        - create_issue
        - list_repos
      # 또는
      exclude:            # 이 도구 제외
        - delete_repo
    resources: false      # list_resources, read_resource 비활성화
YAML
복사

•

include가 설정되어 있으면 exclude보다 우선 즉, 두 필드를 동시에 설정하면 include만 적용됨

•

설정 변경 후 재시작 없이 반영: @양비서 /reload-mcp 

•

여러 MCP가 조합된 형태

mcp_servers:
  github:
    type: stdio
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"

  postgres:
    type: stdio
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      DATABASE_URL: "${DATABASE_URL}"

  filesystem:
    type: stdio
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allow"]
Bash
복사

2-3. Kordoc MCP 연결 (HWP·HWPX·PDF → Markdown)

Kordoc 소개

•

한국 공문서(HWP/HWPX/PDF)를 마크다운으로 변환하는 MCP 서버

•

한국 공무원이 7년간 실무에서 개발, 정부 프로젝트 5개에서 검증

•

Node.js 기반, npx로 별도 설치 없이 바로 실행

•

API 키 불필요

제공 툴

툴	기능
parse_document	HWP·HWPX·PDF → Markdown 변환
detect_format	파일 형식 자동 감지 (magic bytes 기반)

config.yaml 설정:

mcp_servers:
  kordoc:
    type: stdio
    command: npx
    args: ["-y", "kordoc", "mcp"]
    enabled: true
YAML
복사

적용 후 게이트웨이 재시작

hermes gateway restart
PowerShell
복사

파워셀에서 다음 명령어로 MCP 상태확인

또는 슬랙에서 도구 이름 확인

Bash
복사

@양비서 /tools

또는

@양비서 /reload-mcp
Plain Text
복사

2-4. Kordoc MCP 실전테스트

•

hwpx를 MCP로 불러들여 한글작업이 가능해짐

3. Hermes 커스텀 스킬 연결

3-1. 스킬 작성 규칙 (Claude vs Hermes)

항목	Claude	Hermes
메타데이터 형식	XML 태그	YAML frontmatter
파일명	SKILL.md	SKILL.md
트리거	description 태그	trigger 필드 + ## When to Use 섹션
위치	/mnt/skills/	AppData\Local\hermes\skills\
관리 주체	Anthropic 시스템	사용자 직접

필수 YAML frontmatter

---
name: 스킬명
version: 1.0.0
description: "스킬 설명 (Level 0 시스템 프롬프트에 표시)"
trigger: "트리거 조건 (Level 1에서 반환)"
examples:
  - "트리거 예시 1"
  - "트리거 예시 2"
platforms: [windows]
metadata:
  hermes:
    tags: [태그1, 태그2]
    category: 카테고리명
---
YAML
복사

3-2. 클로드에서 만든 PPTX 스킬을 Hermes로 이동

변환 방법

클로드의 스킬에서 <>선택후 해당 내용을 복사

맨 위에 YAML frontmatter 추가

---
name: phagos-pptx
version: 1.0.0
author: yangphago
description: "양파고(Yangphago)의 python-pptx 기반 PPTX 자동화 스킬. '우리의 pptx스킬', '양파고의 pptx스킬', 'pptx 자동화 스킬', 'pptx 만들어줘', '프레젠테이션 코드로 생성', 'python-pptx 애니메이션', 'PPTX 그룹화', 'PPTX 클릭 애니메이션', 'bldLst', 'bldP', 'OOXML 애니메이션' 등을 언급할 때 반드시 사용."
trigger: "PPT, 파워포인트, 프레젠테이션, PPTX 생성 요청 시"
examples:
  - "PPT 만들어줘"
  - "프레젠테이션 생성해줘"
  - "슬라이드 만들어줘"
  - "pptx 자동화 스킬 써줘"
  - "python-pptx로 만들어줘"
platforms: [windows]
metadata:
  hermes:
    tags: [pptx, powerpoint, presentation, python-pptx, ooxml, animation]
    category: productivity
---
YAML
복사

3.저장 경로에 해당 스킬파일 저장

주의점: skill.md 소문자 안되고, 반드시 SKILL.md로 지정

C:\Users\ysj\AppData\Local\hermes\skills\phagos-pptx\SKILL.md
Plain Text
복사

마지막으로 파웨셀에서 적용 확인

hermes skills list
# → phagos-pptx 목록에 표시되면 성공
PowerShell
복사

3-3. phagos PPTX 스킬 실전 활용기

•

먼저 스킬사용가능한지 확인 후

•

작동과정을 살펴보면

◦

phagos-pptx 스킬이 python-pptx, lxml 등 필요한 패키지를 처음 실행 시 자동으로 설치함

◦

이는 Hermes의 lazy install 기능때문: config.yaml에 allow_lazy_installs: true 설정때문에 사전 설치 없이 스킬 첫 실행 때 자동으로 처리

•

실행 중간중간 에이전트에서 접근 권한을 부여해야 하는 경우가 있음(첫 실행단계에서 주로 발생)

•

결과물 확인

•

그냥 로컬에서 안티그래비티나 클로드 코워크 돌리는게 훨씬 결과물이 좋음(아마도 LLM모델차이 일듯)