OpenClaw 커스텀 Skill 개발 가이드
당신의 독특한 워크플로를 Skill로 캡슐화해서 AI가 진정으로 일해주게 하기.
왜 Skill을 직접 써야 할까?
OpenClaw는 많은 통용 Skill을 내장하고 있지만, 모두의 워크플로는 다르지. 커스텀 Skill로 할 수 있는 건:
- 🎯 독특한 워크플로 캡슐화: 회사 내부 승인 흐름, 보고서 포맷, 데이터 소스 - 다른 사람의 Skill로는 커버 불가
- 🔗 내부 도구 연동: 회사 CRM, ERP, OA 시스템과 연결해서 AI가 업무 시스템을 직접 조작
- ⚡ 실행 효율 향상: 10단계 수동 작업을 Skill 호출 하나로 압축, AI 한 마디로 완성
- 🔄 팀 협력 표준화: 팀원들이 같은 Skill 세트를 공유, AI 산출물의 포맷과 품질 일치
Skill 아키텍처 개요
Skill의 핵심 구조는 매우 간단하고 3부분으로 구성:
선언 계층(Manifest)
OpenClaw에 이 Skill이뭔지、뭐가 필요한지、뭘 산출하는지를 알려줘. 이름, 설명, 파라미터 정의, 권한 요청 등 메타정보를 포함.
실행 계층(Handler)
Skill의핵심 로직. 입력 파라미터를 받아서 구체적인 작업 실행(API 호출, 파일 읽기/쓰기, 데이터 처리), 결과 반환. 동기와 비동기 두 가지 모드 지원.
생명주기 훅(Hooks)
선택적 확장 포인트:초기화(설정 로드, 연결 구축), 검증(입력 합법성 검사), 정리(리소스 해제, 연결 닫기). 안 써도 괜찮아, 시스템에 기본 동작이 있어.
실전: "고객 팔로우업 리마인더" Skill 구축
실제 시나리오로 완전한 개발 프로세스를 거쳐보자:
요구사항 명확화
시나리오: 영업 팀이 AI가 매일 CRM에서 7일 이상 미접촉 고객 확인, 팔로우업 목록 생성, 기업 위챗 그룹에 발송하길 원함.
- 입력: 일 기준값(기본 7일), 타겟 그룹 ID
- 출력: 팔로우업 목록(고객명, 마지막 접촉 시간, 제안 액션)
- 권한: CRM API 접근 권한, 기업 위챗 발송 권한 필요
Manifest 작성
Skill의 메타정보 정의: 이름 customer-followup, 기능 설명, 2개 입력 파라미터와 타입, 기본값 선언. 이 단계가 AI가언제 호출할지를 결정.
Handler 실행
핵심 로직 3단계: ① CRM API 호출해서 기한 넘은 고객 조회 → ② AI로 각 고객 팔로우업 제안 생성 → ③ 메시지 포맷 후 기업 위챗에 발송. 각 단계가 OpenClaw 내장 도구 호출 가능.
로컬 테스트
OpenClaw 개발 모드로 Skill 로드, AI에게 "3일 이상 미접촉 고객 확인해". AI가 의도 올바르게 인식하는지, 정확한 파라미터 전달하는지, 예상 결과 반환하는지 관찰.
배포 온라인
테스트 통과 후 Skill을 프로덕션에 설치. 팀의 누구나 자연어로 트리거할 수 있어.
일반 개발 패턴
대부분의 커스텀 Skill은 이런 카테고리 중 하나:
🌐 API 통합 클래스
외부 서비스 API 대접해서 AI가 써드파티 시스템 조작 가능.
- 기업 위챗 / 디기 / 페이셔와 연결, 메시지와 알림 발송
- Jira / Notion / 페이셔 다차원표와 연결, 프로젝트와 작업 관리
- 결제 게이트웨이 호출, 주문 상태 조회
- 자체 구축 내부 API 서비스와 연결
📄 파일 처리 클래스
대량 파일 처리, 포맷 변환, 정보 추출.
- Word를 PDF로 대량 변환하고 워터마크 추가
- 송장 이미지에서 금액과 날짜 추출(OCR 결합)
- 여러 Excel 합병해서 요약 보고서 생성
- 폴더의 파일 스캔해서 규칙에 따라 정렬 보관
🔔 알림과 보고 클래스
정시에 보고서 생성하거나 특정 조건에서 알림 발송.
- 일일 스탠업 요약: 어제 Git 커밋과 Jira 변경사항 정리
- 비정상 경고: 지표 초과 시 자동 알림
- 주간 보고 생성: 여러 데이터 소스에서 데이터 가져와서 포맷
🔄 데이터 처리 클래스
ETL, 데이터 정제, 포맷 변환 등 데이터 집약 작업.
- 데이터베이스에서 내보내기 → 정제 → 다른 시스템에 쓰기
- CSV/JSON 포맷 상호 변환해서 데이터 검증
- 다중 소스 데이터 합병 중복 제거
테스트와 디버깅 팁
- 🐛 개발 모드 실행: Skill 로드 시 debug 모드 켜서 AI의 완전한 파라미터와 Skill의 완전한 결과 볼 수 있어
- 🧪 입력 모의 테스트: 전형적인 입력 몇 세트(정상값, 경계값, 비정상값) 준비해서 하나씩 Skill 동작 검증
- 📋 Manifest 설명 확인: AI가 Skill을 호출하지 않으면 보통 Manifest 설명이 불분명. 더 자연스러운 언어로 기능 설명해보기
- 🔍 로그 추적: Handler에서 로그 출력 추가, 각 단계의 실행 상황 추적
- ⏱️ 타임아웃 처리: 외부 API 호출 시 항상 타임아웃 설정, Skill이 멈추는 걸 피하기
- 🛡️ 에러 처리: 명확한 에러 메시지 반환, Skill이 직접 충돌하지 않게. AI가 에러 정보로 다음 단계 판단
발행과 공유
쓴 Skill 숨기지 말고 커뮤니티에 공유해서 더 많은 사람이 혜택 받게:
- 📦 패키징: 표준 폴더 구조에 따라 파일 정렬, Manifest, Handler, README, 샘플 설정 포함
- ✅ 심사: OpenClaw Skill 저장소에 제출 전에 하드코딩된 키 없는지, 기본 에러 처리 있는지, 설명 명확한지 확인
- 🌍 발행: PR로 공식 Skill 저장소에 제출, 심사 통과 후 모든 사용자가 한 번의 클릭으로 설치
- 🏢 기업 내부 공유: 프라이빗 Skill 저장소 구축해서 팀 내부에서만 사용
daily-report-generator 이게 tool-v2-final 보다 훨씬 나아. AI도 이름과 설명에 따라 호출 여부 판단.개발 최고 실행 체크리스트
- ✅ 단일 책임: 하나의 Skill은 한 가지만 해. "이메일 발송"과 "보고서 생성"은 별개의 Skill이어야 함
- ✅ 파라미터에 기본값: 파라미터에 기본값 설정해서 AI가 확인할 정보 줄이기
- ✅ 설명은 AI를 위해: Manifest의 설명은 AI를 위한 것, AI가 어떤 상황에 호출할지 판단하게
- ✅ 멱등성 설계: 같은 입력으로 여러 번 실행해도 결과는 같게. 이메일 중복 발송, 레코드 중복 생성 피하기
- ✅ 민감 정보는 환경 변수: API Key, 비밀번호 등은 절대 Skill에 하드코딩 금지
- ✅ 의미 있는 결과 반환: "성공" 반환 말고 구체적으로 뭘 했는지 반환(예: "Zhang San, Li Si, Wang Wu에 3개 이메일 발송")
관련 검색
OpenClaw Skill 개발 · 커스텀 AI 기술 · OpenClaw 플러그인 개발 · AI Agent 확장 개발 · OpenClaw Skill 발행 · 기업 AI 자동화