Skills
Skills
Skills는 에이전트가 도구를 사용하는 방법과 시점을 알려 주는 마크다운 지침 파일입니다. 각 Skill은 YAML frontmatter와 마크다운 본문이 포함된 SKILL.md 파일을 담은 디렉터리에 있습니다. OpenClaw는 번들 Skills와 로컬 재정의를 로드하고, 로드 시점에 환경, 구성, 바이너리 존재 여부를 기준으로 필터링합니다.
사용자 지정 Skill을 처음부터 빌드하고 테스트합니다.
에이전트가 초안으로 작성한 Skill 제안을 검토하고 승인합니다.
전체 skills.* 구성 스키마와 에이전트 허용 목록입니다.
커뮤니티 Skills를 탐색하고 설치합니다.
로드 순서
OpenClaw는 다음 소스에서 로드하며, 가장 높은 우선순위가 먼저 적용됩니다. 동일한 Skill 이름이 여러 위치에 나타나면 가장 높은 소스가 우선합니다.
| 우선순위 | 소스 | 경로 |
|---|---|---|
| 1 — 가장 높음 | 워크스페이스 Skills | <workspace>/skills |
| 2 | 프로젝트 에이전트 Skills | <workspace>/.agents/skills |
| 3 | 개인 에이전트 Skills | ~/.agents/skills |
| 4 | 관리형 / 로컬 Skills | ~/.openclaw/skills |
| 5 | 번들 Skills | 설치와 함께 제공됨 |
| 6 — 가장 낮음 | 추가 디렉터리 | skills.load.extraDirs + Plugin Skills |
Skill 루트는 그룹화된 레이아웃을 지원합니다. 구성된 루트 아래 어디에서든 SKILL.md가 나타나면 OpenClaw가 Skill을 발견합니다.
<workspace>/skills/research/SKILL.md ✓ found as "research"<workspace>/skills/personal/research/SKILL.md ✓ also found as "research"폴더 경로는 정리 용도로만 사용됩니다. Skill의 이름, 슬래시 명령, 허용 목록 키는 모두 name frontmatter 필드에서 가져옵니다(name이 없으면 디렉터리 이름에서 가져옵니다).
에이전트별 Skills와 공유 Skills
다중 에이전트 설정에서는 각 에이전트가 자체 워크스페이스를 가집니다. 원하는 표시 범위와 일치하는 경로를 사용하세요.
| 범위 | 경로 | 표시 대상 |
|---|---|---|
| 에이전트별 | <workspace>/skills |
해당 에이전트만 |
| 프로젝트 에이전트 | <workspace>/.agents/skills |
해당 워크스페이스의 에이전트만 |
| 개인 에이전트 | ~/.agents/skills |
이 머신의 모든 에이전트 |
| 공유 관리형 | ~/.openclaw/skills |
이 머신의 모든 에이전트 |
| 추가 디렉터리 | skills.load.extraDirs |
이 머신의 모든 에이전트 |
에이전트 허용 목록
Skill 위치(우선순위)와 Skill 표시 범위(어떤 에이전트가 사용할 수 있는지)는 별도의 제어 항목입니다. 허용 목록을 사용해 로드 위치와 관계없이 에이전트가 볼 수 있는 Skills를 제한하세요.
{ agents: { defaults: { skills: ["github", "weather"], // shared baseline }, list: [ { id: "writer" }, // inherits github, weather { id: "docs", skills: ["docs-search"] }, // replaces defaults entirely { id: "locked-down", skills: [] }, // no skills ], },}허용 목록 규칙
- 기본적으로 모든 Skills를 제한하지 않으려면
agents.defaults.skills를 생략하세요. agents.defaults.skills를 상속하려면agents.list[].skills를 생략하세요.- 해당 에이전트에 어떤 Skills도 노출하지 않으려면
agents.list[].skills: []로 설정하세요. - 비어 있지 않은
agents.list[].skills목록은 최종 집합입니다. 기본값과 병합되지 않습니다. - 유효한 허용 목록은 프롬프트 빌드, 슬래시 명령 발견, 샌드박스 동기화, Skill 스냅샷 전반에 적용됩니다.
- 이는 호스트 셸 권한 부여 경계가 아닙니다. 동일한 에이전트가
exec를 사용할 수 있다면, 샌드박싱, OS 사용자 격리, exec 거부/허용 목록, 리소스별 자격 증명으로 해당 셸을 별도로 제한하세요.
Plugin과 Skills
Plugin은 openclaw.plugin.json에 skills 디렉터리를 나열해 자체 Skills를 제공할 수 있습니다(경로는 Plugin 루트를 기준으로 상대 경로). Plugin Skills는 Plugin이 활성화될 때 로드됩니다. 예를 들어 브라우저 Plugin은 다단계 브라우저 제어를 위한 browser-automation Skill을 제공합니다.
Plugin Skill 디렉터리는 skills.load.extraDirs와 동일한 낮은 우선순위 수준에서 병합되므로, 같은 이름의 번들, 관리형, 에이전트 또는 워크스페이스 Skill이 이를 재정의합니다. Plugin의 구성 항목에서 metadata.openclaw.requires.config를 통해 게이트하세요.
전체 Plugin 시스템은 Plugin 및 도구를 참조하세요.
Skill 워크숍
Skill 워크숍은 에이전트와 활성 Skill 파일 사이의 제안 대기열입니다. 에이전트가 재사용 가능한 작업을 발견하면 SKILL.md에 직접 쓰는 대신 제안 초안을 작성합니다. 변경 사항이 적용되기 전에 검토하고 승인합니다.
openclaw skills workshop listopenclaw skills workshop inspect <proposal-id>openclaw skills workshop apply <proposal-id>전체 수명 주기, CLI 참조, 구성은 스킬 워크숍을 참조하세요.
ClawHub에서 설치
ClawHub는 공개 스킬 레지스트리입니다. 설치와
업데이트에는 openclaw skills 명령을 사용하고, 게시와 동기화에는
clawhub CLI를 사용하세요.
| 작업 | 명령 |
|---|---|
| 작업공간에 스킬 설치 | openclaw skills install @owner/<slug> |
| Git 저장소에서 설치 | openclaw skills install git:owner/repo@ref |
| 로컬 스킬 디렉터리 설치 | openclaw skills install ./path/to/skill --as my-tool |
| 모든 로컬 에이전트에 설치 | openclaw skills install @owner/<slug> --global |
| 모든 작업공간 스킬 업데이트 | openclaw skills update --all |
| 공유 관리형 스킬 업데이트 | openclaw skills update @owner/<slug> --global |
| 모든 공유 관리형 스킬 업데이트 | openclaw skills update --all --global |
| 스킬의 신뢰 엔벌로프 확인 | openclaw skills verify @owner/<slug> |
| 생성된 스킬 카드 출력 | openclaw skills verify @owner/<slug> --card |
| ClawHub CLI로 게시 / 동기화 | clawhub sync --all |
설치 세부 정보
openclaw skills install은 기본적으로 활성 작업공간의 skills/
디렉터리에 설치합니다. 모든 로컬 에이전트가 볼 수 있는 공유
~/.openclaw/skills 디렉터리에 설치하려면 --global을 추가하세요.
단, 에이전트 허용 목록이 범위를 좁힐 수 있습니다.
Git 및 로컬 설치는 소스 루트에 SKILL.md가 있어야 합니다. 슬러그는
유효한 경우 SKILL.md 프런트매터의 name에서 가져오고, 그렇지 않으면
디렉터리 또는 저장소 이름으로 대체됩니다. 재정의하려면 --as <slug>를
사용하세요. openclaw skills update는 ClawHub 설치만 추적합니다. Git
또는 로컬 소스는 새로 고치려면 다시 설치하세요.
검증 및 보안 검사
openclaw skills verify @owner/<slug>는 ClawHub에 스킬의
clawhub.skill.verify.v1 신뢰 엔벌로프를 요청합니다. 설치된 ClawHub
스킬은 .clawhub/origin.json에 기록된 버전 및 레지스트리를 기준으로
검증됩니다. 기존에 설치된 스킬이나 모호하지 않은 스킬에는 소유자 없는
슬러그도 계속 허용되지만, 소유자 한정 참조는 게시자 모호성을 방지합니다.
ClawHub 스킬 페이지는 설치 전에 최신 보안 검사 상태를 표시하며,
VirusTotal, ClawScan, 정적 분석의 세부 정보 페이지를 제공합니다.
ClawHub가 검증 실패로 표시하면 명령은 0이 아닌 종료 코드로 종료됩니다.
게시자는 ClawHub 대시보드 또는 clawhub skill rescan @owner/<slug>를
통해 오탐을 복구합니다.
비공개 아카이브 설치
ClawHub가 아닌 전달이 필요한 Gateway 클라이언트는
skills.upload.begin, skills.upload.chunk, skills.upload.commit으로
zip 스킬 아카이브를 스테이징한 다음
skills.install({ source: "upload", ... })로 설치할 수 있습니다. 이 경로는
기본적으로 꺼져 있으며 openclaw.json에서
skills.install.allowUploadedArchives: true가 필요합니다. 일반적인
ClawHub 설치에는 이 설정이 필요하지 않습니다.
보안
경로 격리
작업공간, 프로젝트 에이전트, 추가 디렉터리 스킬 검색은
skills.load.allowSymlinkTargets가 대상 루트를 명시적으로 신뢰하지 않는 한,
해석된 실제 경로가 구성된 루트 안에 유지되는 스킬 루트만 허용합니다.
스킬 워크숍은 skills.workshop.allowSymlinkTargetWrites가 활성화된 경우에만
이러한 신뢰된 대상에 씁니다. 관리형 ~/.openclaw/skills와 개인
~/.agents/skills에는 심볼릭 링크된 스킬 폴더가 포함될 수 있지만, 모든
SKILL.md 실제 경로는 여전히 해석된 해당 스킬 디렉터리 안에 있어야 합니다.
운영자 설치 정책
스킬 설치를 계속하기 전에 신뢰할 수 있는 로컬 정책 명령을 실행하려면
security.installPolicy를 구성하세요. 정책은 메타데이터와 스테이징된
소스 경로를 받으며, ClawHub, 업로드, Git, 로컬, 업데이트, 의존성 설치
경로에 적용되고, 명령이 유효한 결정을 반환할 수 없으면 실패 시 차단합니다.
시크릿 주입 범위
skills.entries.*.env와 skills.entries.*.apiKey는 해당 에이전트 턴에
대해서만 호스트 프로세스에 시크릿을 주입하며, 샌드박스에는 주입하지
않습니다. 프롬프트와 로그에 시크릿을 넣지 마세요.
더 넓은 위협 모델과 보안 체크리스트는 보안을 참조하세요.
SKILL.md 형식
모든 스킬은 최소한 프런트매터에 name과 description이 필요합니다.
---name: image-labdescription: Generate or edit images via a provider-backed image workflow--- When the user asks to generate an image, use the `image_generate` tool...선택적 프런트매터 키
homepagestringmacOS Skills UI에서 "웹사이트"로 표시되는 URL입니다.
metadata.openclaw.homepage로도 지원됩니다.
user-invocablebooleandefault: truetrue이면 스킬이 사용자가 호출할 수 있는 슬래시 명령으로 노출됩니다.
disable-model-invocationbooleandefault: falsetrue이면 OpenClaw는 스킬 지침을 에이전트의 일반 프롬프트에 포함하지
않습니다. user-invocable도 true이면 스킬은 계속 슬래시 명령으로 사용할
수 있습니다.
command-dispatch"tool"tool로 설정하면 슬래시 명령이 모델을 우회하고 등록된 도구로 직접
디스패치됩니다.
command-toolstringcommand-dispatch: tool이 설정된 경우 호출할 도구 이름입니다.
command-arg-mode"raw"default: raw도구 디스패치의 경우, 코어 파싱 없이 원시 args 문자열을 도구에
전달합니다. 도구는
{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }를 받습니다.
게이팅
OpenClaw는 로드 시점에 metadata.openclaw(frontmatter의 한 줄
JSON)를 사용하여 Skills를 필터링합니다. metadata.openclaw 블록이 없는 skill은 명시적으로
비활성화되지 않는 한 항상 적격입니다.
---name: image-labdescription: Generate or edit images via a provider-backed image workflowmetadata: { "openclaw": { "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] }, "primaryEnv": "GEMINI_API_KEY", }, }---alwaysbooleantrue이면 항상 해당 skill을 포함하고 다른 모든 게이트를 건너뜁니다.
emojistringmacOS Skills UI에 표시되는 선택적 이모지입니다.
homepagestringmacOS Skills UI에서 "웹사이트"로 표시되는 선택적 URL입니다.
os"darwin" | "linux" | "win32"플랫폼 필터입니다. 설정하면 해당 skill은 나열된 OS에서만 적격입니다.
requires.binsstring[]각 바이너리는 PATH에 존재해야 합니다.
requires.anyBinsstring[]하나 이상의 바이너리가 PATH에 존재해야 합니다.
requires.envstring[]각 env var는 프로세스에 존재하거나 config를 통해 제공되어야 합니다.
requires.configstring[]각 openclaw.json 경로는 참이어야 합니다.
primaryEnvstringskills.entries.<name>.apiKey와 연결된 env var 이름입니다.
installobject[]macOS Skills UI에서 사용하는 선택적 설치 관리자 사양입니다(brew / node / go / uv / download).
설치 관리자 사양
설치 관리자 사양은 macOS Skills UI에 종속성을 설치하는 방법을 알려줍니다.
---name: geminidescription: 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)", }, ], }, }---Installer selection rules
- 여러 설치 관리자가 나열된 경우, gateway는 선호하는 옵션 하나를 선택합니다 (사용 가능하면 brew, 그렇지 않으면 node).
- 모든 설치 관리자가
download이면 OpenClaw는 사용 가능한 모든 아티팩트를 볼 수 있도록 각 항목을 나열합니다. - 사양에는 플랫폼별 필터링을 위해
os: ["darwin"|"linux"|"win32"]를 포함할 수 있습니다. - Node 설치는
openclaw.json의skills.install.nodeManager를 따릅니다 (기본값: npm; 옵션: npm / pnpm / yarn / bun). 이는 skill 설치에만 영향을 줍니다. Gateway 런타임은 여전히 Node여야 합니다. - Gateway 설치 관리자 선호 순서: Homebrew → uv → 구성된 node manager → go → download.
Per-installer details
- Homebrew: OpenClaw는 Homebrew를 자동 설치하거나 brew
formula를 시스템 패키지 명령으로 변환하지 않습니다.
brew가 없는 Linux 컨테이너에서는 brew 전용 설치 관리자가 숨겨집니다. 사용자 지정 이미지를 사용하거나 종속성을 수동으로 설치하세요. - Go: OpenClaw는 자동 skill 설치에 Go 1.21 이상을 요구하며
기존
GOBIN,GOPATH,GOTOOLCHAIN설정을 보존합니다. 구성된 toolchain이 모듈의 필수 Go 버전을 충족할 수 없으면, onboarding은 설치 시도 후 해당 skill을 수동 Go 사전 요구 사항과 함께 그룹화합니다.go가 없고 Homebrew를 사용할 수 있으면 OpenClaw는 먼저 Homebrew를 통해 Go를 설치하고GOBIN을 Homebrew의bin으로 설정합니다. Linux에서는 새로 고친golang-go후보가 최소 버전을 충족할 때 OpenClaw가 대신 root로 또는 암호 없는sudo를 통해apt-get을 사용할 수 있습니다. - Download:
url(필수),archive(tar.gz|tar.bz2|zip),extract(기본값: 아카이브 감지 시 자동),stripComponents,targetDir(기본값:~/.openclaw/tools/<skillKey>).
Sandboxing notes
requires.bins는 skill 로드 시점에 호스트에서 확인됩니다. 에이전트가
sandbox에서 실행되는 경우, 바이너리도 컨테이너 내부에 존재해야 합니다.
agents.defaults.sandbox.docker.setupCommand 또는 사용자 지정
이미지를 통해 설치하세요. setupCommand는 컨테이너 생성 후 한 번 실행되며
네트워크 송신, 쓰기 가능한 root FS, sandbox의 root 사용자가 필요합니다.
Config 재정의
~/.openclaw/openclaw.json의 skills.entries 아래에서 번들 또는 관리형 skills를
토글하고 구성합니다.
{ 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 }, }, },}enabledbooleanfalse는 번들되었거나 설치되었더라도 해당 skill을 비활성화합니다. coding-agent
번들 skill은 옵트인입니다. skills.entries.coding-agent.enabled: true를
설정하고 claude, codex, opencode 또는 지원되는 다른 CLI 중 하나가
설치 및 인증되어 있는지 확인하세요.
apiKeystring | { source, provider, id }metadata.openclaw.primaryEnv를 선언하는 skills를 위한 편의 필드입니다.
평문 문자열 또는 SecretRef 객체를 지원합니다.
env"Record<string,configobjectskill별 사용자 지정 구성 필드를 위한 선택적 bag입니다.
allowBundledstring[]번들 skills에만 적용되는 선택적 허용 목록입니다. 설정하면 목록에 있는 번들 skills만 적격입니다. 관리형 및 workspace skills에는 영향을 주지 않습니다.
환경 주입
에이전트 실행이 시작되면 OpenClaw는 다음을 수행합니다.
Reads skill metadata
OpenClaw는 게이팅 규칙, 허용 목록, config 재정의를 적용하여 에이전트의 유효한 skill 목록을 확인합니다.
Injects env and API keys
skills.entries.<key>.env와 skills.entries.<key>.apiKey가 실행 기간 동안
process.env에 적용됩니다.
Builds the system prompt
적격 skills는 compact XML 블록으로 컴파일되어 system prompt에 주입됩니다.
Restores the environment
실행이 끝나면 원래 환경이 복원됩니다.
번들 claude-cli backend의 경우, OpenClaw는 동일한 적격 skill snapshot을
임시 Claude Code Plugin으로도 구체화하고 --plugin-dir을 통해 전달합니다.
다른 CLI backend는 prompt catalog만 사용합니다.
Snapshots 및 새로 고침
OpenClaw는 세션이 시작될 때 적격 skills의 snapshot을 만들고, 세션의 모든 후속 턴에서 해당 목록을 재사용합니다. skills 또는 config 변경 사항은 다음 새 세션부터 적용됩니다.
세션 중 skills는 두 가지 경우에 새로 고쳐집니다.
- skills watcher가
SKILL.md변경을 감지합니다. - 새로운 적격 remote node가 연결됩니다.
새로 고친 목록은 다음 에이전트 턴에서 반영됩니다. 유효한 에이전트 허용 목록이 변경되면, OpenClaw는 표시되는 skills가 일치하도록 snapshot을 새로 고칩니다.
Skills watcher
기본적으로 OpenClaw는 skill 폴더를 감시하고 SKILL.md 파일이 변경되면
snapshot을 갱신합니다. skills.load 아래에서 구성합니다.
{ skills: { load: { extraDirs: ["~/Projects/agent-scripts/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], watch: true, watchDebounceMs: 250, }, },}skill root symlink가 구성된 root 밖을 가리키는 의도적인 symlink 레이아웃에는
allowSymlinkTargets를 사용하세요. 예:
<workspace>/skills/manager -> ~/Projects/manager/skills.
Skill Workshop도 신뢰할 수 있는 이러한 symlink 경로를 통해 제안을 적용해야 할 때만
skills.workshop.allowSymlinkTargetWrites를 활성화하세요.
Remote macOS nodes (Linux gateway)
Gateway가 Linux에서 실행되지만 macOS node가 system.run 허용 상태로
연결되어 있는 경우, 필수 바이너리가 해당 node에 있으면 OpenClaw는 macOS 전용
skills를 적격으로 처리할 수 있습니다. 에이전트는 host=node와 함께 exec 도구를
통해 해당 skills를 실행해야 합니다.
오프라인 node는 remote 전용 skills를 표시하지 않습니다. node가 bin probe에 응답하지 않으면 OpenClaw는 캐시된 bin 일치 항목을 지웁니다.
토큰 영향
skills가 적격이면 OpenClaw는 compact XML 블록을 system prompt에 주입합니다. 비용은 결정적입니다.
total = 195 + Σ (97 + len(name) + len(description) + len(filepath))- 기본 오버헤드(skill이 1개 이상일 때만): 약 195자
- skill당: 약 97자 +
name,description,location필드 길이 - XML 이스케이프는
& < > " '를 엔터티로 확장하여, 발생할 때마다 몇 글자를 추가합니다 - 약 4자/token 기준으로, 97자는 필드 길이를 제외하고 skill당 약 24 tokens입니다
prompt 오버헤드를 최소화하려면 descriptions를 짧고 설명적으로 유지하세요.
