OpenClaw 사용자 정의 스킬 개발 실전: 이미지 처리 Skill을 처음부터 만드는 완벽 가이드

휴대전화에서 내보낸 사진이 127장이나 있었고, 사진마다 용량이 5MB를 넘었습니다. 처음에는 OpenClaw에 일괄 압축을 맡기려고 했지만, 직접 복사해 붙여 넣고 실행해야 하는 ImageMagick 명령어만 잔뜩 돌아왔습니다. 이 과정을 OpenClaw가 바로 ‘기억’하게 만들어 다음부터는 ‘이미지 압축’이라고만 해도 알아서 처리하게 할 수 있다면 어떨까요? 바로 이런 상황에서 사용자 정의 스킬이 필요합니다.

나중에야 OpenClaw가 이미 이런 요구를 고려해 두었다는 사실을 알았습니다. 사용자 정의 Skill(스킬)을 만들면 나만의 작업 흐름을 OpenClaw에 가르칠 수 있습니다. iPhone에 App을 설치하듯 한 번 설정해 두면 계속 활용할 수 있습니다.

이 글에서는 완성된 이미지 처리 스킬을 사례로 삼아 처음부터 전체 개발 과정을 따라가 봅니다.

저비용 ‘AI 에이전트 키우기’ 가이드: ArkClaw로 AI Agent를 누구나 쉽게

최근 큰 인기를 끄는 OpenClaw는 유용하지만 설정 과정이 너무 복잡하게 느껴질 수 있습니다. ByteDance Volcano Engine에서 출시한 ArkClaw는 진입 장벽을 크게 낮췄습니다. 서버나 Token 설정을 씨름할 필요 없이 클릭 한 번으로 24시간 온라인 상태를 유지하며 브라우저를 제어하고, 스크립트를 실행하고, 캘린더를 관리하는 ‘AI 일꾼’을 이용할 수 있습니다.

무엇보다 가격이 저렴합니다. 월 이용료는 9.9위안이며, 제 초대 코드 ZLKUK54M을 사용해 여기에서 가입하면 8.9위안에 이용할 수 있습니다. 프로그래머라면 Coding Plan Pro에 가입해 무료로 사용할 수도 있습니다.

Skill의 본질 이해하기(5분이면 충분합니다)

Skill이란 정확히 무엇인가요?

처음 ‘Skill’이라는 단어를 봤을 때는 여러 기술 용어가 떠올랐습니다. 플러그인일까요? 확장 기능일까요? 미들웨어일까요? 어느 것도 완전히 들어맞지는 않았습니다.

사실 이렇게 이해하면 됩니다. Skill은 OpenClaw에 설치하는 ‘전용 App’입니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

OpenClaw의 Skill도 같은 원리입니다. 기본 기능으로 일반적인 작업의 80%를 처리할 수 있지만, 나머지 20%에 해당하는 고유한 요구 사항, 예를 들어 회사만의 이미지 처리 과정이나 개인적인 파일 이름 규칙은 직접 ‘App을 설치’해 해결해야 합니다.

Skill은 무엇으로 구성되나요?

완성된 Skill의 구성은 매우 단순하며 세 부분뿐입니다.

1. SKILL.md(필수): OpenClaw에 이 스킬의 기능과 호출 시점을 알려 주는 설정 파일
2. scripts/ 디렉터리(선택): 실제로 실행할 Python, Bash 등의 스크립트 코드
3. references/ 디렉터리(선택): 지원 파일 형식 목록과 같은 보충 설명 문서

이 글에서 만들 이미지 처리 스킬을 예로 들면 디렉터리 구조는 다음과 같습니다.

~/.openclaw/skills/image-processor/
├── SKILL.md              # 핵심 설정 파일
├── scripts/
│   └── compress.py       # 이미지 압축 스크립트
└── references/
    └── formats.md        # 지원 형식 설명

사용자 정의 Skill이 필요한 이유

사용자 정의 Skill의 가치는 바로 여기에 있습니다. 반복 작업을 정형화해 한 번만 설정하고 계속 활용할 수 있습니다.

Skill의 작동 원리(Progressive Disclosure)

이 메커니즘은 상당히 효율적입니다. OpenClaw는 처음부터 모든 Skill의 상세 설명을 메모리에 불러오지 않습니다. 그렇게 하면 token을 너무 많이 소비하기 때문입니다. 대신 세 단계로 처리합니다.

1. 첫 번째 계층(Frontmatter): 스킬의 이름과 짧은 설명만 확인해 ‘이 작업에 이 스킬이 필요한가?’를 판단합니다.
2. 두 번째 계층(Body): 필요하다고 판단되면 전체 사용 설명을 불러옵니다.
3. 세 번째 계층(Scripts): 실제 실행 단계에 이르러서야 스크립트 파일을 호출합니다.

개인용 스킬과 프로젝트용 스킬

• 개인용: ~/.openclaw/skills/스킬명/에 두며 모든 프로젝트에서 사용할 수 있습니다.
• 프로젝트용: 프로젝트 루트 디렉터리/.openclaw/skills/스킬명/에 두며 해당 프로젝트에서만 작동합니다.

먼저 개인용으로 만들어 충분히 사용해 본 뒤 프로젝트 단위로 분리할 필요가 있는지 판단하는 방식을 권합니다.

이미지 처리 Skill을 만드는 전체 과정

1단계: 디렉터리 구조 만들기

먼저 적절한 위치에 디렉터리를 만듭니다. 모든 프로젝트에서 이 스킬을 사용하고 싶다면 개인 디렉터리에 배치합니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

mkdir -p ~/.openclaw/skills/image-processor
cd ~/.openclaw/skills/image-processor
mkdir scripts references

2단계: SKILL.md 설정 파일 작성하기

이 파일은 스킬 전체의 핵심입니다. SKILL.md 파일을 만들고 다음 내용을 입력합니다.

---
name: image-processor
description: 이미지 일괄 처리 도구. 사용자가 이미지 압축, 형식 변환, 크기 조절 또는 워터마크 추가를 요청할 때 사용합니다. JPG, PNG, WebP 형식을 지원합니다.
tools: Bash, Read, Write
---

이 세 줄의 YAML이 핵심입니다.

• name: 스킬의 고유 식별자이며 사용자는 /image-processor로 직접 호출할 수 있습니다.
• description: OpenClaw가 이 스킬을 언제 자동으로 호출할지 직접 결정하는 설명입니다.
• tools: 필요한 권한을 선언합니다.

3단계: Python 스크립트 개발하기

실제 작업을 수행할 scripts/compress.py를 만듭니다. 글 앞부분에서 설명한 기능을 기준으로 보면 이 스크립트는 압축, 형식 변환, 크기 조절을 지원해야 합니다.

(분량 관계상 스크립트 코드는 원본 문서 또는 GitHub 예시를 참고해 주세요. 핵심 로직은 Pillow 라이브러리로 이미지를 처리하는 것입니다.)

4단계: 보충 문서 추가하기(선택)

Skill을 더 완성도 있게 만들려면 references/formats.md에 지원 형식에 관한 설명을 작성할 수 있습니다.

테스트 및 디버깅 팁

방법 1: 직접 호출해 테스트하기

가장 간단한 테스트 방법은 OpenClaw에 /image-processor를 직접 입력하는 것입니다.

방법 2: 자동 호출 유도하기

이미지가 들어 있는 디렉터리를 찾은 뒤 OpenClaw에 다음과 같이 말합니다. “~/Downloads/photos 디렉터리의 이미지를 압축해 줘.”

방법 3: 실행 로그 확인하기

스크립트 실행에 실패하면 터미널 출력을 확인해 오류의 원인을 찾습니다.

보안과 모범 사례

보안 설정의 세 가지 원칙

1. 최소 권한: 실제로 필요한 도구만 선언하고 tools: *를 사용하지 않습니다.
2. 입력값 검증: 잘못된 매개변수를 막을 수 있도록 스크립트에서 사용자 입력을 검사합니다.
3. 경로 제한: 스크립트가 시스템의 민감한 디렉터리에 접근해서는 안 됩니다.

성능 최적화 권장 사항

• Progressive Disclosure 활용: description을 짧고 정확하게 작성합니다.
• 캐시 전략: 자주 읽는 설정은 SKILL.md에 직접 작성합니다.

마무리

핵심은 세 문장으로 정리할 수 있습니다.

1. Skill은 OpenClaw에 설치하는 전용 App입니다. SKILL.md 설정 파일로 ‘어떤 기능이며 언제 사용하는지’를 알려 줍니다.
2. 개발 과정은 간단합니다. 디렉터리를 만들고, 설정을 작성하고, 필요하면 스크립트를 작성하는 세 단계면 됩니다.
3. 작게 시작하세요. 처음부터 완벽하게 만들려고 하지 말고, 구체적인 문제 하나를 먼저 해결하세요. 작동하기 시작하면 이미 성공입니다.

지금 바로 시작하기

읽는 데서 멈추지 말고 지금 직접 해 보세요.

1. 글의 코드를 복사합니다.
2. 테스트합니다.
3. 자신의 용도에 맞게 수정합니다.

지금 시작하세요. 30분 뒤면 직접 만든 첫 번째 OpenClaw 스킬을 갖게 될 것입니다.