AI 에이전트 스킬 엔지니어링 — 이론은 됐고, 실전에서 뭐가 달라지는지 보여준다

“스킬을 잘 만들면 99%보다 나아진다”는 말은 맞다. 근데 실제로 돌려본 사람이 하는 얘기는 좀 다르다.

들어가며

최근 Ben AI의 “How to build Claude Skills Better than 99% of People” 영상이 화제다. AI 에이전트 스킬의 개념부터 구조, 플러그인까지 잘 정리한 가이드다.

근데 가이드를 보고 “아 이렇게 하면 되는구나” 하는 것과, 실제로 매일 돌리면서 깨진 것을 고치는 건 완전히 다른 이야기다.

우리는 OpenClaw 기반으로 20개 이상의 스킬을 실전 운용하고 있다. 인스타그램 자동 발행, 뉴스 수집·요약, YouTube 자막 추출, 블로그 파이프라인까지. 이 글에서는 “이론 vs 실전”의 차이를 솔직하게 공유한다.

스킬이란 — 30초 요약

Ben AI 영상의 핵심을 빠르게 정리하면:

• skill.md = SOP (실행 흐름 정의)
• 참조 파일 = 스타일 가이드, 예시, MCP 지침
• 코드 스크립트 = API 호출, 함수 실행
• Progressive Disclosure = 메타데이터만 기억 → 트리거 시 본문 로드 → 필요 시 참조 로드

하나의 에이전트에 수천 개 스킬을 붙일 수 있는 이유가 이 Progressive Disclosure 덕분이다. 전부 컨텍스트에 올리는 게 아니라, 필요할 때만 꺼내 쓴다.

여기까지는 이론. 실전에서 마주치는 건 이론이 안 알려주는 것들이다.

실전 교훈 1: skill.md만으로는 부족하다 — “뚱뚱한 스킬” 안티패턴

Ben AI는 스킬의 핵심을 skill.md라고 설명한다. 맞는 말이다. 하지만 실전에서 가장 중요한 건 skill.md 밖에 있다.

CLAUDE.md의 함정

최근 “Repository-level Context Files: Helpful for Coding Agents?” 논문이 보여준 것처럼, 뚱뚱한 CLAUDE.md는 에이전트 성능을 오히려 떨어뜨린다. AI 자동 생성 컨텍스트는 성공률 2% 하락, 비용 20% 증가.

스킬도 마찬가지다. skill.md에 “이것도 하고 저것도 해”를 넣으면 에이전트가 헤맨다.

실전 원칙: 하나의 스킬 = 하나의 작업.

우리의 blog-publish 스킬은 “블로그 발행”만 한다. 이미지 생성은 nano-banana-pro 스킬이, 인스타 발행은 insta-knowledge 스킬이 각각 담당한다. 스킬 하나가 여러 작업을 시도하는 순간 품질이 떨어진다.

실전 사례: dev-delegate 스킬의 진화

우리 dev-delegate 스킬은 3번 다시 작성했다.

• v1: “Claude Code에 작업을 위임한다” — 너무 범용적. 에이전트가 매번 새로 방법을 고안하느라 일관성이 없었다.
• v2: “pty+background+wake 체이닝 패턴” 추가 — 실행은 되는데, interactive 모드로 빠져서 멈추는 버그.
• v3(현재): claude -p --dangerously-skip-permissions 패턴 고정, --verbose --output-format stream-json 필수 플래그 명시 — 드디어 안정적으로 동작.

핵심 교훈: 스킬은 “무엇을 한다”가 아니라 “정확히 어떻게 한다”를 적어야 한다. -p 플래그 하나 빠지면 interactive 모드로 떨어져서 프로세스가 멈춘다. 이런 건 이론 가이드에 안 나온다.

CODA: 스킬과 문서의 연결 고리

스킬이 “어떻게 하는지”를 정의한다면, 프로젝트 문서는 “왜 이렇게 하는지”와 “지금 상태가 어떤지”를 정의한다.

우리가 만든 CODA(Context-Oriented Documentation Architecture)는 이 둘을 연결한다:

CLAUDE.md (30줄) → 불변 규칙만
docs/INDEX.md    → "이 작업이면 이 문서를 봐라"
skills/          → 작업별 실행 방법

Ben AI가 말한 Progressive Disclosure를 프로젝트 문서까지 확장한 것이다. 스킬이 트리거되면 INDEX.md를 통해 필요한 문서만 로드된다.

실전 교훈 2: 자기개선은 마법이 아니다 — 피가 나야 배운다

Ben AI는 스킬이 “self-improving”할 수 있다고 말한다. 맞는 말인데, 저절로 되는 건 아니다.

우리가 실제로 삽질한 자기개선 사례들

사례 1: Apple Color Emoji 렌더링 실패

인스타 카드뉴스 Pillow 렌더링에서 이모지(☕, 📖)가 전부 ☐로 나왔다. NanumSquare Neo 폰트에 이모지 글리프가 없었던 것. 해결: Apple Color Emoji를 96px로 별도 로드 → RGBA 이미지로 렌더 → crop → resize → composite. 이 과정을 스킬에 기록하지 않았으면 다음 카드뉴스에서 또 같은 삽질을 했을 것이다.

사례 2: Peekaboo 스크린샷 CLI의 --output vs --path

peekaboo v3.0.0-beta3에서 --output 플래그가 --path로 바뀌었다. 문서에는 아직 --output으로 되어 있어서, 에이전트가 매번 실패했다. TOOLS.md에 “⚠️ --output 아님, --path 사용”을 한 줄 추가하고 나서야 멈췄다.

사례 3: Gemini의 자신감 넘치는 환각

블로그 에이전트(Gemini Flash)가 리서치 단계에서 존재하지 않는 벤치마크 점수와 모델명을 자신만만하게 지어냈다. “Gemini 3.1 Pro가 MMLU에서 92.3점”이라고 쓰는데, 실제 수치는 다른 값이었다. 이후 blog-writing 스킬에 “⚠️ Gemini가 생성한 수치는 반드시 Brave Search로 팩트체크” 규칙을 추가했다.

자기개선의 진짜 구조

1. 에이전트가 작업 수행
2. 실패/성공을 memory/YYYY-MM-DD.md에 기록
3. HEARTBEAT.md로 주기적 점검
4. 교훈을 skill.md나 TOOLS.md에 반영

자기개선의 핵심은 “기록”이다. 에이전트는 세션마다 기억을 잃는다. 파일에 써두지 않으면 같은 실수를 영원히 반복한다. 인간의 조직에서 “사후 분석(postmortem)“을 쓰는 것과 완전히 같은 원리다.

실전 교훈 3: 멀티에이전트에서 스킬이 빛난다

Ben AI는 플러그인(스킬 묶음)을 부서별로 배포하는 개념을 설명한다. 우리는 이걸 실제로 운용하고 있다.

2봇 협업 구조

같은 스킬 저장소(_share/skills/)를 iCloud로 공유한다. 로디가 만든 스킬을 누비가 바로 쓸 수 있다.

실전에서 발견한 스킬 공유의 함정

“같은 스킬, 다른 환경” 문제가 생긴다. 로디(맥미니)와 누비(맥북)는 설치된 도구가 다르다. nano-banana-pro 스킬은 Gemini API 키가 필요한데, 누비에는 환경변수가 없었다.

해결: 스킬 안에 환경 체크 로직 추가, 환경별 노트는 각자의 TOOLS.md에 기록.

스킬 공유의 진짜 가치는 “일관성”이다. 두 봇이 같은 블로그 발행 스킬을 쓰면, 누가 발행하든 같은 포맷이 나온다. 인간 팀에서 SOP를 공유하는 것과 같은 효과.

봇 간 통신에서 스킬의 역할

봇끼리 sessions_send로 작업을 요청할 때, 스킬이 있으면 “블로그 발행해줘”라고만 보내면 된다. 스킬이 없었을 때는 매번 “드래프트 경로는 여기고, 이미지는 이렇게 생성하고, MDX 변환은 이렇게 하고…”를 전부 설명해야 했다.

스킬 = API 엔드포인트. 이름만 부르면 나머지는 스킬이 알아서 한다.

실전 교훈 4: 돌아가는 파이프라인이 증명이다

이론적으로 완벽한 스킬보다, 매일 돌아가는 스킬이 낫다.

우리가 실제로 매일 운용하는 파이프라인:

각각이 스킬 조합으로 동작한다. 하나가 깨지면 고치고, 패턴이 보이면 스킬을 개선한다. 이게 자기개선의 실체다.

실전 숫자

• 전체 스킬 수: 20+ (OpenClaw 내장 + 커스텀)
• 매일 자동 실행되는 스킬: 5개 (RSS, 브리핑, 다이제스트 등)
• 스킬 재작성 횟수 (평균): 2-3회 (첫 버전은 거의 항상 문제가 있다)
• 자기개선 기록 건수: 50+ (TOOLS.md + memory/)

실전 교훈 5: 스킬 설계에서 가장 중요한 3가지

수십 개 스킬을 만들고 고치면서 발견한 패턴:

1. 구체적 명령어를 적어라

# ❌ 나쁜 예
이미지를 생성한다.
 
# ✅ 좋은 예
uv run generate_image.py --prompt "{프롬프트}" --filename /tmp/{이름}.png --pro

에이전트는 “이미지를 생성한다”를 보면 10가지 방법 중 하나를 고른다. 매번 다른 방법을 골라서 결과가 불안정하다. 정확한 명령어를 적으면 매번 같은 결과가 나온다.

2. 실패 패턴을 적어라

## ⚠️ 알려진 함정
- `claude -p` 없이 실행하면 interactive 모드로 멈춤
- `--verbose` 없이 `--output-format stream-json` 쓰면 에러
- Gemini가 생성한 수치는 반드시 팩트체크

스킬에 “하지 마라”를 적는 것이 “해라”를 적는 것만큼 중요하다.

3. 환경 의존성을 명시하라

## 필수 환경
- GEMINI_API_KEY 환경변수
- NanumSquareNeoOTF 폰트 설치
- uv (Python 패키지 매니저)

다른 머신에서 스킬이 안 돌아가는 이유의 90%는 환경 의존성 때문이다.

Ben AI와의 포지션 차이

둘 다 필요하다. Ben AI의 가이드로 시작하고, 실전에서 부딪히면서 자기만의 체계를 만들어가는 게 정답이다.

액션 아이템: 지금 시작할 수 있는 것

첫 스킬 만들기 (5분)

~/.claude/skills/
└── my-first-skill/
    └── SKILL.md

# My First Skill
 
## Description
블로그 글의 제목을 5개 제안한다.
 
## Process
1. 사용자가 주제를 알려주면
2. SEO 키워드를 고려해서
3. 클릭을 유도하는 제목 5개를 제안한다
 
## Rules
- 한국어로 작성
- 15자 이내
- 숫자 포함 제목 최소 1개

이것만으로도 동작한다. 여기서부터 참조 파일 추가, MCP 연동, 코드 스크립트를 하나씩 쌓아가면 된다.

다음 단계 로드맵

1. CLAUDE.md 다이어트 — 500줄 넘으면 스킬로 분리
2. CODA 적용 — docs/INDEX.md로 문서 라우팅
3. 기록 습관 — 실패를 파일에 남기기 (자기개선의 시작)
4. 스킬 공유 — 팀이 있다면 공유 폴더, 없다면 GitHub
5. 파이프라인 조합 — 단일 스킬 → 스킬 체이닝 → 자동화

마치며

스킬 엔지니어링은 새로운 소프트웨어 레이어다. Ben AI 말처럼 “곧 수익화 가능”해질 것이다.

하지만 진짜 차이는 “만드는 것”과 “돌리는 것” 사이에 있다. 매일 돌려보고, 깨진 걸 고치고, 패턴을 스킬에 반영하는 사이클을 돌리는 사람이 결국 99%를 이긴다.

이론은 됐다. 만들고 돌려보자.

참고:

• Ben AI — How to build Claude Skills Better than 99% of People
• CODA 프레임워크
• Anthropic 공식 Skills
• “CLAUDE.md 지워라” 논문 리뷰
• 에이전트 스킬 생태계 분석
• CODA 소개 블로그