OpenClaw Skill 시스템 완벽 가이드

1. Skill의 정의

Skill은 SKILL.md 파일을 포함하는 디렉토리로, AgentSkills 규격을 따릅니다. Markdown 명령어를 통해 LLM이 특정 도구나 워크플로우를 활용하는 방법을 가르칩니다.

my-skill/
├── SKILL.md          # 필수: 정의 + 지침
├── scripts/          # 선택: 실행 가능한 스크립트
├── references/       # 선택: 필요 시 로드하는 참조 문서
└── assets/           # 선택: 출력용 리소스 파일

SKILL.md 구조:

---
name: my-skill
description: LLM이 언제 호출할지 판단하는 한 줄 설명
user-invocable: true
metadata:
  { "openclaw": { "emoji": "", "skillKey": "my-skill", "requires": { "bins": ["some-cli"] } } }
---

여기에 Markdown 본문을 작성합니다. LLM이 이 skill을 사용하기 위한 완전한 지침을 포함합니다...

2. Skill 저장 위치 (우선순위 낮음 → 높음)

출처	경로	설명
플러그인/확장	`skills.load.extraDirs[]` + 플러그인 내 `skills/`	서드파티 확장
기본 내장	`<설치 디렉토리>/skills/`	OpenClaw와 함께 배포 (35개 이상)
로컬 관리	`~/.openclaw/skills/`	사용자 전역 skill
개인 에이전트	`~/.agents/skills/`	프로젝트 간 개인 skill
프로젝트 에이전트	`<워크스페이스>/.agents/skills/`	프로젝트 수준 skill
워크스페이스	`<워크스페이스>/skills/`	최고 우선순위

동일한 이름의 skill은 우선순위가 높은 것으로 덮어씁니다.

3. Skill 호출 방식

1. 모델 자동 호출 — skill의 name과 description이 시스템 프롬프트에 포함되어, LLM이 사용자 의도에 따라 자동으로 호출 여부를 결정합니다.

2. 사용자 수동 호출 — 대화창에 /skill-name(슬래시 명령어)을 입력하여 직접 skill을 활성화합니다.

Frontmatter 옵션으로 동작 제어:

user-invocable: true — 사용자 슬래시 명령어로 노출
disable-model-invocation: true — 모델 자동 호출 비활성화, 사용자가 직접 호출만 가능
command-dispatch: tool — 모델을 거치지 않고, 지정된 도구를 직접 호출

4. Skill 접근 제어 (Gating)

metadata.openclaw의 필드를 사용해 skill 사용 가능 여부를 제어합니다:

{
  "openclaw": {
    "always": true,                    // 모든 검사 건너뛰고 항상 로드
    "os": ["darwin", "linux"],         // 운영체제 제한
    "requires": {
      "bins": ["ffmpeg"],              // 필수 CLI 도구
      "anyBins": ["bun", "node"],      // 이 중 하나는 설치되어야 함
      "env": ["OPENAI_API_KEY"],       // 필수 환경변수
      "config": ["browser.enabled"]    // 활성화되어야 하는 설정
    }
  }
}

조건을 만족하지 못하는 skill은 LLM 컨텍스트에 로드되지 않습니다.

5. CLI 관리 명령어

openclaw skills list               # 모든 skill 확인
openclaw skills list --eligible    # 현재 사용 가능한 skill만 표시
openclaw skills list --verbose     # 누락된 의존성 상세 정보
openclaw skills info <이름>        # 개별 skill 상세 정보
openclaw skills check              # 모든 skill 상태 점검

6. 설정 관리

~/.openclaw/openclaw.json 파일에서:

{
  "skills": {
    // 활성/비활성 + API 키 관리
    "entries": {
      "gemini": { "enabled": true, "apiKey": "xxx" },
      "peekaboo": { "enabled": false }
    },
    // 내장 skill 범위 제한
    "allowBundled": ["gemini", "peekaboo"],
    // 추가 skill 디렉토리
    "load": {
      "extraDirs": ["~/my-skills-pack/skills"],
      "watch": true
    }
  }
}

에이전트별 skill 필터링:

{
  "agents": {
    "list": [
      { "id": "coding-agent", "skills": ["gemini", "github"] }
    ]
  }
}

7. 모범 사례

1. 계층형 관리

시나리오	위치
모든 프로젝트 공통 개인 skill	`~/.agents/skills/`
특정 프로젝트 전용 skill	`<프로젝트>/.agents/skills/`
팀 공유 skill (Git 커밋)	`<프로젝트>/skills/`
서드파티 skill 패키지	`skills.load.extraDirs`

2. SKILL.md 작성 팁

description은 정확하고 간결하게 작성하여 LLM이 호출 시점을 올바르게 판단하도록 함
requires로 의존성을 선언하여 런타임 오류 방지
본문에는 사용 시점 / 사용 금지 시점을 명확히 기술 (내장 skill의 "Use when" / "Do NOT use" 패턴 참조)
스크립트는 scripts/, 방대한 참고 자료는 references/에 배치 (필요 시 로드, 토큰 절약)

3. 토큰 비용 관리

사용 가능한 모든 skill은 시스템 프롬프트에 토큰을 소모합니다. 권장 사항:

enabled: false로 자주 사용하지 않는 skill 비활성화
allowBundled로 필요한 내장 skill만 로드
disable-model-invocation: true로 자주 사용하지 않지만 가끔 필요한 skill은 /명령어로만 호출
SKILL.md 본문은 최대한 간결하게 유지

4. 핫 리로드 개발

skills.load.watch: true 설정 후 SKILL.md를 수정하면 자동으로 리로드됩니다 (기본 250ms 디바운스). 개발 및 디버깅 시 재시작 불필요.

5. 보안 주의사항

skill 의존성 설치 전 자동 보안 스캔 수행 (child_process, eval, 데이터 외부 전송 등 위험 패턴 탐지)
apiKey는 설정 파일에 저장되고, 환경변수를 통해 런타임에 주입되며 실행 종료 후 자동 제거
SKILL.md에 민감 정보를 하드코딩하지 않음

태그: OpenClaw LLM Skill AgentSkills markdown

6월 15일 01:10에 게시됨

괴물 클럽