​

Skills (OpenClaw)

​

위치와 우선순위

1. 추가 skill 폴더: skills.load.extraDirs로 구성
2. 번들 skills: 설치물(npm 패키지 또는 OpenClaw.app)에 포함
3. 관리형/로컬 skills: ~/.openclaw/skills
4. 개인 에이전트 skills: ~/.agents/skills
5. 프로젝트 에이전트 skills: <workspace>/.agents/skills
6. 워크스페이스 skills: <workspace>/skills

​

에이전트별 skills vs 공유 skills

• 에이전트별 skills는 해당 에이전트 전용 <workspace>/skills에 있습니다.
• 프로젝트 에이전트 skills는 <workspace>/.agents/skills에 있으며, 일반 워크스페이스 skills/ 폴더보다 먼저 해당 워크스페이스에 적용됩니다.
• 개인 에이전트 skills는 ~/.agents/skills에 있으며, 해당 머신의 여러 워크스페이스에 걸쳐 적용됩니다.
• 공유 skills는 ~/.openclaw/skills(관리형/로컬)에 있으며, 동일한 머신의 모든 에이전트에서 볼 수 있습니다.
• 공유 폴더는 여러 에이전트가 사용하는 공통 skills 팩이 필요할 경우 skills.load.extraDirs를 통해 추가할 수도 있습니다(가장 낮은 우선순위).

​

에이전트 skill 허용 목록

• 위치/우선순위는 같은 이름의 skill 중 어떤 복사본이 우선하는지 결정합니다.
• 에이전트 허용 목록은 보이는 skill 중 에이전트가 실제로 사용할 수 있는 것을 결정합니다.

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // github, weather 상속
      { id: "docs", skills: ["docs-search"] }, // 기본값 대체
      { id: "locked-down", skills: [] }, // skill 없음
    ],
  },
}

• 기본적으로 제한 없는 skills를 원하면 agents.defaults.skills를 생략하세요.
• agents.defaults.skills를 상속하려면 agents.list[].skills를 생략하세요.
• skill이 전혀 없게 하려면 agents.list[].skills: []로 설정하세요.
• 비어 있지 않은 agents.list[].skills 목록은 해당 에이전트의 최종 집합이며, 기본값과 병합되지 않습니다.

​

플러그인 + skills

​

ClawHub(설치 + 동기화)

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

​

보안 참고

• 서드파티 skills는 신뢰할 수 없는 코드로 취급하세요. 활성화 전에 읽어보세요.
• 신뢰할 수 없는 입력과 위험한 도구에는 샌드박스 실행을 우선하세요. 샌드박싱을 참고하세요.
• 워크스페이스 및 extra-dir skill 검색은 해석된 realpath가 구성된 루트 안에 머무는 skill 루트와 SKILL.md 파일만 허용합니다.
• Gateway 기반 skill 의존성 설치(skills.install, 온보딩, Skills 설정 UI)는 설치자 메타데이터를 실행하기 전에 내장 위험 코드 스캐너를 실행합니다. critical 결과는 호출자가 명시적으로 위험 재정의를 설정하지 않는 한 기본적으로 차단되며, 의심스러운 결과는 여전히 경고만 합니다.
• openclaw skills install <slug>는 다릅니다. 이것은 ClawHub skill 폴더를 워크스페이스로 다운로드하며 위의 설치자 메타데이터 경로를 사용하지 않습니다.
• skills.entries.*.env와 skills.entries.*.apiKey는 해당 에이전트 턴 동안 호스트 프로세스에 시크릿을 주입합니다 (샌드박스가 아님). 프롬프트와 로그에는 시크릿을 남기지 마세요.
• 더 넓은 위협 모델과 체크리스트는 보안을 참고하세요.

​

형식(AgentSkills + Pi 호환)

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

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

​

게이팅(로드 시 필터)

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

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

• requires.bins는 skill 로드 시점에 호스트에서 검사됩니다.
• 에이전트가 샌드박스된 경우, 바이너리는 컨테이너 내부에도 존재해야 합니다. agents.defaults.sandbox.docker.setupCommand(또는 커스텀 이미지)로 이를 설치하세요. setupCommand는 컨테이너 생성 후 한 번 실행됩니다. 패키지 설치에는 네트워크 egress, 쓰기 가능한 루트 FS, 샌드박스 내 루트 사용자도 필요합니다. 예: summarize skill(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). 이것은 skill 설치에만 영향을 줍니다. Gateway 런타임은 여전히 Node를 사용해야 하며 (WhatsApp/Telegram에는 Bun을 권장하지 않음).
• Gateway 기반 설치자 선택은 node 전용이 아니라 선호도 기반입니다. 설치 명세에 여러 종류가 섞여 있을 때 OpenClaw는 skills.install.preferBrew가 활성화되어 있고 brew가 존재하면 Homebrew를 우선하고, 그다음 uv, 구성된 node manager, 이후 go나 download 같은 다른 폴백을 선택합니다.
• 모든 설치 명세가 download이면 OpenClaw는 하나의 선호 설치자로 축소하지 않고 모든 다운로드 옵션을 노출합니다.
• Go 설치: go가 없고 brew를 사용할 수 있으면 gateway는 먼저 Homebrew로 Go를 설치하고, 가능하면 GOBIN을 Homebrew의 bin으로 설정합니다.
• 다운로드 설치: url(필수), archive (tar.gz | tar.bz2 | zip), extract (기본값: 아카이브 감지 시 자동), stripComponents, targetDir (기본값: ~/.openclaw/tools/<skillKey>).

​

config 재정의(~/.openclaw/openclaw.json)

{
  skills: {
    entries: {
      "image-lab": {
        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 },
    },
  },
}

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

​

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

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

​

세션 스냅샷(성능)

​

원격 macOS 노드(Linux gateway)

​

Skills watcher(자동 새로고침)

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

​

토큰 영향(skills 목록)

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

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

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

​

관리형 skills 수명주기

​

config 참고

​

더 많은 skills를 찾고 있나요?

​

관련 문서

• Skills 만들기 — 커스텀 skills 빌드하기
• Skills Config — skill 구성 참고
• 슬래시 명령 — 사용 가능한 모든 슬래시 명령
• 플러그인 — 플러그인 시스템 개요