에이전트 스킬 작성 — SKILL.md 구조와 모범 사례
저자 헤르메스 - 빠르게 로드되고 신뢰성 있게 작동하는 스킬
Hermes Agent는 반복 가능한 워크플로우를 가르치는 기본 방법으로 스킬을 취급합니다. 공식 문서는 스킬을 agentskills.io의 오픈 형식과 일치하는 온디맨드 지식 문서로 설명하며, 모델이 먼저 작은 인덱스를 보고 작업이 실제로 필요할 때만 전체 지침을 가져오도록 점진적 공개를 통해 로드됩니다.
스킬 작성은 말솜씨보다 패키징에 관한 것입니다—런타임에 언제 절차를 로드해야 하는지, 어떤 단계 순서가 “완료"인지, 성공과 조용한 실패를 어떻게 구분해야 하는지를 알려주는 것입니다. 이 글은 SKILL.md 구조, 지원 폴더, 가시성 규칙, 그리고 비밀 설정과 비비밀 설정의 구분에 초점을 맞춥니다—스킬이 /slash 명령에 표시되는지, 허브 설치를 견뎌내는지, CI에서 조용히 사라지는지를 결정하는 세부사항들입니다.
Hermes는 AI 시스템: 자체 호스팅 어시스턴트, RAG, 로컬 인프라 클러스터의 일부로, 어시스턴트를 단일 채팅 표면이 아닌 추론, 검색, 메모리, 도구로 구성된 시스템으로 취급합니다. 설치 경로, 제공자 연결, 게이트웨이 동작, ~/.hermes 레이아웃은 Hermes AI 어시스턴트 - 설치, 설정, 워크플로우 및 문제 해결 가이드에 명시되어 있으며, 일상적인 쉘 사용성—hermes skills, 프로필, 게이트웨이, 메모리—은 **Hermes Agent CLI 치트시트 — 명령어, 플래그, 슬래시 단축키**에서 더 쉽게 스캔할 수 있습니다. 실제 배포 환경에서는 스킬이 프로필로부터 격리를 상속받습니다(별도의 설정, 비밀, 메모리, 스킬 트리). **실제 프로덕션 설정을 위한 Hermes AI 어시스턴트 스킬**는 개별 마크다운 파일이 아닌 프로필을 소유 단위로서 취급해야 한다고 주장합니다—스킬 이름을 정하고 공유 external_dirs와 단일 프로필 사이에 무엇을 둘지 결정할 때 이를 염두에 두세요.
스킬 vs 도구?
공식 가이드라인은 명쾌합니다. 기능이 주로 Hermes가 이미 노출하는 쉘 명령어와 도구를 활용한 텍스트 지침인 경우—CLI 랩핑, git 구동, curl 호출, 또는 구조화된 가져오기를 위한 web_extract 사용—스킬을 사용하세요. API 키 및 인증 흐름에 대한 긴밀한 통합, 결정론적 바이너리 처리, 스트리밍, 또는 매번 동일하게 실행되어야 하는 Python이 필요한 경우 도구를 사용하세요.
이 경계는 실제로 중요합니다. 스킬은 에이전트 코드를 변경하지 않고 배포되지만, 도구는 검토 및 릴리스 오버헤드를 수반합니다. 대부분의 팀은 스킬로 시작한 다음, 실패 모드가 명확해지면(인증 갱신 루프, 바이너리 파서, 엄격한 멱등성) 취약한 핵심 부분만 도구로 승격시키는 편이 이롭습니다. 자격 증명, 라이브 상태, 트랜잭션 쓰기를 중심으로 에이전트 스킬 vs MCP 서버 사용 시기에 대한 더 넓은 아키텍처 질문은 에이전트 스킬 vs MCP 서버 결정 프레임워크를 참조하세요.
절차 vs 큐레이션된 메모리
스킬은 워크플로우를 어떻게 실행할지 답하고, Hermes의 유한한 코어 메모리는 사용자와 프로젝트에 대해 이미 합의된 내용을 답합니다. 스킬은 작업이 설명과 일치할 때 로드되며, MEMORY.md와 USER.md는 작은 큐레이션된 사실 계층으로 프롬프트에 남습니다. 두 메커니즘은 경쟁하기보다 쌓이며, 스냅샷, 제한, 외부 제공자에 대한 전체 그림은 **Hermes Agent 메모리 시스템: 영속적 AI 메모리가 실제로 작동하는 방식**에 설명되어 있습니다.
스킬 디렉터리 구조
디스크 상에서 모든 스킬은 ~/.hermes/skills/ 하위의 폴더이며, 종종 devops/ 또는 research/와 같은 카테고리로 중첩됩니다. Hermes는 **리프에 SKILL.md**를 기대합니다; 나머지는 지침이 그렇지 않으면 흩어질 때 추가하는 선택적 구조입니다. 일반적인 패턴은 긴 테이블이나 벤더 문서를 위한 references/, 출력 골격을 위한 templates/, 결정론적 헬퍼를 위한 scripts/, 에이전트가 다시 가져와서는 안 되는 정적 파일을 위한 assets/입니다.
이 레이아웃은 점진적 공개가 실제로 작동하는 방식을 반영합니다: 에이전트는 진정한 깊은 부록을 필요로 할 때까지 메인 파일에 머물 수 있습니다. “해피 패스” 텍스트를 SKILL.md에 유지하고 드물게 사용되는 세부사항을 references/로 밀어내는 것이 토큰 예산을 보호하는 가장 저렴한 방법 중 하나입니다.
Hermes는 config.yaml의 skills.external_dirs를 통해 외부 스킬 디렉터리도 병합할 수 있습니다. 이러한 경로는 발견을 위해 스캔되지만, 에이전트는 여전히 skill_manage를 통해 주요 ~/.hermes/skills/ 트리에 씁니다. 로컬 이름이 외부 이름을 섀도우하므로, 홈 디렉터리에서 공유 스킬을 “수정"하면 같은 외부 리포지토리를 가져오는 팀원은 로컬 복사본을 제거하거나 이름을 변경할 때까지 수정 사항을 보지 못합니다—“제 컴퓨터에서는 작동하는데” 혼란의 흔한 원인입니다.
검토를 견뎌내는 SKILL.md 프론트매터
SKILL.md의 본문은 마크다운이며, 시작 블록은 --- 구분자 사이의 유효한 YAML이어야 합니다. 실제 스킬은 긴 펜스된 예제를 축적하므로, **마크다운 코드 블록: 문법, 언어 및 예제 포함 완전 가이드**의 작은 습관—일관된 언어 태그, 읽기 쉬운 발췌, 조밀한 펜스—은 큰 파일을 인간에게 유지 가능하게 하고 모델이 스캔하기 약간 더 쉽게 만듭니다.
필수 필드는 name과 description입니다. name은 슬래시 라우트 및 인덱스 키가 되며, 하이픈을 사용한 소문자로 유지되고 문서화된 길이 상한을 준수해야 합니다. description은 많은 세션이 레벨 제로에서 지불하는 유일한 텍스트이므로, 블로그 글의 첫 단락이 아닌 검색 결과나 라우터 문자열처럼 읽히어야 합니다(“백업이 오래되어 보일 때, 최신 아카이브와 체크섬 확인”).
선택적 최상위 키인 version, author, license는 허브 패키징과 감사에 도움이 됩니다. platforms 목록(macos, linux, windows)은 보이는 것보다 더 날카롭습니다—설정되면 Hermes는 일치하지 않는 호스트에서 스킬을 완전히 생략하므로, “맥에서는 작동하는데” 스킬이 Linux CI에서 더 짧은 스킬 목록 외에는 오류 메시지 없이 사라질 수 있습니다.
Hermes 특화 설정은 metadata.hermes 아래에 있습니다: tags, related_skills, 그리고 다음 섹션의 조건부 가시성 필드. **required_environment_variables**는 .env에 저장되고 샌드박스에 전달되어야 하는 비밀을 선언합니다; **required_credential_files**는 Docker나 Modal에 마운트되어야 하는 OAuth 토큰 파일과 다른 디스크 자격 증명을 다룹니다; **metadata.hermes.config**는 config.yaml의 skills.config 아래에 저장되는 비비밀 선호도를 선언합니다.
공식 문서는 이유 있는 이유로 크기 관리를 강조합니다. 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.
실제 점진적 공개
점진적 공개는 스냅피하게 느껴지는 스킬 라이브러리와 첫 사용자 메시지 전에 수천 토큰을 태우는 라이브러리의 차이입니다. Hermes는 세 가지 개념적 단계를 밟습니다: 압축된 카탈로그(이름과 짧은 설명), 작업이 일치할 때 전체 SKILL.md, 그리고—필요한 경우에만—skill_view 경로를 통한 참조 파일의 일부. 레벨 제로가 모델이 명시적으로 커밋하기 전에 읽는 전부라고 가정하세요; description과 본문 텍스트의 첫 화면의 모든 문장은 스토리텔링이 아닌 라우팅에 도움이 되어야 합니다.
부분 로드를 견뎌내는 실용적인 개요는 사용 시기(평어 트리거), 빠른 참조(명령어, env 변수, 파일 경로), 절차(에이전트가 즉흥적으로 버려서는 안 되는 순서된 단계), 함정(알려진 실패 모드), 검증(“초록"이 어떻게 보이는지)입니다. 서사적 역사, 벤더 변경 로그 덤프, 20행 옵션 테이블은 에이전트가 단일 섹션을 가져올 수 있도록 안정된 헤딩과 함께 references/에 속합니다.
스킬이 활성화되면, Hermes는 본문의 **${HERMES_SKILL_DIR}**와 **${HERMES_SESSION_ID}**를 다시 쓸 수 있으므로 쉘 라인이 수동으로 만든 경로 없이 설치된 폴더를 가리킵니다. 선택적 인라인 쉘 스니펫(!cmd``)은 새로운 컨텍스트(현재 브랜치, 디스크 여유 공간)를 주입할 수 있지만, 호스트에서 실행되며 skills.inline_shell이 켜져 있지 않으면 비활성화됩니다—그 플래그를 편의 토글이 아닌 전체 스킬 소스에 대한 신뢰 경계로 취급하세요.
조건부 활성화 및 프롬프트 위생
스킬은 현재 세션에 어떤 툴셋 또는 도구가 존재하는지에 따라 표시하거나 숨길 수 있습니다. requires_toolsets / requires_tools는 반드시 존재해야 하는 기능 뒤에 스킬을 게이트하고; fallback_for_toolsets / fallback_for_tools는 프리미엄 통합이 없을 때 더 저렴하거나 로컬 경로를 표면화합니다—유료 웹 검색 API가 설정되지 않았을 때의 DuckDuckGo 폴백이 정통 예입니다.
이러한 술어는 직접적으로 프롬프트 노이즈를 형성합니다. 지나치게 엄격한 requires_* 규칙은 아직 hermes tools 설정을 완료하지 않은 초보자에게 스킬을 숨기고; 지나치게 느슨한 fallback_for_* 규칙은 누군가가 API 키를 생략할 때마다 라이브러리의 절반을 중복합니다. 유용한 중도는 실제 선결 조건을 명명하고, hermes chat --toolsets skills로 테스트하며, 스킬 목록이 기대하는 대로 숨쉬는지 보며 의도적으로 키 또는 툴셋을 토글하는 것입니다.
비밀, 설정, 자격 증명 파일
비밀은 required_environment_variables에서 선언되어야 합니다. Hermes는 로컬 CLI에서 스킬이 로드될 때 프롬프트하고, .env에 값을 영속화하며, 원본 비밀을 모델 트랜스크립트로 스트리밍하지 않고 terminal과 execute_code 샌드박스에 전달할 수 있습니다. 원격 채팅 표면은 인라인으로 키를 수집하는 것을 거부하고 대신 hermes setup이나 수동 .env 편집을 가리킵니다—사용자에게 키가 필요하다는 것을 알리고 텔레그램에 붙여넣으라고 하지 않도록 스킬 텍스트를 작성하세요.
비비밀 선호도—기본 경로, 조직 이름, 기능 토글—는 metadata.hermes.config에 속합니다. 값은 config.yaml 내부의 skills.config로 해석되고, hermes config show에 표시되며, 모델이 작업 중에 설정 파일을 열 필요가 없도록 해결된 사실로서 스킬 메시지에 도달합니다.
파일 모양 자격 증명(OAuth 토큰 JSON, 서비스 계정 키)은 required_credential_files에 매핑됩니다. 이러한 파일이 존재하면 Hermes는 Docker에 바인드 마운트하거나 Modal 작업에 동기화할 수 있습니다; 사전에 선언하면 “로컬에서는 작동하는데 샌드박스에서는 죽는” 격차를 피할 수 있습니다.
지원 스크립트 및 의존성
업스트림 가이드는 작성자를 지루한 의존성으로 이끕니다: stdlib Python, curl, Hermes의 자체 도구(web_extract, read_file, terminal). 이는 순수성에 관한 것이 아니라 재현성에 관한 것입니다—에이전트가 깨끗한 컨테이너에서 실행될 때 각 추가 pip install은 또 다른 조용한 실패입니다.
JSON 또는 XML 파싱이 까다로우면, scripts/ 아래 짧은 스크립트와 ${HERMES_SKILL_DIR} 경로가 모델에게 매번 파서를 재파생하라고 요청하는 것보다 낫습니다. 패키지가 정말 필요하면 절차에서 설치 명령어를 명시하고, 함정에서 실패 증상을 반복하며, 의존성이 없으면 크게 실패하는 검증 명령어를 제공하세요.
게시, 허브 설치, 신뢰
커뮤니티 스킬은 사용가이드가 나열하는 스킬 허브와 다른 발견 경로를 통해 이동합니다—공식 선택적 스킬, GitHub 슬러그, skills.sh 항목, .well-known 인덱스, 원시 SKILL.md URL. 설치는明显的인 유출, 주입, 파괴적 패턴을 스캔합니다; 신뢰 티어는 빌트인에서 커뮤니티까지이며, 일부 발견은 --force로만 해결되고 가장 나쁜 사례는 완전히 차단됩니다.
SKILL.md 파일 형식은 Hermes 특화가 아닙니다; IDE 중심 어시스턴트는 다른 발견과 트리거를 사용하여 동일한 점진적 로딩 아이디어를 사용합니다. **개발자를 위한 Claude 스킬 및 SKILL.md: 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 "<구체적 작업>에 <스킬> 워크플로우 사용"은 에이전트가 즉흥적으로 하기 전에 올바른 공개 수준을 가져오는 것을 보여야 합니다. skill_view를 결코 호출하지 않으면, 사용 시기 텍스트나 description이 사람들이 요청을 표현하는 방식과 일치하지 않을 가능성이 높습니다.
공식 참조는 동작 변경에 대해 권위 있습니다—런타임 시맨틱을 위한 스킬 시스템 사용자 가이드, 작성자 대상 규칙을 위한 스킬 생성, 복사-붙여넣기 예제를 위한 번들 스킬 카탈로그, Hermes가 일치하는 공유 파일 형식을 위한 agentskills.io 사양.
