OpenClaw 스킬은 무엇을 바꾸나｜에이전트에게 도구 사용법을 알려 주는 파일의 우선순위

OpenClaw에서 말하는 ‘스킬’은 새 모델을 설치하는 버튼이라기보다, 에이전트가 특정 도구를 언제, 어떤 순서로, 어떤 주의사항과 함께 써야 하는지 적어 둔 안내 묶음에 가깝습니다. 반복하는 작업의 절차를 매번 길게 설명하고 싶지 않을 때 특히 유용합니다.

다만 스킬을 많이 넣는다고 에이전트가 모든 권한을 얻는 것은 아닙니다. 공식 문서는 스킬의 위치, 사용 가능 조건, 에이전트 허용 목록을 따로 설명합니다. 이 글은 그 차이를 처음 설정하는 사람이 헷갈리지 않도록 정리한 것입니다.

스킬의 최소 단위는 SKILL.md입니다

기본 단위는 폴더 하나와 그 안의 SKILL.md 파일입니다. 파일 앞부분에는 이름과 필요한 조건을 적고, 본문에는 작업 절차·주의사항·참고 자료를 적습니다. 예를 들어 게시 전 링크 점검처럼 반복하는 작업의 순서와 중단해야 할 상황을 문서로 남길 수 있습니다.

중요한 점은 이것이 비밀번호나 권한을 담아 두는 장소가 아니라는 것입니다. 스킬은 지침을 제공할 뿐, 실제 도구 접근과 비밀값 처리는 각 도구와 Gateway 설정의 통제를 계속 받습니다.

같은 이름이면 어디에 둔 파일이 먼저 적용될까

공식 문서의 로딩 순서는 대략 작업공간 → 프로젝트 에이전트 → 개인 에이전트 → 관리형/로컬 → 번들 → 추가 디렉터리입니다. 같은 이름의 스킬이 여러 곳에 있다면 앞선 위치가 우선합니다.

특정 프로젝트에서만 다른 절차가 필요할 때는 작업공간 또는 프로젝트 쪽에 두는 편이 이해하기 쉽습니다. 여러 작업에서 공통으로 쓰되 모두에게 공개할 필요가 없는 절차는 개인 라이브러리 범위를 검토할 수 있습니다. 파일을 복사해 두기 전에 어느 범위에 적용할지부터 정하면 이름 충돌을 줄일 수 있습니다.

‘보인다’와 ‘실행할 수 있다’는 다릅니다

스킬 위치의 우선순위와 에이전트 허용 목록은 별개입니다. 관리자 설정에서 특정 에이전트가 사용할 수 있는 스킬을 제한할 수 있고, 스킬이 요구하는 운영체제·실행 파일·설정 조건도 충족되어야 합니다. 안내 문서가 보인다고 해서 새 셸 권한이나 외부 서비스 권한이 생기는 것은 아닙니다.

공유 Gateway라면 이 구분이 더 중요합니다. 공식 문서는 개인 스킬 라이브러리의 소유와 공유를 다루지만, 공유한 스킬도 같은 신뢰 경계 안의 입력일 뿐 비밀 저장소나 격리 장치가 아니라고 설명합니다. 민감한 값은 스킬 본문에 적지 않는 편이 안전합니다.

처음 만들 때는 작은 반복 작업부터

1. 매번 같은 순서로 하는 작업 하나를 고릅니다.
2. 성공 조건과 멈춰야 할 조건을 짧게 적습니다.
3. 개인용·프로젝트용·공유용 중 적용 범위를 정합니다.
4. 필요한 도구와 실행 환경이 실제로 허용되어 있는지 확인합니다.
5. 공유 전에는 안내문에 계정 정보나 토큰이 없는지 다시 확인합니다.

이렇게 두면 스킬은 기능을 무작정 늘리는 파일보다, 반복 업무의 판단 기준을 보존하는 작은 작업 매뉴얼에 가까워집니다.

정리

OpenClaw 스킬은 에이전트의 도구 사용법을 구조화하는 문서 묶음입니다. 우선순위는 위치가, 실제 사용 가능 여부는 허용 목록과 환경 조건이 결정합니다. 먼저 좁은 범위의 반복 작업에 적용하고, 공유와 권한의 차이를 분명히 하는 것이 좋습니다.

OpenClaw의 기본 구조가 궁금하다면 OpenClaw란 무엇인가 글도 함께 볼 수 있습니다.

---

이 글은 OpenClaw 공식 문서 Skills와 설치본의 docs/tools/skills.md를 바탕으로 한국어 독자가 설정 범위를 이해하기 쉽게 풀어 쓴 해설입니다. 개인 사용·설치·보안 효과를 경험한 것처럼 주장하지 않습니다.