OpenClaw Skill 속성 설정 가이드

1. Skill 아키텍처 개요

OpenClaw Skill은 에이전트 프레임워크의 확장 메커니즘으로, LLM에 도구 활용법을 가르치는 모듈 단위입니다. YAML 프론트매터와 Markdown 본문으로 구성된 SKILL.md를 포함하는 디렉터리 형태로 배포되며, AgentSkills 표준을 따릅니다.

Skill의 핵심 역할은 범용 언어 모델을 특정 분야 전문가 에이전트로 전환하는 것입니다. 파일 처리, API 연동, 자동화 작업 등 복잡한 업무 수행에 필요한 지식과 도구 사용법을 에이전트에 주입합니다.

에이전트가 "두"라면 Skill은 "전문 경험 + 실행 매뉴얼"입니다. 에이전트는 Skill을 읽어 분야 지식을 습득하고, 이를 바탕으로 도구를 호출해 실제 작업을 수행합니다.

2. 디렉터리 구조와 SKILL.md 문법

2.1 디렉터리 레이아웃

Skill의 최소 구성 요소는 다음과 같은 파일 구조를 갖춘 디렉터리입니다:

my-skill/
├── SKILL.md          # 필수: YAML 메타델 + Markdown 지시사항
├── scripts/          # 선택: 실행 가능한 스크립트
├── references/       # 선택: 동적 로딩 참고 문서
└── assets/           # 선택: 출력용 자원

2.2 SKILL.md 구성

SKILL.md는 두 부분으로 이루어집니다:

YAML 프론트매터: 식별자, 설명, 실행 조건 등을 ---로 감싸 정의
Markdown 본문: 에이전트에게 전달되는 작업 지시와 설명

핵심 제약: OpenClaw의 파서는 단일 행 프론트매터 키-값만 지원합니다. 특히 metadata 필드는 반드시 한 줄짜리 JSON이어야 하며, YAML 여러 줄 들여쓰기 문법은 사용할 수 없습니다.

바른 작성 예시

---
name: demo_greet
description: 사용자에게 인사말을 전달합니다.
metadata: {"openclaw": {"requires": {"bins": ["echo"]}}}
---

# 데모 인사 Skill
사용자가 인사를 요청하면 `echo` 도구를 사용해 "안녕하세요, 커스텀 Skill입니다!"라고 출력하세요.

Markdown 본문 내에서는 {baseDir} 플레이스홀더로 Skill 디렉터리 경로를 참조할 수 있어, scripts/ 하위 파일 접근이 용이합니다.

3. 프론트매터 속성 상세

3.1 기본 필드

속성	필수	유형	설명
`name`	○	string	Skill 고유 식별자 (snake_case 권장)
`description`	○	string	프롬프트 구성 시 에이전트의 Skill 호출 판단 기준
`metadata`	○	string	한 줄 JSON, `openclaw` 네임스페이스 하위 확장 속성 포함
`user-invocable`	✕	boolean	사용자 슬래시 명령으로 노출 여부, 기본 `true`
`disable-model-invocation`	✕	boolean	`true` 시 모델 프롬프트에서 제외, 수동 트리거만 가능, 기본 `false`
`command-dispatch`	✕	string	`tool` 설정 시 슬래시 명령을 도구로 직접 분배
`command-tool`	✕	string	`command-dispatch: tool` 시 호출할 도구명
`command-arg-mode`	✕	string	도구 분배 시 인자 전달 방식, 기본 `raw`

3.2 metadata.openclaw 하위 속성

속성	설명
`os`	운영체제 필터 배열, 예: `["darwin", "linux"]`
`requires.bins`	모두 존재해야 하는 바이너리 목록
`requires.anyBins`	하나 이상 존재해야 하는 바이너리 목록
`requires.env`	필수 환경변수 (시스템 또는 `skills.entries.<skillKey>.env`로 제공)
`requires.config`	필수 설정 키 목록
`requires.always`	`true` 시 모든 조건 검사 무시, 항상 후보 포함. `enabled: false`는 미해제
`install`	설치기 명세 배열, `brew`/`node`/`go`/`uv`/`download` 지원
`skillKey`	기본 `name` 매핑을 덮어쓰는 사용자 정의 설정 키
`primaryEnv`	`apiKey`에 대응하는 환경변수명
`homepage`	macOS Skills UI의 "웹사이트" 링크
`emoji`	macOS Skills UI 아이콘

3.3 실행 조건과 자동 설치

requires는 Skill 로드 시 환경을 필터링합니다. requires.env는 시스템 환경변수뿐 아니라 설정 파일의 env 항목으로 제공된 값도 인정합니다.

metadata: {"openclaw": {"requires": {"bins": ["gh", "git"], "anyBins": ["jq", "yq"], "env": ["GITHUB_TOKEN"], "config": ["github.username"], "os": ["darwin", "linux"]}}}

OpenClaw는 evaluateEntryRequirementsForCurrentPlatform 함수로 OS 호환성, 바이너리 존재, 환경변수 충족 여부를 검증합니다.

install 필드로 의존성 자동 설치를 정의합니다:

설치기	설명	예시
`brew`	Homebrew 포뮬러	`{"type": "brew", "formula": "gh"}`
`node`	Node 패키지	`{"type": "node", "package": "axios"}`
`go`	Go 모듈	`{"type": "go", "module": "github.com/xxx/yyy@latest"}`
`uv`	Python uv	`{"type": "uv", "package": "ruff"}`
`download`	직접 다운로드	`url`, `archive`, `extract`, `stripComponents`, `targetDir` 등

Gateway는 install.preferBrew 설정에 따라 brew를 우선적으로 선택합니다.

4. skills.* 설정 스키마

Skill 로드와 설치 설정은 ~/.openclaw/openclaw.json의 skills 키 아래에 정의됩니다.

4.1 전체 설정 예시

{
  "skills": {
    "allowBundled": ["gemini", "peekaboo"],
    "load": {
      "extraDirs": ["~/Projects/agent-scripts/skills"],
      "watch": true,
      "watchDebounceMs": 250
    },
    "install": {
      "preferBrew": true,
      "nodeManager": "npm"
    },
    "entries": {
      "nano-banana-pro": {
        "enabled": true,
        "apiKey": { "source": "env", "provider": "default", "id": "GEMINI_KEY_HERE" },
        "env": {
          "GEMINI_API_KEY": "your-key-here"
        },
        "config": {
          "endpoint": "https://example.invalid",
          "model": "nano-pro"
        }
      }
    }
  }
}

4.2 설정 목 상세

속성	유형	기본값	설명
`allowBundled`	string[]	—	내장 Skill 화이트리스트. 설정 시 목록 내 Skill만 활성화, 외부/워크스페이스 Skill은 영향 없음
`load.extraDirs`	string[]	—	추가 Skill 스캔 디렉터리 (최하위 우선순위)
`load.watch`	boolean	true	Skill 폴더 변경 감시 및 스냅샷 갱신 여부
`load.watchDebounceMs`	number	250	감시 이벤트 디바운스 시간 (ms)
`install.preferBrew`	boolean	true	가능한 경우 brew 설치기 우선 사용
`install.nodeManager`	string	`"npm"`	Node 설치기 선호도 (npm \\| pnpm \\| yarn \\| bun)
`entries.<skillKey>.enabled`	boolean	—	false로 설정 시 해당 Skill 비활성화
`entries.<skillKey>.env`	object	—	에이전트 실행 시 주입할 환경변수 (미설정 시에만)
`entries.<skillKey>.apiKey`	string \\| SecretRef	—	주 API 키 단축 필드. 문자열 또는 `{ source: "env", provider: "default", id: "..." }`
`entries.<skillKey>.config`	object	—	Skill 내부에서 읽는 사용자 정의 설정

entries의 키는 기본적으로 Skill name에 대응합니다. metadata.openclaw.skillKey가 정의된 경우 해당 키를 사용합니다.

5. 로드 우선순위와 스코프

5.1 계층별 우선순위

동일 이름 충돌 시 상위 우선순위가 하위를 덮어씁니다:

위치	우선순위	적용 범위
`<workspace>/skills/`	최상위	단일 에이전트
`~/.openclaw/skills/`	중간	전역 공유
내장 (설치 패키지 포함)	하위	시스템 전역
`skills.load.extraDirs`	최하위	사용자 정의 공유

플러그인 Skill은 특별한 출처로, openclaw.plugin.json의 skills 디렉터리를 통해 포함되며 워크스페이스 Skill 다음, 공유 Skill 이전의 우선순위를 갖습니다.

5.2 에이전트별 Skill 가시성

에이전트 설정으로 접근 가능한 Skill 집합을 제어합니다:

{
  "agents": {
    "defaults": { "skills": ["github", "weather"] },
    "list": [
      { "id": "writer" },
      { "id": "docs", "skills": ["docs-search"] },
      { "id": "locked-down", "skills": [] }
    ]
  }
}

규칙:

agents.defaults.skills: 공통 기준 화이트리스트
agents.defaults.skills 미설정: 기본 제한 없음
agents.list[].skills: 해당 에이전트의 최종 Skill 집합, defaults와 병합되지 않고 완전 대체

6. 라이프사이클과 게이팅

6.1 로드 시 필터 조건

OS 호환성 (metadata.openclaw.os)
필수 바이너리 존재 (bins 전체, anyBins 일부)
필수 환경변수 설정 또는 구성 제공 여부
필수 설정 키 존재
에이전트 Skill 화이트리스트
allowBundled 화이트리스트

6.2 상태 조회와 핫 로딩

skills.status (Gateway)는 모든 Skill의 자격 상태와 미충족 요건을 반환하며, 내장 Skill의 allowBundled 차단 여부도 포함합니다.

OpenClaw는 세션 시작 시점에 적격 Skill을 스냅샷으로 캡처하며, 이후 턴에서 재사용합니다. load.watch: true 설정 시 폴더 변경이 감지되면 다음 에이전트 턴에 자동 반영되며 Gateway 재시작이 불필요합니다. 단, 새 세션 또는 감시기 트리거를 통해 갱신되어야 적용됩니다.

7. 환경변수와 비밀 관리

7.1 주입 방식

설정 파일: skills.entries.<skillKey>.env로 ~/.openclaw/openclaw.json에 정의
API 키 단축: skills.entries.<skillKey>.apiKey로 주 환경변수 간편 선언
런타임 갱신: skills.update 명령으로 enabled, apiKey, env 수정

7.2 샌드박스 리 시 주의

샌드박스 세션에서는 Skill 프로세스가 Docker 내부에서 실행되며, 호스트의 process.env를 상속받지 않습니다.

해결책:

agents.defaults.sandbox.docker.env 또는 개별 에이전트의 agents.list[].sandbox.docker.env 사용
커스텀 샌드박스 이미지에 환경변수 빌드 시 포함

전역 env와 skills.entries.<skill>.env/apiKey는 호스트 실행 시에만 적용됩니다.

8. 원격 macOS 노드 지원

Linux에서 Gateway가 실행되어도 macOS 노드가 연결된 경우, metadata.openclaw.os: ["darwin"]으로 제한된 Skill도 nodes.run을 통해 원격 macOS 노드에서 실행 가능해집니다. 이를 통해 크로스 플랫폼 배포가 유연해집니다.

9. 토큰 비용 분석

Skill이 모델 프롬프트에 주입되면 다음과 같은 토큰 오버헤드가 발생합니다:

고정 오버헤드: 1개 이상 Skill 활성화 시 195자前치 접두사
개별 Skill 오버헤드: 97자 + name + description + location의 XML 이스케이프 길이

name과 description 길이를 제어하여 컨텍스트 창 사용을 최적화할 수 있습니다.

10. 보안 속성과 운영 권고

10.1 보안 체크리스트

외부 Skill은 신뢰하지 않는 코드로 취급: 활성화 전 내용 검증
샌드박스 격리 우선: 신뢰할 수 없는 입력과 고위험 도구는 샌드박스 실행
비밀 보호: skills.entries.*.env와 apiKey는 호스트 프로세스에 주입되므로, 프롬프트와 로그에 유출되지 않도록 주의
네트워크 격리: OpenClaw 기본 포트를 공개망에 노출하지 고, 관리자 권한으로 실행하지 말 것

10.2 경로 탐색 방어

워크스페이스와 추가 디렉터리의 Skill 발견은, 해석된 실제 경로가 설정 루트 내에 있는 경우만 수락합니다. 심볼릭 링크를 통한 임의 파일시스템 위치 탈출을 방지합니다.

구버전 (< 2026.2.14)에서는 샌드박스 Skill 이미지의 경로 탐색 취약점(CVE-2026-28457)이 존재했으나, 미검증된 Skill 프론트매터 name 매개변수를 통한 것으로 후속 버전에서 수정되었습니다.

10.3 권한 모델

Skill은 독립 권한을 갖지 않으며, 활성화된 Tools만 호출할 수 있습니다. 대응 Tools 미활성화 시 Skill은 무효화됩니다. 내장 bundled Skills는 시스템과 연동되어 자동 활성화되므로, 필요시 화이트리스트로 제한하세요.

10.4 개발 원칙

간결성: 컨텍스트 창은 공유 자원, 에이전트가 모르는 내용만 추가, 장문 설명보다 간결한 예시 우선
적절한 자유도: 작업의 취약성과 가변성에 맞춰 상세도 조절 (높은 자유도 지시 → 중간 자유도 의사코드 → 낮은 자유도 특정 스크립트)
로컬 검증: 배포 전 openclaw agent --message "..."로 테스트
Skill Creator 활용: OpenCl의 Skill Creator는 Skill 제작의 모범 사례이자 agentskills 표준 준수 예시

11. CLI와 API 참조

11.1 명령어

명령어	소속	기능
`openclaw skills list`	OpenClaw CLI	로드된 Skill 목록
`openclaw skills install <slug>`	OpenClaw CLI	ClawHub에서 워크스페이스로 Skill 설치
`openclaw skills update --all`	OpenClaw CLI	설치된 모든 Skill 갱신
`openclaw gateway restart`	OpenClaw CLI	설정 변경 적용을 위한 Gateway 재시작
`clawhub login`	ClawHub CLI	브라우저 인증
`clawhub publish <path>`	ClawHub CLI	ClawHub 레지스트리에 Skill 게시
`clawhub sync --all`	ClawHub CLI	로컬 Skill 스캔 및 업데이트 게시

11.2 Gateway REST API

기본 엔드포인트 http://127.0.0.1:18789:

skills.status: 전체 Skill 자격 상태 반환
skills.install: Gateway 호스트에서 Skill 설치기 실행
skills.update: enabled, apiKey, env 설정 갱신

12. 완전한 Skill 정의 예시

SKILL.md

---
name: github_pr_manager
description: GitHub PR 생성, 검토, 병합을 관리합니다.
metadata: {"openclaw": {"os": ["darwin", "linux"], "requires": {"bins": ["gh", "git"], "env": ["GITHUB_TOKEN"], "config": ["github.username"]}, "install": [{"type": "brew", "formula": "gh"}, {"type": "node", "package": "@octokit/rest"}], "skillKey": "github", "primaryEnv": "GITHUB_TOKEN", "emoji": "", "homepage": "https://cli.github.com"}}
user-invocable: true
disable-model-invocation: false
---

# GitHub Pull Request 관리자

이 Skill은 `gh` CLI를 사용해 GitHub PR을 관리합니다.

## 사용 시점
- PR 생성 요청
- PR 검토 또는 병합 요청
- 저장소의 열린 PR 목록 조회

## 명령어

1. PR 목록: `gh pr list --repo <owner>/<repo>`
2. PR 생성: `gh pr create --title "..." --body "..." --base main`
3. PR 병합: `gh pr merge <pr-number> --merge`

## 환경
`GITHUB_TOKEN`에 적절한 repo 권한이 설정되어 있어야 합니다.

설정 파일 (~/.openclaw/openclaw.json)

{
  "skills": {
    "entries": {
      "github": {
        "enabled": true,
        "apiKey": { "source": "env", "provider": "default", "id": "GITHUB_TOKEN" },
        "env": {
          "GITHUB_TOKEN": "your-github-token-here"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "skills": ["github", "weather"]
    }
  }
}

태그: OpenClaw AgentSkills YAML Frontmatter LLM Agent Skill Configuration

6월 21일 16:15에 게시됨

괴물 클럽