스킬 (OpenClaw)

OpenClaw는 AgentSkills 호환 스킬 폴더를 사용하여 에이전트에게 도구 사용법을 알려줍니다. 각 스킬은 YAML 프론트매터와 안내가 포함된 SKILL.md 파일이 있는 디렉터리입니다. OpenClaw는 번들 스킬 및 선택적 로컬 재정의를 로드하고, 환경, 설정, 바이너리 존재 여부에 따라 로드 시점에 필터링합니다.

위치 및 우선순위

스킬은 세 곳에서 로드됩니다:

번들 스킬: 설치와 함께 제공 (npm 패키지 또는 OpenClaw.app)
관리/로컬 스킬: ~/.openclaw/skills
워크스페이스 스킬: <workspace>/skills

스킬 이름이 충돌하면 우선순위:

<workspace>/skills (최상위) → ~/.openclaw/skills → 번들 스킬 (최하위)

추가로 ~/.openclaw/openclaw.json의 skills.load.extraDirs를 통해 추가 스킬 폴더(최저 우선순위)를 설정할 수 있습니다.

에이전트별 vs 공유 스킬

멀티 에이전트 환경에서 각 에이전트는 자체 워크스페이스를 가집니다:

에이전트별 스킬은 해당 에이전트 전용 <workspace>/skills에 있습니다.
공유 스킬은 ~/.openclaw/skills(관리/로컬)에 있으며 동일 머신의 모든 에이전트에게 표시됩니다.
공유 폴더는 여러 에이전트가 사용할 공통 스킬 팩을 위해 skills.load.extraDirs(최저 우선순위)를 통해서도 추가할 수 있습니다.

같은 스킬 이름이 여러 곳에 있으면 일반적인 우선순위가 적용됩니다: 워크스페이스 > 관리/로컬 > 번들.

플러그인 + 스킬

플러그인은 openclaw.plugin.json에서 skills 디렉터리를 나열하여 자체 스킬을 제공할 수 있습니다(플러그인 루트 기준 상대 경로). 플러그인 스킬은 플러그인이 활성화되면 로드되며 일반적인 스킬 우선순위 규칙에 참여합니다. metadata.openclaw.requires.config를 통해 플러그인의 설정 항목으로 게이팅할 수 있습니다. 검색/설정은 플러그인을, 스킬이 가르치는 도구 체계는 도구를 참고하세요.

ClawHub (설치 + 동기화)

ClawHub는 OpenClaw의 공개 스킬 레지스트리입니다. https://clawhub.com에서 탐색하세요. 스킬을 검색, 설치, 업데이트, 백업하는 데 사용합니다. 전체 가이드: ClawHub.

일반적인 흐름:

워크스페이스에 스킬 설치:
- clawhub install <skill-slug>
설치된 모든 스킬 업데이트:
- clawhub update --all
동기화 (스캔 + 업데이트 게시):
- clawhub sync --all

기본적으로 clawhub는 현재 작업 디렉터리의 ./skills에 설치합니다(또는 설정된 OpenClaw 워크스페이스로 폴백). OpenClaw는 다음 세션에서 이를 <workspace>/skills로 인식합니다.

보안 참고

서드파티 스킬은 신뢰할 수 없는 코드로 취급하세요. 활성화하기 전에 읽어보세요.
신뢰할 수 없는 입력과 위험한 도구에는 샌드박스 실행을 선호하세요. 샌드박스를 참고하세요.
워크스페이스 및 추가 디렉터리 스킬 탐색은 해석된 실제 경로가 설정된 루트 내에 있는 스킬 루트와 SKILL.md 파일만 허용합니다.
skills.entries.*.env와 skills.entries.*.apiKey는 해당 에이전트 턴의 호스트 프로세스에 시크릿을 주입합니다(샌드박스가 아님). 시크릿을 프롬프트와 로그에서 제외하세요.
더 넓은 위협 모델과 체크리스트는 보안을 참고하세요.

형식 (AgentSkills + Pi 호환)

SKILL.md에는 최소한 다음이 포함되어야 합니다:

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

참고:

AgentSkills 사양의 레이아웃/의도를 따릅니다.
임베디드 에이전트가 사용하는 파서는 한 줄 프론트매터 키만 지원합니다.
metadata는 한 줄 JSON 객체여야 합니다.
지침에서 스킬 폴더 경로를 참조하려면 {baseDir}을 사용하세요.
선택적 프론트매터 키:
- homepage — macOS 스킬 UI에서 “웹사이트”로 표시되는 URL (metadata.openclaw.homepage으로도 지원됨).
- user-invocable — true|false (기본값: true). true이면 스킬이 사용자 슬래시 명령으로 노출됩니다.
- disable-model-invocation — true|false (기본값: false). true이면 스킬이 모델 프롬프트에서 제외됩니다(사용자 호출은 여전히 가능).
- command-dispatch — tool (선택 사항). tool로 설정하면 슬래시 명령이 모델을 우회하고 도구로 직접 디스패치됩니다.
- command-tool — command-dispatch: tool 설정 시 호출할 도구 이름.
- command-arg-mode — raw (기본값). 도구 디스패치의 경우 원시 인수 문자열을 도구에 전달합니다(코어 파싱 없음).
  
  도구는 다음 매개변수로 호출됩니다: { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

게이팅 (로드 시점 필터)

OpenClaw는 metadata(한 줄 JSON)를 사용하여 로드 시점에 스킬을 필터링합니다:

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

metadata.openclaw 아래 필드:

always: true — 항상 스킬을 포함합니다(다른 게이트 건너뜀).
emoji — macOS 스킬 UI에서 사용하는 선택적 이모지.
homepage — macOS 스킬 UI에서 “웹사이트”로 표시되는 선택적 URL.
os — 선택적 플랫폼 목록(darwin, linux, win32). 설정 시 해당 OS에서만 스킬이 적용됩니다.
requires.bins — 목록; 각각 PATH에 존재해야 합니다.
requires.anyBins — 목록; 하나 이상이 PATH에 존재해야 합니다.
requires.env — 목록; 환경 변수가 존재하거나 설정에서 제공되어야 합니다.
requires.config — 참(truthy)이어야 하는 openclaw.json 경로 목록.
primaryEnv — skills.entries.<name>.apiKey와 연결된 환경 변수 이름.
install — macOS 스킬 UI에서 사용하는 선택적 설치 사양 배열(brew/node/go/uv/download).

샌드박스 참고:

requires.bins는 스킬 로드 시점에 호스트에서 확인됩니다.
에이전트가 샌드박스된 경우, 바이너리가 컨테이너 내부에도 존재해야 합니다. agents.defaults.sandbox.docker.setupCommand(또는 사용자 정의 이미지)로 설치하세요. setupCommand는 컨테이너 생성 후 한 번 실행됩니다. 패키지 설치에는 네트워크 이그레스, 쓰기 가능한 루트 FS, 샌드박스 내 root 사용자가 필요합니다. 예시: summarize 스킬(skills/summarize/SKILL.md)은 샌드박스 컨테이너에서 실행하려면 summarize CLI가 필요합니다.

설치 프로그램 예시:

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

참고:

여러 설치 프로그램이 나열된 경우, 게이트웨이는 단일 선호 옵션을 선택합니다(가능하면 brew, 그렇지 않으면 node).
모든 설치 프로그램이 download인 경우, OpenClaw는 사용 가능한 아티팩트를 볼 수 있도록 각 항목을 나열합니다.
설치 사양에 os: ["darwin"|"linux"|"win32"]를 포함하여 플랫폼별로 필터링할 수 있습니다.
Node 설치는 openclaw.json의 skills.install.nodeManager를 따릅니다(기본값: npm; 옵션: npm/pnpm/yarn/bun). 스킬 설치에만 영향을 미칩니다. 게이트웨이 런타임에는 여전히 Node를 사용해야 합니다 (WhatsApp/Telegram에는 Bun 비권장).
Go 설치: go가 없고 brew가 있으면, 게이트웨이가 먼저 Homebrew를 통해 Go를 설치하고 가능하면 GOBIN을 Homebrew의 bin으로 설정합니다.
Download 설치: url(필수), archive(tar.gz | tar.bz2 | zip), extract(기본값: 아카이브 감지 시 자동), stripComponents, targetDir(기본값: ~/.openclaw/tools/<skillKey>).

metadata.openclaw가 없으면 스킬은 항상 적용 가능합니다(설정에서 비활성화되거나 번들 스킬에 대해 skills.allowBundled에 의해 차단되지 않는 한).

설정 재정의 (`~/.openclaw/openclaw.json`)

번들/관리 스킬은 토글하거나 환경 변수 값을 제공할 수 있습니다:

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 또는 평문 문자열
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

참고: 스킬 이름에 하이픈이 포함된 경우 키를 따옴표로 묶으세요(JSON5는 따옴표 키를 허용합니다).

설정 키는 기본적으로 스킬 이름에 매핑됩니다. 스킬이 metadata.openclaw.skillKey를 정의한 경우 skills.entries 아래에서 해당 키를 사용하세요.

규칙:

enabled: false는 번들/설치 스킬이라도 비활성화합니다.
env: 프로세스에 해당 변수가 아직 설정되지 않은 경우에만 주입됩니다.
apiKey: metadata.openclaw.primaryEnv를 선언하는 스킬을 위한 편의 기능. 평문 문자열 또는 SecretRef 객체({ source, provider, id })를 지원합니다.
config: 사용자 정의 스킬별 필드를 위한 선택적 컨테이너; 사용자 정의 키는 여기에 있어야 합니다.
allowBundled: 번들 스킬에 대한 선택적 허용 목록. 설정 시 목록에 포함된 번들 스킬만 적용 가능(관리/워크스페이스 스킬은 영향 없음).

환경 주입 (에이전트 실행별)

에이전트 실행이 시작되면 OpenClaw는:

스킬 메타데이터를 읽습니다.
skills.entries.<key>.env 또는 skills.entries.<key>.apiKey를 process.env에 적용합니다.
적용 가능한 스킬로 시스템 프롬프트를 구성합니다.
실행이 끝나면 원래 환경을 복원합니다.

이는 전역 셸 환경이 아닌 에이전트 실행 범위입니다.

세션 스냅샷 (성능)

OpenClaw는 세션이 시작될 때 적용 가능한 스킬을 스냅샷하고 동일 세션의 후속 턴에서 해당 목록을 재사용합니다. 스킬이나 설정 변경은 다음 새 세션에서 적용됩니다.

스킬은 스킬 감시자가 활성화되거나 새로운 적용 가능한 원격 노드가 나타나면 세션 중간에도 갱신될 수 있습니다(아래 참고). 이를 핫 리로드로 생각하세요: 갱신된 목록은 다음 에이전트 턴에서 반영됩니다.

원격 macOS 노드 (Linux 게이트웨이)

게이트웨이가 Linux에서 실행 중이지만 macOS 노드가 system.run 허용(Exec 승인 보안이 deny가 아님)으로 연결된 경우, OpenClaw는 해당 노드에 필요한 바이너리가 있으면 macOS 전용 스킬을 적용 가능으로 취급할 수 있습니다. 에이전트는 nodes 도구(일반적으로 nodes.run)를 통해 이러한 스킬을 실행해야 합니다.

이는 노드가 명령 지원을 보고하고 system.run을 통한 바이너리 탐색에 의존합니다. macOS 노드가 나중에 오프라인이 되더라도 스킬은 계속 표시됩니다. 노드가 다시 연결될 때까지 호출이 실패할 수 있습니다.

스킬 감시자 (자동 갱신)

기본적으로 OpenClaw는 스킬 폴더를 감시하고 SKILL.md 파일이 변경되면 스킬 스냅샷을 갱신합니다. skills.load에서 설정하세요:

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

토큰 영향 (스킬 목록)

스킬이 적용 가능하면, OpenClaw는 시스템 프롬프트에 사용 가능한 스킬의 간결한 XML 목록을 주입합니다(pi-coding-agent의 formatSkillsForPrompt 사용). 비용은 결정적입니다:

기본 오버헤드 (스킬 1개 이상일 때): 195자.
스킬당: 97자 + XML 이스케이프된 <name>, <description>, <location> 값의 길이.

공식 (문자 수):

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

참고:

XML 이스케이프는 & < > " '를 엔티티(&, < 등)로 확장하여 길이를 늘립니다.
토큰 수는 모델 토크나이저에 따라 다릅니다. OpenAI 스타일의 대략적인 추정치는 약 4자/토큰이므로 97자 ≈ 24 토큰/스킬 + 실제 필드 길이입니다.

관리 스킬 생명주기

OpenClaw는 설치(npm 패키지 또는 OpenClaw.app)의 일부로 기본 스킬 세트를 번들 스킬로 제공합니다. ~/.openclaw/skills는 로컬 재정의를 위해 존재합니다(예: 번들 복사본을 변경하지 않고 스킬을 고정/패치). 워크스페이스 스킬은 사용자 소유이며 이름 충돌 시 둘 다 재정의합니다.

설정 참조

전체 설정 스키마는 스킬 설정을 참고하세요.

더 많은 스킬 찾기

https://clawhub.com에서 탐색하세요.