스킬 만들기

anchor alias

스킬 만들기

스킬은 Hermes Agent에 새로운 능력을 추가할 때 가장 먼저 고려해야 하는 확장 방식입니다. 도구보다 만들기 쉽고, 에이전트 코드를 수정할 필요가 없으며, 커뮤니티와 공유하기도 쉽습니다.

스킬이어야 할까요, 도구여야 할까요?

다음과 같은 경우에는 스킬로 만드세요.

• 기능은 지침 + 셸 명령 + 기존 도구로 표현될 수 있습니다.
• 에이전트가 terminal 또는 web_extract를 통해 호출할 수 있는 외부 CLI나 API를 감쌉니다.
• 에이전트에 내장된 맞춤형 Python 통합이나 API 키 관리가 필요하지 않습니다.
• 예: arXiv 검색, git 워크플로, Docker 관리, PDF 처리, CLI 도구를 통한 이메일

다음과 같은 경우에는 도구로 만드세요.

• 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 형식

---
name: my-skill
description: Brief description (shown in skill search results)
version: 1.0.0
author: Your Name
license: MIT
platforms: [macos, linux]          # Optional — restrict to specific OS platforms
                                   #   Valid: macos, linux, windows
                                   #   Omit to load on all platforms (default)
metadata:
  hermes:
    tags: [Category, Subcategory, Keywords]
    related_skills: [other-skill-name]
    requires_toolsets: [web]            # Optional — only show when these toolsets are active
    requires_tools: [web_search]        # Optional — only show when these tools are available
    fallback_for_toolsets: [browser]    # Optional — hide when these toolsets are active
    fallback_for_tools: [browser_navigate]  # Optional — hide when these tools exist
    config:                              # Optional — config.yaml settings the skill needs
      - key: my.setting
        description: "What this setting controls"
        default: "sensible-default"
        prompt: "Display prompt for setup"
required_environment_variables:          # Optional — env vars the skill needs
  - name: MY_API_KEY
    prompt: "Enter your API key"
    help: "Get one at https://example.com"
    required_for: "API access"
---

# Skill Title

Brief intro.

## When to Use
Trigger conditions — when should the agent load this skill?

## Quick Reference
Table of common commands or API calls.

## Procedure
Step-by-step instructions the agent follows.

## Pitfalls
Known failure modes and how to handle them.

## Verification
How the agent confirms it worked.

플랫폼별 기술

스킬은 platforms 필드를 사용하여 특정 운영 체제로 제한될 수 있습니다.

platforms: [macos]            # macOS only (e.g., iMessage, Apple Reminders)
platforms: [macos, linux]     # macOS and Linux
platforms: [windows]          # Windows only

설정되면 해당 스킬은 시스템 프롬프트 skills_list() 및 호환되지 않는 플랫폼의 슬래시 명령에서 자동으로 숨겨집니다. 생략하거나 비어 있으면 모든 플랫폼에서 스킬이 로드됩니다(이전 버전과 호환 가능).

조건부 스킬 활성화

스킬은 특정 도구나 도구 세트에 대한 종속성을 선언할 수 있습니다. 이는 특정 세션에 대한 시스템 프롬프트에 스킬이 표시되는지 여부를 제어합니다.

metadata:
  hermes:
    requires_toolsets: [web]           # Hide if the web toolset is NOT active
    requires_tools: [web_search]       # Hide if web_search tool is NOT available
    fallback_for_toolsets: [browser]   # Hide if the browser toolset IS active
    fallback_for_tools: [browser_navigate]  # Hide if browser_navigate IS available

필드	행동
requires_toolsets	나열된 도구 세트 중 하나라도 사용할 수 없으면스킬이숨겨집니다
requires_tools	나열된 도구 중 하나라도 사용할 수 없으면스킬이숨겨집니다
fallback_for_toolsets	나열된 도구 세트 중 하나라도 사용 가능하면 스킬이 숨겨집니다
fallback_for_tools	나열된 도구 중 하나라도 사용 가능하면 스킬이 숨겨집니다

fallback_for_*의 사용 사례: 기본 도구를 사용할 수 없는 경우 해결 방법으로 사용되는 스킬을 만듭니다. 예를 들어 fallback_for_tools: [web_search]이 포함된 duckduckgo-search 스킬은 웹 검색 도구(API 키 필요)가 구성되지 않은 경우에만 표시됩니다.

requires_*의 사용 사례: 특정 도구가 있을 때만 의미가 있는 스킬을 만듭니다. 예를 들어, requires_toolsets: [web]을 사용하는 웹 스크래핑 워크플로 스킬은 웹 도구가 비활성화된 경우 프롬프트를 복잡하게 만들지 않습니다.

환경 변수 요구 사항

스킬은 필요한 환경 변수를 선언할 수 있습니다. skill_view을 통해 스킬이 로드되면 필수 변수가 샌드박스 실행 환경(터미널, 실행 코드)으로의 통과를 위해 자동으로 등록됩니다.

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: "Tenor API key"               # Shown when prompting user
    help: "Get your key at https://tenor.com"  # Help text or URL
    required_for: "GIF search functionality"   # What needs this var

각 항목은 다음을 지원합니다.

• name (필수) — 환경 변수 이름
• prompt (선택 사항) — 사용자에게 값을 물을 때 프롬프트 텍스트
• help (선택 사항) — 값을 얻기 위한 도움말 텍스트 또는 URL
• required_for (선택 사항) — 이 변수가 필요한 기능을 설명합니다.

사용자는 config.yaml에서 패스스루 변수를 수동으로 구성할 수도 있습니다.

terminal:
  env_passthrough:
    - MY_CUSTOM_VAR
    - ANOTHER_VAR

macOS 전용 스킬의 예는 skills/apple/을 참조하세요.

로드 시 보안 설정

스킬에 API 키 또는 토큰이 필요한 경우 required_environment_variables을 사용하세요. 누락된 값은 검색되지 않도록 스킬을 숨기지 않습니다. 대신, Hermes는 스킬이 로컬 CLI에 로드될 때 이를 안전하게 묻는 메시지를 표시합니다.

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

사용자는 설정을 건너뛰고 스킬을 계속 로드할 수 있습니다. Hermes는 절대 원시 비밀 값을 모델에 노출하지 않습니다. 게이트웨이 및 메시징 세션에서는 대역 내에서 비밀을 수집하는 대신 로컬 설정 지침을 표시합니다.

Sandbox Passthrough

스킬이 로드되면 설정된 모든 선언된 required_environment_variables은 Docker 및 Modal과 같은 원격 백엔드를 포함하여 execute_code 및 terminal 샌드박스에 자동으로 전달됩니다. 스킬의 스크립트는 사용자가 추가로 구성할 필요 없이 $TENOR_API_KEY(또는 Python의 경우 os.environ["TENOR_API_KEY"])에 액세스할 수 있습니다. 자세한 내용은 환경 변수 통과를 참조하세요.

레거시 prerequisites.env_vars은 이전 버전과 호환되는 별칭으로 계속 지원됩니다.

구성 설정(config.yaml)

스킬은 skills.config 네임스페이스 아래의 config.yaml에 저장된 비밀이 아닌 설정을 선언할 수 있습니다. 환경 변수(.env에 저장된 비밀)와 달리 구성 설정은 경로, 기본 설정 및 기타 중요하지 않은 값에 대한 것입니다.

metadata:
  hermes:
    config:
      - key: myplugin.path
        description: Path to the plugin data directory
        default: "~/myplugin-data"
        prompt: Plugin data directory path
      - key: myplugin.domain
        description: Domain the plugin operates on
        default: ""
        prompt: Plugin domain (e.g., AI/ML research)

각 항목은 다음을 지원합니다.

• key (필수) — 설정에 대한 도트 경로(예: myplugin.path)
• description (필수) — 설정이 무엇을 제어하는지 설명합니다.
• default (선택 사항) — 사용자가 구성하지 않은 경우 기본값
• prompt (선택 사항) — hermes config migrate 중에 표시되는 프롬프트 텍스트입니다. description로 대체됩니다.

작동 방식:

1. 저장소: 값은 skills.config.<key> 아래의 config.yaml에 기록됩니다.

   skills:
     config:
       myplugin:
         path: ~/my-data

2. 검색: hermes config migrate은 활성화된 모든 스킬을 검색하고 구성되지 않은 설정을 찾아 사용자에게 메시지를 표시합니다. 설정은 "스킬 설정" 아래의 hermes config show에도 나타납니다.

3. 런타임 주입: 스킬이 로드되면 해당 구성 값이 확인되어 스킬 메시지에 추가됩니다.

   [Skill config (from ~/.hermes/config.yaml):
     myplugin.path = /home/user/my-data
   ]

에이전트는 config.yaml 자체를 읽을 필요 없이 구성된 값을 확인합니다.

4. 수동 설정: 사용자가 직접 값을 설정할 수도 있습니다.

   hermes config set skills.config.myplugin.path ~/my-data

When to use which

API 키, 토큰 및 기타 비밀에는 required_environment_variables을 사용하세요(~/.hermes/.env에 저장되어 있으며 모델에는 표시되지 않음). 경로, 기본 설정 및 중요하지 않은 설정에는 config을 사용하세요(config.yaml에 저장되어 있으며 구성 표시에 표시됨).

자격 증명 파일 요구 사항(OAuth 토큰 등)

OAuth 또는 파일 기반 자격 증명을 사용하는 스킬은 원격 샌드박스에 탑재해야 하는 파일을 선언할 수 있습니다. 이는 파일(env vars 아님)로 저장된 자격 증명용입니다. 일반적으로 설정 스크립트에서 생성된 OAuth 토큰 파일입니다.

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

각 항목은 다음을 지원합니다.

• path (필수) — ~/.hermes/을 기준으로 한 파일 경로
• description (선택 사항) — 파일이 무엇인지, 어떻게 생성되는지 설명합니다.

로드되면 Hermes는 이러한 파일이 존재하는지 확인합니다. 누락된 파일이 setup_needed을 트리거합니다. 기존 파일은 자동으로 다음과 같습니다.

• Docker 컨테이너에 읽기 전용 바인드 마운트로 마운트됨
• 모달로 동기화됨 샌드박스(생성 시 + 각 명령 전이므로 세션 중간 OAuth가 작동함)
• 특별한 처리 없이 로컬 백엔드에서 사용 가능

When to use which

간단한 API 키 및 토큰(~/.hermes/.env에 저장된 문자열)에는 required_environment_variables을 사용합니다. OAuth 토큰 파일, 클라이언트 비밀번호, 서비스 계정 JSON, 인증서 또는 디스크에 있는 파일인 사용자 인증 정보에는 required_credential_files을 사용하세요.

두 가지를 모두 사용하는 전체 예는 skills/productivity/google-workspace/SKILL.md을 참조하세요.

스킬 가이드라인

외부 종속성 없음

stdlib Python, 컬 및 기존 Hermes 도구(web_extract, terminal, read_file)를 선호합니다. 종속성이 필요한 경우 스킬의 설치 단계를 문서화하세요.

점진적 공개

가장 일반적인 작업 흐름을 먼저 배치하세요. 엣지 케이스와 고급 사용법은 맨 아래에 있습니다. 이렇게 하면 일반적인 작업에 대한 토큰 사용량이 낮게 유지됩니다.

도우미 스크립트 포함

XML/JSON 구문 분석 또는 복잡한 논리의 경우 scripts/에 도우미 스크립트를 포함합니다. LLM이 매번 파서를 인라인으로 작성할 것이라고 기대하지 마십시오.

SKILL.md의 번들 스크립트 참조

스킬이 로드되면 활성화 메시지는 절대 스킬 디렉터리를 [Skill directory: /abs/path]으로 노출하고 SKILL.md 본문의 두 템플릿 토큰을 대체합니다.

토큰	다음으로 대체됨
${HERMES_SKILL_DIR}	스킬 디렉터리의 절대 경로
${HERMES_SESSION_ID}	활성 세션 ID(세션이 없는 경우 그대로 유지됨)

따라서 SKILL.md는 에이전트에게 다음을 사용하여 번들 스크립트를 직접 실행하도록 지시할 수 있습니다.

To analyse the input, run:

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

에이전트는 대체된 절대 경로를 확인하고 즉시 실행 가능한 명령으로 terminal 도구를 호출합니다. 경로 계산이나 추가 skill_view 왕복이 필요하지 않습니다. config.yaml의 skills.template_vars: false을 사용하여 전역적으로 대체를 비활성화합니다.

인라인 셸 조각(선택)

스킬은 SKILL.md 본문에 `` !cmd로 작성된 인라인 셸 조각을 포함할 수도 있습니다. 활성화되면 에이전트가 메시지를 읽기 전에 각 조각의 stdout이 메시지에 인라인되므로 스킬이 동적 컨텍스트를 삽입할 수 있습니다.

Current date: !`date -u +%Y-%m-%d`
Git branch: !`git -C ${HERMES_SKILL_DIR} rev-parse --abbrev-ref HEAD``

이는 **기본적으로 꺼져 있습니다**. SKILL.md의 모든 스니펫은 승인 없이 호스트에서 실행되므로 신뢰할 수 있는 기술 소스에 대해서만 활성화하세요.

```yaml
# config.yaml
skills:
  inline_shell: true
  inline_shell_timeout: 10   # seconds per snippet

스니펫은 기술 디렉터리를 작업 디렉터리로 사용하여 실행되며 출력은 4000자로 제한됩니다. 실패(시간 초과, 0이 아닌 종료)는 전체 스킬을 손상시키는 대신 짧은 [inline-shell error:...] 마커로 표시됩니다.

테스트해 보세요

스킬을 실행하고 에이전트가 지침을 올바르게 따르는지 확인합니다.

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

스킬은 어디에 있어야 합니까?

번들 기술(skills/)은 모든 Hermes 설치와 함께 제공됩니다. 대부분의 사용자에게 광범위하게 유용해야 합니다.

• 문서 처리, 웹 조사, 공통 개발 워크플로, 시스템 관리
• 다양한 사람들이 정기적으로 사용함

귀하의 기술이 공식적이고 유용하지만 보편적으로 필요하지 않은 경우(예: 유료 서비스 통합, 과도한 종속성) **optional-skills/**에 넣으십시오. 이는 리포지토리와 함께 제공되고 hermes skills browse("공식" 레이블이 지정됨)을 통해 검색 가능하며 기본 신뢰를 바탕으로 설치됩니다.

귀하의 기술이 전문적이거나 커뮤니티에 기여했거나 틈새 시장인 경우 기술 허브에 더 적합합니다. 등록소에 업로드하고 hermes skills install을 통해 공유하세요.

출판 기술

기술 허브로

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

사용자 정의 저장소로

탭으로 저장소를 추가하세요.

hermes skills tap add owner/repo

그러면 사용자는 저장소에서 검색하고 설치할 수 있습니다.

보안 스캐닝

허브에 설치된 모든 기술은 다음을 확인하는 보안 스캐너를 거칩니다.

• 데이터 유출 패턴
• 즉각적인 주입 시도
• 파괴적인 명령
• 쉘 주입

신뢰 수준:

• builtin — Hermes와 함께 배송됨(항상 신뢰할 수 있음)
• official — 저장소의 optional-skills/에서(내장된 신뢰, 제3자 경고 없음)
• trusted — openai/기술, 인류학/기술, 포옹얼굴/기술에서
• community — 위험하지 않은 결과는 --force로 override될 수 있습니다. dangerous 평결은 차단된 상태로 유지됩니다.

Hermes는 이제 여러 외부 검색 모델에서 타사 기술을 사용할 수 있습니다.

• 직접 GitHub 식별자(예: openai/skills/k8s)
• skills.sh 식별자(예: skills-sh/vercel-labs/json-render/json-render-react)
• /.well-known/skills/index.json에서 제공되는 잘 알려진 엔드포인트

GitHub 관련 설치 프로그램 없이 기술을 검색할 수 있도록 하려면 리포지토리나 마켓플레이스에 게시하는 것 외에도 잘 알려진 엔드포인트에서 기술을 제공하는 것을 고려하세요.