스킬 작성

기준일: 2026-08-02
난이도: 중급
공식 기준: Creating Skills

개요

Skill은 에이전트 코드 자체를 수정하지 않고 Hermes 기능을 확장하는 가장 권장되는 방법이며, 커뮤니티와 쉽게 공유할 수 있습니다. SKILL.md 형식, progressive disclosure, env 요구, 배포 위치를 공식 기준으로 정리합니다.

핵심 개념

개념	설명
Skill vs Tool	지침 vs 코드 통합
Progressive disclosure	목록→본문→스크립트
requires_env	로드 전 자격증명
Blueprints	자동화 템플릿 겸 스킬

구현 가이드

스킬 vs 도구

Skill로 만드는 경우

• 지침과 셸 명령, 기존 도구의 조합만으로 동작이 성립할 때
• terminal이나 web_extract로 호출 가능한 외부 CLI·API를 감쌀 때
• 커스텀 Python 통합이나 에이전트 차원의 API 키 관리가 필요 없을 때
• 예: arXiv 검색, git 워크플로, Docker 관리, PDF 처리

Tool로 만드는 경우

• 엔드투엔드 API 통합, 인증 흐름, 복잡한 설정이 필요할 때
• 매번 정확한 실행이 요구되는 커스텀 처리 로직이 있을 때
• 바이너리 데이터, 스트리밍, 실시간 이벤트 처리가 필요할 때
• 예: 브라우저 자동화, TTS(음성 합성), 비전 분석

스킬 디렉터리 구조

스킬은 카테고리별로 skills/ 아래에 위치합니다. 널리 쓰이지 않는 공식 스킬은 optional-skills/에 둡니다.

skills/
├── research/
│   └── arxiv/
│       ├── SKILL.md              # Required: main instructions
│       └── scripts/              # Optional: helper scripts
│           └── search_arxiv.py
├── productivity/
│   └── ocr-and-documents/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
└── ...

SKILL.md 형식

frontmatter에는 name, description, version, author, license가 들어가고, 특정 OS로 제한하는 platforms, 태그·연관 스킬·도구 의존성을 담는 metadata.hermes(tags, related_skills, requires_toolsets, requires_tools, fallback_for_toolsets, fallback_for_tools, config, blueprint), 그리고 frontmatter 최상위 키인 required_environment_variables·required_credential_files를 선언할 수 있습니다.

본문 구조는 다음 순서를 따릅니다: 제목(# Skill Title) → 짧은 소개 → ## When to Use(언제 쓰는지) → ## Quick Reference(빠른 참조) → ## Procedure(절차) → ## Pitfalls(함정) → ## Verification(검증).

플랫폼 제한

platforms 필드로 스킬을 특정 OS에서만 노출할 수 있습니다.

platforms: [macos]              # macOS only
platforms: [macos, linux]       # Multiple platforms

제한된 스킬은 지원하지 않는 플랫폼에서 시스템 프롬프트에 자동으로 노출되지 않습니다.

조건부 활성화

필드	동작
requires_toolsets	나열된 toolset 중 하나라도 사용 불가능하면 스킬이 숨겨짐
requires_tools	나열된 tool 중 하나라도 사용 불가능하면 스킬이 숨겨짐
fallback_for_toolsets	나열된 toolset 중 하나라도 사용 가능하면 스킬이 숨겨짐
fallback_for_tools	나열된 tool 중 하나라도 사용 가능하면 스킬이 숨겨짐

fallback_for_*는 기본 도구가 설정되지 않았을 때의 대체 수단에, requires_*는 특정 도구·toolset이 반드시 필요한 스킬에 씁니다.

환경변수 요구사항

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.google.com/tenor
    required_for: full functionality

스킬이 skill_view로 로드되면 필요한 변수들은 terminal·execute_code 같은 샌드박스 실행 환경으로의 passthrough용으로 자동 등록됩니다. 값이 없으면 로컬 CLI가 안전하게 물어봅니다.

설정 값 (config.yaml)

비밀이 아닌 경로·선호값은 config로 선언합니다.

metadata:
  hermes:
    config:
      - key: myplugin.path
        description: "Path to plugin data directory"
        default: "~/myplugin-data"
        prompt: "Plugin data directory path"

값은 config.yaml의 skills.config 네임스페이스 아래에 저장됩니다. 구분 기준: 비밀 값은 환경변수(.env), 경로·선호값은 설정(config.yaml)을 씁니다.

자격 증명 파일

OAuth나 파일 기반 자격 증명을 쓰는 스킬은 required_credential_files로, 원격 샌드박스(Docker 컨테이너·Modal 등)에 마운트되어야 할 파일을 선언합니다.

required_credential_files:
  - path: google_token.json
    description: "Google OAuth2 token (created by setup script)"

스킬 가이드라인

• 외부 의존성 최소화 — stdlib Python, curl, 기존 Hermes 도구를 우선한다. 별도 설치가 필요하면 문서화한다.
• Progressive disclosure — 자주 쓰는 절차를 먼저, 예외 케이스는 뒤에 배치해 토큰 사용을 줄인다.
• 헬퍼 스크립트 포함 — 파싱이나 복잡한 로직은 모델이 즉석에서 작성하게 두지 말고 scripts/에 넣는다.
• 미디어는 문서로 전달 — 손실 압축이 아닌 무손실 전달이 필요한 고해상도 이미지·차트는 [[as_document]]로 표시한다.
• 토큰 치환 — SKILL.md는 ${HERMES_SKILL_DIR}, ${HERMES_SESSION_ID} 토큰 치환을 지원한다.

토큰	치환값
${HERMES_SKILL_DIR}	스킬 디렉터리 절대 경로
${HERMES_SESSION_ID}	활성 세션 id (세션이 없으면 그대로 남음)

To analyse the input, run:

    node ${HERMES_SKILL_DIR}/scripts/analyse.js <input>

인라인 셸 스니펫(!`cmd` 문법으로 동적 컨텍스트 주입)은 보안상 기본적으로 꺼져 있는 선택 기능입니다.

테스트: 다음처럼 실제 에이전트 동작으로 확인합니다.

hermes chat --toolsets skills -q "Use the X skill to do Y"

스킬 위치

• skills/ (번들 스킬) — 문서 처리, 웹 리서치, 흔한 개발 워크플로처럼 대부분의 사용자에게 폭넓게 유용한 스킬.
• optional-skills/ — 공식이지만 모두에게 필요하지는 않은 스킬(유료 연동, 무거운 의존성 등).
• Skills Hub — 커뮤니티·특화 스킬은 hermes skills install로 설치하는 레지스트리에 두는 편이 낫다.

Blueprints: 자동화를 겸하는 스킬

blueprint 블록을 추가하면 스킬을 스케줄 실행 대상으로 선언할 수 있습니다.

metadata:
  hermes:
    tags: [blueprint, email]
    blueprint:
      schedule: "0 8 * * *"     # presence of `blueprint:` marks it runnable
      deliver: telegram          # optional (default: origin)
      prompt: "Summarize my unread email and today's calendar."  # optional
      no_agent: false            # optional

Blueprint는 스케줄에 맞춰 실행될 수 있는 평범한 스킬입니다. 설치해도 자동으로 스케줄이 걸리지 않고 /suggestions를 통해 작업으로 제안됩니다. 흐름: 스킬 설치 → 제안된 작업 등장 → /suggestions accept N으로 스케줄링 → cron 작업 생성.

Suggested Cron Jobs

출처	트리거
catalog	큐레이션된 시작용 자동화 (/suggestions catalog) — daily briefing, important-mail monitor, weekly review, workday-start reminder
blueprint	blueprint: 블록을 가진 스킬을 설치했을 때
usage	백그라운드 리뷰가 스케줄로 처리하면 좋을 반복 요청을 감지했을 때
integration	계정(Gmail, GitHub 등)을 연결해 뻔한 자동화가 제안될 때

/suggestions             # list pending
/suggestions accept N    # schedule suggestion N (creates the cron job)
/suggestions dismiss N   # dismiss it — latched, never re-offered
/suggestions catalog     # add the curated starter automations

Publishing Skills

To the Skills Hub:

hermes skills publish skills/my-skill --to github --repo owner/repo

To a Custom Repository:

hermes skills tap add owner/repo

Security Scanning

Hub에서 설치하는 스킬은 데이터 유출, 프롬프트 인젝션, 파괴적 명령, 셸 인젝션에 대해 스캔됩니다. 신뢰 등급은 다음과 같습니다.

• builtin — Hermes에 기본 포함
• official — optional-skills/ 출처, 기본 신뢰
• trusted — 검증된 퍼블리셔(OpenAI, Anthropic, HuggingFace 등) 출처
• community — 위험하지 않다면 --force로 재정의 가능

스킬은 GitHub 식별자, skills.sh 식별자, 또는 /.well-known/skills/index.json 잘 알려진 엔드포인트를 통해 검색할 수 있습니다.

체크리스트

• 공식 원문 Creating Skills과 대조했다
• 관련 코드·설정·권한을 로컬에서 확인했다
• 보안·opt-in·allowlist 정책을 지켰다
• 스모크 테스트 또는 단계 검증을 수행했다

다음 단계

• 공식 문서: Creating Skills
• Hermes Agent 소개
• 트러블슈팅