Hermes 에이전트 스킬 작성 — SKILL.md 구조 및 모범 사례
빠르게 로드되고 안정적으로 동작하는 Author Hermes 기능
Hermes Agent는 **스킬(skill)**을 반복 가능한 워크플로우를 가르치는 기본 방식으로 취급합니다. 공식 문서에서는 이를 오픈 agentskills.io 형식에 맞춘 온디맨드(on-demand) 지식 문서로 설명하며, **점진적 공개(progressive disclosure)**를 통해 로드되므로 모델은 먼저 작은 인덱스를 보다가 작업이 실제로 필요할 때만 전체 지침을 가져오게 됩니다.
작성의 핵심은 교묘한 어휘 선택보다는 **포장(packaging)**에 있습니다. 런타임에 절차를 언제 로드할지, 어떤 단계 순서가 ‘완료’로 간주되는지, 성공과 침묵 실패(silent failure)를 어떻게 구분할지를 지시하는 것입니다. 이 기사에서는 /slash 명령어에 스킬이 표시되는지, 허브(hub) 설치를 견디는지, 아니면 CI에서 조용히 사라지는지를 결정하는 SKILL.md 구조, 지원 폴더, 가시성 규칙, 그리고 비공개 설정과 공개 설정 간의 분리와 같은 세부 사항에 집중합니다.
Hermes는 AI Systems: Self-Hosted Assistants, RAG, and Local Infrastructure 클러스터 내에 위치하며, 여기서 에이전트들은 단일 채팅 인터페이스가 아닌 추론, 검색, 메모리, 도구를 기반으로 구축된 시스템으로 간주됩니다. 설치 경로, 제공자(provider) 연결, 게이트웨이 동작, ~/.hermes 레이아웃은 모두 Hermes AI Assistant - Install, Setup, Workflow, and Troubleshooting 가이드에 명시되어 있습니다. 일상적인 셸 사용성—hermes skills, 프로필, 게이트웨이, 메모리—are는 **Hermes Agent CLI cheat sheet — commands, flags, and slash shortcuts**에서 더 쉽게 확인할 수 있습니다. 실제 배포 환경에서는 스킬이 프로필(profiles)(별도의 설정, 시크릿, 메모리, 스킬 트리)로부터 격리를 상속받습니다. **Hermes AI Assistant Skills for Real Production Setups**에서는 개별 마크다운 파일이 아닌 이러한 프로필을 소유의 단위로 취급해야 한다고 주장하므로, 스킬 명명 및 단일 프로필과 공유 external_dirs에 무엇을 배치할지 결정할 때 이를 염두에 두십시오.
스킬(skill)인가, 도구(tool)인가?
공식 지침은 직설적입니다. 기능이 주로 문구형 지침과 Hermes가 이미 노출하는 셸 명령어 및 도구(CLI 감싸기, git 구동, curl 호출, 또는 구조화된 가져오기를 위한 web_extract 사용 등)에 기반한다면 스킬을 사용하십시오. API 키 및 인증 흐름, 결정론적인 바이너리 처리, 스트리밍, 또는 매번 동일하게 실행되어야 하는 Python에 대한 긴밀한 통합이 필요하면 도구를 사용하십시오.
이 경계는 실제로 중요합니다. 스킬은 에이전트 코드를 변경하지 않고 배포되지만, 도구는 검토 및 릴리스 오버헤드를 수반하기 때문입니다. 대부분의 팀은 스킬로 시작하고, 실패 모드(인증 갱신 루프, 바이너리 파싱, 엄격한 멱등성)가 명확해지면 취약한 핵심 부분만 도구로 승격시키는 방식을 선호합니다.
절차(procedure)와 큐레이션된 메모리(curated memory)
스킬은 워크플로우를 어떻게 실행할지에 대한 답변을 제공하며, Hermes의 유계(bounded) 코어 메모리는 사용자 및 프로젝트에 대해 이미 합의된 것에 대한 답변을 제공합니다. 작업이 설명과 일치할 때 스킬이 로드되며, MEMORY.md와 USER.md는 작고 큐레이션된 사실 계층으로 프롬프트에 남아 있습니다. 두 메커니즘은 경쟁하지 않고 쌓이며, 스냅샷, 한계, 외부 제공자에 대한 전체 그림은 **Hermes Agent Memory System: How Persistent AI Memory Actually Works**에 설명되어 있습니다.
스킬 디렉토리 구조
디스크에서 각 스킬은 ~/.hermes/skills/ 아래의 폴더이며, 종종 devops/ 또는 research/와 같은 카테고리에 중첩됩니다. Hermes는 **리프(leaf)에 SKILL.md**가 있어야 한다고 기대하며, 다른 모든 것은 지침이otherwise 확장될 때 추가하는 선택적 구조입니다. 일반적인 패턴은 긴 테이블이나 벤더 문서를 위한 references/, 출력 골격을 위한 templates/, 결정론적인 헬퍼를 위한 scripts/, 에이전트가 다시 가져오지 않아야 하는 정적 파일을 위한 assets/입니다.
이 레이아웃은 실제 점진적 공개가 작동하는 방식을 반영합니다: 에이전트는 깊은 부록이 정말 필요할 때까지 메인 파일에 머물 수 있습니다. “해피 패드(happy path)” 문구를 SKILL.md에 유지하고 드물게 사용되는 세부 사항을 references/로 밀어내는 것은 토큰 예산을 보호하는 가장 저렴한 방법 중 하나입니다.
Hermes는 config.yaml의 skills.external_dirs를 통해 외부 스킬 디렉토리를 병합할 수도 있습니다. 이러한 경로는 발견(discovery)을 위해 스캔되지만, 에이전트는 여전히 skill_manage를 통해 주 ~/.hermes/skills/ 트리에 기록합니다. 로컬 이름이 외부 이름을 가립니다(shadow), 따라서 홈 디렉토리에서 공유 스킬을 “수정"하면 같은 외부 저장소를 끌어오는 팀원들은 로컬 복사본을 제거하거나 이름을 바꾸기 전까지 수정 사항을 볼 수 없으며, 이는 “내 컴퓨터에서는 작동한다"는 혼란의 일반적인 원인입니다.
검토를 견디는 SKILL.md 프론트매터
SKILL.md의 본문은 마크다운이며, 개시 블록은 --- 구분 기호 사이의 유효한 YAML이어야 합니다. 실제 스킬은 긴 펜스드(fenced) 예제를 축적하므로, **Markdown Code Blocks: Complete Guide with Syntax, Languages & Examples**에서 제시된 작은 습관들—일관된 언어 태그, 읽기 쉬운 발췌문, 긴밀한 펜스—을 적용하면 큰 파일을 인간이 유지 관리하기 쉽고 모델이 스캔하기도 약간 더 쉬워집니다.
필수 필드는 name과 description입니다. name은 슬래시 루트 및 인덱스 키가 되며, 하이픈을 포함한 소문자로 유지되어야 하며 문서화된 길이 제한을 준수해야 합니다. description은 **레벨 제로(level zero)**에서 많은 세션이 비용을 지불하는 유일한 문구이므로, 블로그 게시물의 첫 단락이 아니라 검색 결과 또는 라우터 문자열처럼 읽혀야 합니다(“백업이陈旧해 보일 때, 최신 아카이브와 체크섬을 확인하십시오”).
version, author, license와 같은 선택적 최상위 키는 허브 패키징 및 감사에 도움이 됩니다. platforms 목록(macos, linux, windows)은 겉보기보다 더 날카롭습니다. 설정되면 Hermes는 일치하지 않는 호스트에서 스킬을 완전히 제외하므로, “맥에서는 작동하는” 스킬이 오류 메시지 없이 Linux CI에서 사라질 수 있으며, 스킬 목록이 짧아진 것 이상의 메시지가 없습니다.
Hermes 전용 노브(knobs)는 metadata.hermes 아래에 있습니다: tags, related_skills, 그리고 다음 섹션의 조건부 가시성 필드. **required_environment_variables**는 .env에 저장되어 샌드박스로 전달되어야 하는 시크릿을 선언합니다. **required_credential_files**는 Docker 또는 Modal로 마운트해야 하는 OAuth 토큰 파일 및 기타 디스크상의 자격 증명을 다룹니다. **metadata.hermes.config**는 config.yaml의 skills.config에 저장되는 비공개 설정을 선언합니다.
공식 문서가 **크기 규율(size discipline)**을 강조하는 이유는 있습니다. description을 예산만큼 줄이고, 절차를 최전면에 배치하며, 역사적 주석이나 거대한 옵션 매트릭스를 references/로 밀어내어 부분적인 skill_view로도 에이전트가 실행 가능한 정보를 얻을 수 있도록 하십시오.
아래는 ~/.hermes/skills/devops/backup-check/SKILL.md(또는任何 카테고리 폴더)에 드롭하고从此 반복할 수 있는 최소한의 SKILL.md입니다.
---
name: backup-check
description: Verify nightly backup archives exist, are non-empty, and pass a quick checksum spot-check on the latest file.
version: 1.0.0
metadata:
hermes:
tags: [devops, backups, shell]
requires_toolsets: [terminal]
config:
- key: backup_check.archive_dir
description: Absolute path to the directory that holds backup archives
default: "/var/backups"
prompt: Backup archive directory (absolute path)
---
# Backup archive spot-check
## When to use
Use when the user asks to confirm backups ran, to audit the latest archive on disk, or to catch empty or stale backup files before a restore drill.
## Quick reference
- Latest archive directory is configured under `skills.config.backup_check.archive_dir` (set via `hermes config migrate` if declared in metadata).
- Default check uses `ls` by mtime and `test -s` for non-empty files.
## Procedure
1. Resolve the archive directory from skill config or ask the user once if unset.
2. List the most recently modified file matching the expected pattern (for example `*.tar.zst`).
3. Confirm the file exists, is non-empty, and record its path and size for the reply.
4. If a checksum file exists beside the archive, verify it with the documented tool (for example `sha256sum -c`).
## Pitfalls
- Empty files can still have a recent mtime if a failed job touched the path; always check size.
- Relative paths break when the terminal cwd is not the backup host; use absolute paths in config.
## Verification
The user should see the latest archive path, byte size, and either a checksum OK line or an explicit note that no `.sha256` sidecar was found.
실제 점진적 공개
점진적 공개는 스냅피(snappy)하게 느껴지는 스킬 라이브러리와 첫 사용자 메시지 전에 수천 개의 토큰을 소모하는 라이브러리의 차이입니다. Hermes는 세 가지 개념적 단계를 밟습니다: 컴팩트한 카탈로그(이름과 짧은 설명), 작업이 일치할 때의 전체 SKILL.md, 그리고—필요하다면—skill_view 경로를 통한 참조 파일의 일부. 레벨 제로가 모델이 읽을 전부라고 가정하십시오. 명시적으로 커밋할 때까지 description과 본문 텍스트의 첫 화면에 있는 모든 문장은 스토리텔링이 아닌 라우팅에 도움이 되어야 합니다.
부분 로드에서도 견딜 수 있는 실용적인 개요는 When to use(평문으로 된 트리거), Quick reference(명령어, 환경 변수, 파일 경로), Procedure(에이전트가 임의대로 바꾸지 않아야 하는 순서 있는 단계), Pitfalls(알려진 실패 모드), Verification(“초록"이 어떤 모습인지)입니다. 서사적 역사, 벤더 변경 로그 덤프, 20줄 옵션 테이블은 에이전트가 단일 섹션을 끌어올 수 있도록 안정적인 헤딩과 함께 references/에 속합니다.
스킬이 활성화되면 Hermes는 셸 라인이 수동으로 빌드된 경로 없이 설치된 폴더를 가리키도록 본문에서 ${HERMES_SKILL_DIR} 및 **${HERMES_SESSION_ID}**를 다시 작성할 수 있습니다. 선택적 인라인 셸(inline shell) 스니펫(!cmd``)은 현재 브랜치, 디스크 여유 공간과 같은 최신 컨텍스트를 삽입할 수 있지만, 호스트에서 실행되며 skills.inline_shell이 켜져 있지 않으면 비활성화되므로 이 플래그를 편의 토글이 아닌 전체 스킬 소스의 신뢰 경계로 취급하십시오.
조건부 활성화 및 프롬프트 위생
스킬은 현재 세션에 있는 툴셋(toolset) 또는 도구에 따라 표시되거나 숨겨질 수 있습니다. requires_toolsets / requires_tools는 스킬을 반드시 존재해야 하는 기능 뒤에 게이트(gate)하고, fallback_for_toolsets / fallback_for_tools는 프리미엄 통합이 없을 때 더 저렴하거나 로컬 경로를 노출합니다—유료 웹 검색 API가 구성되지 않았을 때의 DuckDuckGo 폴백이 전형적인 예입니다.
이러한 예언(predicate)은 프롬프트 노이즈를 직접 형성합니다. 지나치게 엄격한 requires_* 규칙은 hermes tools 설정을 아직 완료하지 않은 신규 사용자에게 스킬을 숨깁니다. 지나치게 느슨한 fallback_for_* 규칙은 누군가가 API 키를 생략할 때마다 라이브러리의 절반을 중복합니다. 유용한 중간 지점은 실제 전제 조건을 명명하고, hermes chat --toolsets skills로 테스트하며, 스킬 목록이 예상대로 숨쉬는지 관찰하면서 키 또는 툴셋을 의도적으로 토글하는 것입니다.
시크릿, 설정, 자격 증명 파일
시크릿은 required_environment_variables에서 선언되어야 합니다. Hermes는 로컬 CLI에서 스킬이 로드될 때 프롬프트를 표시하고, 값을 .env에 지속하며, 원본 시크릿을 모델 전사로 스트리밍하지 않고 terminal 및 execute_code 샌드박스에 전달할 수 있습니다. 원격 채팅 표면은 인라인으로 키를 수집하는 것을 거부하고 대신 hermes setup 또는 수동 .env 편집을 지시하므로, 스킬 텍스트를 해당 동작에 맞게 작성하십시오(사용자에게 키가 필요하다는 것을 알려주되, Telegram에 붙여넣으라고 지시하지 마십시오).
비공개 설정—기본 경로, 조직 이름, 기능 토글—are는 metadata.hermes.config에 속합니다. 값은 config.yaml 내부의 skills.config로 해결되며, hermes config show에 표시되고, 모델이 작업 중간에 설정 파일을 열 필요가 없도록 해결된 사실로 스킬 메시지에 도착합니다.
파일 형태의 자격 증명(OAuth 토큰 JSON, 서비스 계정 키)은 required_credential_files에 매핑됩니다. 이러한 파일이 존재하면 Hermes는 Docker에 바인드 마운트하거나 Modal 작업으로 동기화할 수 있습니다. 사전에 선언하면 “로컬에서는 스크립트가 작동하지만 샌드박스에서는 죽는다"는 고전적인 격차를 방지합니다.
지원 스크립트 및 종속성
업스트림 가이드는 저자들을 지루한 종속성(boring dependencies)—stdlib Python, curl, Hermes 자체 도구(web_extract, read_file, terminal)—로 이끕니다. 이는 순수성보다 재현성에 관한 것입니다. 에이전트가 깨끗한 컨테이너에서 실행될 때 각 추가 pip install은 또 다른 침묵 실패입니다.
JSON 또는 XML 파싱이 까다로울 때, scripts/ 아래의 짧은 스크립트와 ${HERMES_SKILL_DIR} 경로가 매 실행마다 모델이 파서를 다시 유도하는 것보다 낫습니다. 패키지가 정말 필요하면 Procedure에서 설치 명령을 명시하고, Pitfalls에서 실패 증상을 반복하며, 종속성이 누락되었을 때 크게 실패하는 Verification 명령을 제공하십시오.
게시, 허브 설치, 신뢰
커뮤니티 스킬은 Skills Hub 및 사용자 가이드가 나열하는 다른 발견 경로를 통해 이동합니다—공식 선택적 스킬, GitHub 슬러그, skills.sh 항목, .well-known 인덱스, 원시 SKILL.md URL. 설치에는 명백한 탈출, 주입, 파괴적 패턴에 대한 스캔이 포함되며, 신뢰 등급은 builtin에서 community까지 다양하며, 일부 발견 사항은 --force로만 해결되고 최악의 사례는 완전히 차단됩니다.
SKILL.md 파일 형식은 Hermes 전용이 아닙니다. IDE 중심의 어시스턴트는 다른 발견 및 트리거와 함께 동일한 점진적 로딩 아이디어를 사용합니다. **Claude Skills and SKILL.md for Developers: VS Code, JetBrains, Cursor**은 유용한 대조 읽기입니다—설치자와 슬래시 명령어 배선이 다르더라도 프론트매터 규율과 “관련될 때만 로드"는 이어집니다.
조직 전체 롤아웃은 일반적으로 읽기 전용 공유를 위한 external_dirs와 프라이빗 탭 또는 공유 Git 저장소를 결합하며, skill_manage가 스킬을 제자리에서 변경할 수 있을 때 에이전트 작성 복사본을 각 프로필 아래에 유지합니다.
문제 해결 및 최적화
스킬이 잘못 작동할 때, 문구를 다시 작성하기 전에 이 체크리스트를 따르십시오.
- 가시성 —
platforms,requires_*,fallback_for_*예언을 확인하십시오. “맥에서는 작동하지만 Linux CI에서는 작동하지 않는” 스킬은 종종 플랫폼 가드입니다. - 이름 충돌 — 로컬 및 외부 디렉토리 간의 중복 이름은 로컬 우선순위를 따릅니다. 이름을 변경하거나 네임스페이스를 공격적으로 사용하십시오.
- 발견 레이아웃 — 잘못 배치된
SKILL.md또는 잘못된 카테고리 폴더는 스킬을 인덱싱에서 완전히 떨어뜨릴 수 있습니다. - 토큰 로드 — 세션이 느리게 느껴지면 레벨 제로 설명을 짧게 하고, 깊이를
references/로 이동하며, 거대한 테이블을 중복 제거하십시오. - 에이전트 편집 — Hermes는
skill_manage를 통해 스킬을 생성, 패치, 삭제할 수 있습니다. 가치 있는 스킬을 코드처럼 취급하십시오: diff를 검토하고, 스냅샷을 내보내며, 업그레이드가 편차할 때 번들된 스킬을 의도적으로 리셋하십시오.
긴 파일 전체를 재 읽는 것보다 조밀한 회귀 루프가 낫습니다: hermes chat --toolsets skills -q "Use the <skill> workflow to <concrete task>"는 에이전트가 프리스타일(freestyle)하기 전에 올바른 공개 레벨을 끌어오는 것을 보여야 합니다. skill_view를 호출하지 않는다면, When to use 텍스트 또는 description이 사람들이 요청을 표현하는 방식과 일치하지 않을 가능성이 큽니다.
공식 참조는 동작 변경에 대해 여전히 권위 있습니다—런타임 시맨틱스를 위한 Skills System 사용자 가이드, 저자 대상 규칙을 위한 Creating Skills, 복사-붙여넣기 예제를 위한 Bundled Skills Catalog, 그리고 Hermes가 정렬하는 공유 파일 형식을 위한 agentskills.io specification.
