​

스킬 (OpenClaw)

​

위치와 우선순위

1. 번들 스킬: 설치물(npm 패키지 또는 OpenClaw.app)에 포함되어 제공됨
2. 관리형/로컬 스킬: ~/.openclaw/skills
3. 워크스페이스 스킬: <workspace>/skills

​

에이전트별 스킬과 공유 스킬

• 에이전트별 스킬은 해당 에이전트 전용 <workspace>/skills에 있습니다.
• 공유 스킬은 ~/.openclaw/skills(관리형/로컬)에 있으며 같은 머신의 모든 에이전트에게 보입니다.
• 공유 폴더도 skills.load.extraDirs(가장 낮은 우선순위)를 통해 추가할 수 있으며, 여러 에이전트가 공통으로 쓰는 스킬 팩을 구성할 때 유용합니다.

​

플러그인 + 스킬

​

ClawHub (설치 + 동기화)

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

​

보안 참고 사항

• 서드파티 스킬은 신뢰할 수 없는 코드로 취급하세요. 활성화하기 전에 읽어보세요.
• 신뢰할 수 없는 입력과 위험한 도구에는 샌드박스 실행을 우선하세요. Sandboxing을 참고하세요.
• 워크스페이스 및 extra-dir 스킬 검색은 해석된 realpath가 설정된 루트 내부에 머무르는 skill root와 SKILL.md 파일만 허용합니다.
• skills.entries.*.env와 skills.entries.*.apiKey는 해당 에이전트 턴 동안 비밀 값을 호스트 프로세스에 주입합니다(샌드박스가 아님). 비밀 값이 프롬프트나 로그에 들어가지 않도록 하세요.
• 더 넓은 범위의 위협 모델과 체크리스트는 Security를 참고하세요.

​

형식 (AgentSkills + Pi 호환)

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

• 레이아웃/의도는 AgentSkills 사양을 따릅니다.
• 임베디드 에이전트가 사용하는 파서는 frontmatter 키에서 한 줄짜리 값만 지원합니다.
• metadata는 한 줄짜리 JSON 객체여야 합니다.
• 지침 안에서 {baseDir}를 사용하면 스킬 폴더 경로를 참조할 수 있습니다.
• 선택적 frontmatter 키:
  • homepage — macOS Skills UI에서 “Website”로 표시되는 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(기본값). 도구 디스패치 시 원시 인자 문자열을 도구에 그대로 전달합니다(core 파싱 없음). 이 경우 도구는 다음 params로 호출됩니다. { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

​

게이팅(로드 시 필터)

---
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",
      },
  }
---

• always: true — 항상 스킬을 포함합니다(다른 게이트는 건너뜀).
• emoji — macOS Skills UI에서 사용하는 선택적 이모지.
• homepage — macOS Skills UI에서 “Website”로 표시되는 선택적 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 Skills UI에서 사용하는 설치 스펙 배열(brew/node/go/uv/download), 선택 사항.

• requires.bins는 스킬 로드 시점에 호스트에서 검사됩니다.
• 에이전트가 샌드박스 안에서 실행된다면, 해당 바이너리는 컨테이너 내부에도 있어야 합니다. agents.defaults.sandbox.docker.setupCommand(또는 커스텀 이미지)로 설치하세요. setupCommand는 컨테이너가 생성된 뒤 한 번 실행됩니다. 패키지 설치에는 네트워크 egress, 쓰기 가능한 루트 파일시스템, 그리고 샌드박스 안의 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)",
            },
          ],
      },
  }
---

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

​

설정 오버라이드 (~/.openclaw/openclaw.json)

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• enabled: false는 번들/설치 여부와 무관하게 스킬을 비활성화합니다.
• env: 해당 변수가 프로세스에 아직 설정되지 않았을 때에만 주입됩니다.
• apiKey: metadata.openclaw.primaryEnv를 선언한 스킬을 위한 편의 기능입니다. 평문 문자열 또는 SecretRef 객체({ source, provider, id })를 지원합니다.
• config: 스킬별 커스텀 필드를 담는 선택적 bag입니다. 사용자 정의 키는 반드시 여기에 있어야 합니다.
• allowBundled: 번들 스킬에만 적용되는 선택적 허용 목록입니다. 설정하면 목록에 있는 번들 스킬만 사용할 수 있습니다(관리형/워크스페이스 스킬은 영향 없음).

​

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

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

​

세션 스냅샷(성능)

​

원격 macOS 노드(Linux gateway)

​

스킬 watcher(자동 새로고침)

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

​

토큰 영향(스킬 목록)

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

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

• XML 이스케이프는 & < > " '를 엔터티(&, < 등)로 확장하므로 길이가 늘어납니다.
• 토큰 수는 모델 토크나이저에 따라 달라집니다. OpenAI 스타일로 대략 추정하면 약 4자/토큰이므로 97자 ≈ 24토큰에 실제 필드 길이가 추가됩니다.

​

관리형 스킬 수명주기

​

설정 참조

​

더 많은 스킬을 찾고 있나요?