본문으로 건너뛰기

스킬 만들기

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 자체를 읽을 필요 없이 구성된 값을 확인합니다.

  1. 수동 설정: 사용자가 직접 값을 설정할 수도 있습니다.
    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 관련 설치 프로그램 없이 기술을 검색할 수 있도록 하려면 리포지토리나 마켓플레이스에 게시하는 것 외에도 잘 알려진 엔드포인트에서 기술을 제공하는 것을 고려하세요.