에이전트 스킬 설계 (Agent Skill Design)
에이전트가 새로운 능력을 배우는 단위. 폴더 하나(SKILL.md + scripts/ + references/)로 구성되며, 에이전트가 설명서를 읽고 판단해서 실행한다. n8n 같은 노코드 워크플로우와의 핵심 차이는 “판단 여부” — 맥락을 이해하고 예외에 대응해야 하는 작업은 스킬이 적합하다. Claude Code의 Skills(Phase 2 하네스)와 동일한 원리다.
스킬 폴더 구조
~/.claude/skills/{스킬이름}/
├── SKILL.md ← 필수. 설명서이자 진입점
├── scripts/ ← 실행 로직 (TypeScript/Python)
│ ├── main-action.ts ← 핵심 로직
│ └── helper.ts ← 보조 기능
├── references/ ← 참고 자료
│ └── api-guide.md ← API 정보, ID 매핑, 엔드포인트
└── .env ← 환경변수
(출처: bbojjak-openclaw-skill-design-lesson10)
SKILL.md — 설명서이자 진입점
가장 중요한 파일. YAML 프론트매터에 name과 description을 넣고, 본문에 실행 절차·주의사항을 기록한다.
---
name: leader-self-enroll
description: 스터디장 본인 스터디 무료등록 자동화.
---스킬 매칭 메커니즘
에이전트 런타임(agent-runtime-architecture)이 세션 시작 시 모든 스킬의 description을 스캔한다:
사용자 요청: "스터디장 등록해줘"
↓
모든 스킬의 description 검색
↓
가장 적합한 스킬 선택
↓
SKILL.md 전체 로드 → 에이전트 실행
Warning
description이 부정확하면 적절한 스킬이 있어도 매칭에 실패한다. 실제 사고:
openclaw-lesson스킬이 있었는데 description에서 찾지 못해 수동으로 발행 → 태그 누락.
스킬 3요소 상세
1. SKILL.md — 무엇을 할지
- 스킬의 목적·사용 조건·실행 순서 기술
- 주의사항·예외 처리 방법 포함
- harness-engineering의 CLAUDE.md 지침과 동일한 역할 (에이전트에게 절차 제공)
2. scripts/ — 어떻게 실행할지
SKILL.md에 “이 스크립트를 실행해”라고 적혀있으면 에이전트가 bun run 등으로 실행.
스크립트 활용 기준:
- 복잡한 로직 (API 여러 개, 조건 분기)
- 재현 가능성 필요 (같은 스크립트 = 같은 결과)
--dry-run플래그 등 테스트 지원
간단한 스킬은 SKILL.md에 절차만 적고 에이전트가 직접 도구 조합으로 처리 가능.
3. references/ — 왜 이 값인지
API 키, 엔드포인트, ID 매핑표 등을 설명과 함께 기록. n8n에서는 블록에 하드코딩되어 “왜 이 값인지”를 알 수 없었던 것들을 마크다운으로 문서화.
# 블록 ID 매핑표
- Space: aB6d7eABzcR7
- 메인 블록: odwEgjK_kgNmNqYOB2iW4
- Slate API: updateSpace → updatedBlocks로 HtmlScript 업데이트git으로 관리되므로 변경 이력 추적 가능.
스킬 로드 우선순위
| 우선순위 | 위치 | 접근 범위 |
|---|---|---|
| 1 (높음) | <workspace>/skills/ | 해당 에이전트만 |
| 2 | ~/.claude/skills/ (공유) | 같은 컴퓨터 모든 에이전트 |
| 3 (낮음) | 번들 스킬 | OpenClaw 기본 내장 |
같은 이름의 스킬이 여러 곳에 있으면 우선순위 높은 쪽이 적용된다.
공유 폴더의 장점: 뽀야·뽀짝이 두 에이전트가 같은 스킬을 공유할 수 있다. n8n 워크플로우는 n8n 서버에 종속되어 이식 불가능했지만, 스킬은 폴더 복사만으로 이식 가능.
스킬 vs n8n 선택 기준
Tip
핵심 질문: “맥락을 이해하고 예외에 대응해야 하는가?”
| 상황 | 권장 도구 |
|---|---|
| 단순 반복 (“매일 10시에 이 API 호출”) | n8n |
| 외부 웹훅 중계 (인증 변환, 포맷 변환) | n8n |
| GUI 빠른 프로토타입 | n8n |
| 맥락 필요한 작업 (“이미 등록된 사람은 빼고”) | 스킬 |
| 복잡한 예외 처리 (“실패하면 원인에 따라 대응”) | 스킬 |
| 여러 시스템 조합 (Zoom + Bitly + 베터모드 + Airtable) | 스킬 |
| 점점 복잡해지는 작업 | 스킬 |
결정적 차이: n8n은 정해진 경로(A→B→C)를 따라 실행. 스킬은 에이전트가 SKILL.md를 읽고 상황에 맞게 판단. 베터모드 게시 실패 시 n8n은 처음부터 재실행, 스킬은 실패한 게시만 수정 재게시 가능.
Hermes 온보딩 영상은 스킬을 “성공한 작업 절차를 가벼운 레시피 카드로 압축한 것”으로 설명한다. 이는 스킬이 단순 프롬프트 저장소가 아니라 API 사용법, 검색 패턴, 예외 처리 순서를 재사용 가능한 실행 지식으로 남기는 단위라는 점을 교육적으로 잘 보여준다. (출처: yt-GsMB3SHHlzI-Hermes-Agent-완벽-구축-가이드)
Claude Code 하네스와의 연결
harness-engineering의 Phase 2 Skills와 동일한 원리:
Hermes 사례에서는 스킬이 “설치된 기능 목록”보다 반복 문제 해결 과정을 다음 작업에 남기는 학습 단위로 설명된다. 즉 커뮤니티 스킬을 많이 보유하는 것보다, 사용 중 발견한 병목·예외·선호 결과 형식을 스킬로 축적하는 것이 장기 품질을 만든다. (출처: yt-WXka6bp1aYw-헤르메스-에이전트-20분-총정리)
| Claude Code 하네스 | OpenClaw 스킬 |
|---|---|
.claude/skills/<skill>/SKILL.md | ~/.openclaw/workspace/skills/<skill>/SKILL.md |
| Skill description 매칭 | description 스캔 |
| 스킬 절차 실행 | 스크립트 실행 |
| 컨텍스트 절약 | 필요 시에만 로드 |
실제 경로 (출처: openclaw-github-readme):
- 워크스페이스 루트:
~/.openclaw/workspace(설정으로 변경 가능:agents.defaults.workspace) - 스킬 위치:
~/.openclaw/workspace/skills/<skill>/SKILL.md
차이점: Claude Code Skills는 사람이 /skill-name으로 호출. OpenClaw 스킬은 에이전트가 자동으로 description 매칭해서 선택.
실전 적용
- OpenClaw — 스킬 로드 우선순위를 제공하는 에이전트 런타임
- harness-engineering — Phase 2 Skills; 동일한 원리의 Claude Code 하네스 구현
- agentic-scheduling-design — n8n이 여전히 적합한 단순 반복·웹훅 중계 작업
관련 개념
- harness-engineering — Claude Code Skills(Phase 2)와 동일 원리
- agent-workspace-structure — skills/ 폴더가 워크스페이스 구조의 일부
- agent-runtime-architecture — 세션 시작 시 스킬 description 스캔 레이어
- agentic-scheduling-design — n8n vs 스킬 선택 기준의 확장 (스케줄링 관점)
스킬 마켓플레이스 신뢰 평가
ClawhHub(OpenClaw 스킬 마켓플레이스)에서 제3자 스킬을 선택할 때, 스킬 설계 품질(SKILL.md 구조) 외에 신뢰성 평가가 필요하다. (출처: bbojjak-openclaw-skill-ecosystem-lesson18)
평가 기준: VirusTotal+AI 스캔 결과, 커뮤니티 별점·다운로드, 코드 동작 방식(오프라인 vs 외부 API).
→ agent-skill-ecosystem-trust 참조.
Workspace Studio Skills와의 관계
workspace-studio의 “Skills” 기능(Cloud Next ‘26)은 이 스킬 설계 원칙과 용어가 같지만 구현 환경이 다르다:
| 구분 | OpenClaw/Claude Code 스킬 | Workspace Studio Skills |
|---|---|---|
| 환경 | CLI / 개발자 중심 | 노코드 GUI |
| 작성 방식 | SKILL.md + 스크립트 | 자연어 설명 |
| 실행 주체 | 에이전트 (description 매칭) | Gemini 에이전트 |
| 공유 | 파일 복사/git | Google Drive 공유 방식 |
공통: “재사용 가능한 자동화 단위” 원칙은 동일.
Claude Code 플러그인형 스킬 배포 사례
andrej-karpathy-skills-github-repo는 스킬/지침을 “GitHub 저장소 + 설치 명령” 형태로 배포하는 실전 예시다.
- 배포 단위: 단일
CLAUDE.md가이드 또는 플러그인 - 가치 제안: 코딩 에이전트의 반복 실수(가정 폭주, 과설계, 과잉 수정)를 사전 억제
- 시사점: 스킬 설계의 핵심은 코드량보다 행동 원칙의 명확성/검증성
영상 제작 워크플로우의 스킬화 사례
yt-jaychoi-ai-video-editing-automation-2026는 스킬 설계를 “코딩 자동화”를 넘어 “콘텐츠 제작 자동화”로 확장한 사례다.
- Video-Utils(컷/자막)와 HyperFrame/Remotion(모션)을 분리 스킬로 두고
- Claude Code가 프롬프트 하나로 오케스트레이션
- 반복 수정으로 얻은 스타일 규칙을 다음 작업에 재사용 가능한 스킬로 축적
핵심은 스킬이 단순 매크로가 아니라, 결과 피드백을 흡수해 점진적으로 품질을 고정하는 운영 단위라는 점이다.
소스
- bbojjak-openclaw-skill-design-lesson10
- bbojjak-openclaw-skill-ecosystem-lesson18 (스킬 마켓플레이스 신뢰 평가)
- openclaw-github-readme (실제 스킬 경로:
~/.openclaw/workspace/skills/<skill>/SKILL.md확인) - yt-jaychoi-ai-video-editing-automation-2026 (영상 편집 자동화 파이프라인의 스킬화·스타일 축적 사례)