Skills 로딩과 실행
기준일: 2026-07-13 난이도: 중급 공식 기준: Skills, Skills configuration
OpenClaw는 Skill 파일이 존재한다고 무조건 agent에 노출하지 않습니다. source precedence, agent allowlist, OS·binary·env·config requirement, disabled 상태를 적용해 eligible Skill 목록을 만듭니다.
핵심 개념
- 설정된 root에서
SKILL.md를 발견합니다. - 같은 이름이면 source precedence로 하나를 선택합니다.
metadata.openclaw.requires와 config override를 평가합니다.- agent allowlist를 적용합니다.
- eligible Skill의 name, description, location을 prompt catalog에 넣습니다.
- 새 세션에서 snapshot을 만들고 watcher가 변경을 감지하면 다음 turn에 갱신합니다.
skills.builtin: ["file-read", ...] 같은 임의 catalog는 현재 공식 config 모델이 아닙니다. bundled Skill 제어는 skills.allowBundled, 개별 설정은 skills.entries.*, agent visibility는 agents.defaults.skills와 agents.list[].skills를 사용합니다.
선택 기준
- Skill이 보이지 않으면 설치를 반복하기 전에
skills check로 eligibility를 확인합니다. - allowlist가 비어 있는 배열이면 해당 agent에 Skill을 노출하지 않습니다.
skills.entries.*.env와apiKey는 host agent turn에만 적용되며 sandbox 내부 secret 주입으로 간주하면 안 됩니다.- prompt 비용을 줄이려면 name과 description을 짧고 구체적으로 씁니다.
실습
openclaw skills list --verbose
openclaw skills check --json
openclaw config get agents.defaults.skills --json
openclaw config get skills.entries --json
결과에서 missing binary, environment, disabled entry, allowlist 제외를 구분합니다.
도구에 입력할 프롬프트
이 Skill이 OpenClaw에 보이지 않는 원인을 조사해줘.
source precedence, SKILL.md name, agent allowlist,
metadata.openclaw.requires, skills.entries override를 순서대로 확인하고
설치 재시도 전에 읽기 전용 진단 결과를 보여줘.
체크리스트
-
skills check --json으로 eligibility를 확인했다. - 같은 이름의 상위 precedence Skill이 있는지 확인했다.
- agent allowlist가 교체인지 병합인지 확인했다.
- host env와 sandbox env를 구분했다.
- 새 세션 또는 watcher 갱신 시점을 고려했다.
다음 단계
- Skills 시스템 개요에서 source와 trust 경계를 확인합니다.
- Skill 만들기에서 frontmatter를 작성합니다.
- 보안에서 sandbox와 exec policy를 점검합니다.