Claude Code 스킬 28개 운영 경험: 왜 지속 모니터링이 필요한가

Claude Code의 스킬 시스템을 활용해 28개의 스킬을 만들고 운영해왔습니다.

그 과정에서 스킬의 품질을 일정하게 유지하기 위한 자체 검증 도구까지 직접 개발했습니다. 하지만 AI 도구 생태계는 예상보다 훨씬 빠르게 변했고, 제가 만든 검증 도구가 오히려 outdated된 규칙을 기준으로 경고를 내고 있었다는 사실을 뒤늦게 발견했습니다.

이 글에서는 그 경험을 공유하려 합니다. AI 도구를 만들고 운영할 때 왜 지속적인 모니터링이 필수인지에 대한 이야기입니다.

본격적인 이야기에 앞서, 클로드 코드 스킬이 무엇인지 간략히 짚고 넘어가겠습니다.

‍

클로드 코드 스킬이란? MCP와의 차이

클로드 코드 스킬

Claude Code 스킬은 SKILL.md라는 마크다운 파일 하나에 워크플로우를 기술하면 Claude가 알아서 실행하는 자동화 시스템입니다. MCP 서버처럼 별도의 프로세스를 띄울 필요 없이 마크다운으로 '사람이 읽을 수 있는 자동화'를 만들 수 있다는 것이 가장 큰 장점입니다.

MCP에서 스킬로

처음에는 MCP 서버를 사용했습니다. 잘 동작했지만, 프로세스를 띄워야 하고 설정이 번거로워서 단순한 워크플로우 안내에는 과했습니다. 스킬 시스템으로 전환한 뒤 하나씩 추가하다 보니 금방 20개를 넘겼습니다.

~/.claude/skills/
├── deploy-yard/SKILL.md     # dev 서버 배포
├── slack-analyze/SKILL.md   # Slack 스레드 분석
├── vpn/SKILL.md             # VPN 연결 관리
└── ... (28개)

그런데, 문제는 품질이었습니다.

‍

클로드 코드 스킬 28개를 만들고 운영하며 배운 ‘품질 유지 전략’

1. 문제 인식: 스킬이 늘어날수록 관리가 어렵다

초기에 만든 스킬과 나중에 만든 스킬의 구조가 달랐습니다. frontmatter가 있는 것과 없는 것, description이 충실한 것과 빈약한 것이 섞여 있었습니다. 사람이 하나씩 검토하기엔 이미 너무 많았습니다. "가이드라인 문서를 만들어서 Claude가 스스로 검증하게 하자"는 생각이 들었습니다.

‍

2. 문제 해결: 직접 만든 검증 도구

Anthropic의 공식 스킬 빌딩 가이드 PDF를 참고해서 검증 도구를 직접 만들었습니다.

당시 가이드라인의 핵심 규칙

규칙	설명
`name`, `description` 필수	frontmatter에 반드시 포함
Description은 3인칭	"This skill should be used when..."
본문에 2인칭 금지	"you", "your" 사용 불가
name = 디렉토리명	반드시 일치
1,500~2,000 단어 최적	5,000 초과 시 references/로 분리
Progressive Disclosure 3단계	메타데이터 → SKILL.md → references/

검증 도구 구조

skill-authoring-review/
├── SKILL.md                              # 스킬 정의
├── scripts/
│   ├── validate_skill.py                 # 자동 검증 스크립트
│   └── init_skill.sh                     # 새 스킬 스캐폴딩
├── references/
│   ├── anthropic-skill-guide.md          # 가이드라인 요약
│   ├── validation-checklist.md           # 수동 체크리스트
│   └── templates.md                      # SKILL.md 템플릿 5종
└── examples/
    └── minimal-skill.md                  # 최소 유효 스킬 예시

validate_skill.py는 다음을 검증했습니다:

Critical: SKILL.md 존재, frontmatter 유무, name/description 필드
Warning: 2인칭 사용 탐지 (코드블록 제외), description 인칭, name-디렉토리 불일치
Suggestion: 트리거 키워드 부재, 단어 수 초과/부족
recursive 옵션으로 전체 스킬을 일괄 검증하고, JSON/markdown 리포트도 생성할 수 있었습니다.

실제로 잘 동작했습니다. 새 스킬을 만들 때마다 검증을 돌리고, 스킬 품질을 일정 수준으로 유지할 수 있었습니다.

몇 달간 이 체계로 잘 운영했습니다. 새 스킬을 만들 때마다 검증을 돌리고, 통과하면 안심하고 배포했습니다. 그런데 어느 순간, 검증 도구가 통과시킨 스킬에서 문제가 보이기 시작했습니다.

‍

3. 균열과 반전: 검증 도구의 한계, 생태계의 변화

AI 도구 생태계는 빠르게 변합니다. 몇 개월 사이에 여러 가지가 바뀌었습니다:

MCP → 스킬: 단순 워크플로우는 MCP 서버 대신 스킬로 전환하는 추세
CLAUDE.md 축소 권장: 내용을 가득 채웠던 CLAUDE.md를 줄이고, 스킬과 references로 분산하라는 가이드
MCP 동적 로딩: 필요할 때만 MCP를 로드하는 방식 등장
새 frontmatter 필드: allowed-tools, context, model 등 7개 필드 추가

제가 만든 검증 도구는 이전 규칙을 기준으로 만들어진 것이었습니다.

AI 도구 생태계가 빠르게 변하고 있다는 걸 체감하고 있었기 때문에, 검증 도구의 기반 규칙이 아직 유효한지 직접 확인해봤습니다. 공식 문서를 다시 읽어보니 "description은 3인칭으로" 같은 규칙은 이미 사라져 있었습니다.

PDF 가이드와 현재 공식 웹 문서를 직접 비교해본 결과, 변경 폭이 상당했습니다.

Frontmatter 변경

필드	이전	현재
`name`	필수, 디렉토리명 일치	선택, 생략 시 디렉토리명 자동 사용
`description`	필수	권장, 생략 시 첫 문단 사용
`argument-hint`	없음	신규 — 자동완성 힌트
`allowed-tools`	없음	신규 — 스킬 내 허용 도구 제한
`model`	없음	신규 — 실행 모델 지정
`context`	없음	신규 — `fork` 로 서브에이전트 실행
`disable-model-invocation`	없음	신규 — Claude 자동 호출 차단

작성 규칙 변경

항목	이전	현재
Description 인칭	3인칭 필수	제약 없음
본문 문체	2인칭 금지, 명령형 필수	제약 없음
단어 수	1,500~2,000 최적, 5,000 초과 시 분리	500줄 이내 (줄 기준으로 변경)
디렉토리 구조	`scripts/`, `references/`, `assets/` 고정	자유 구조
Progressive Disclosure	3단계	2단계 (description 버짓 = 컨텍스트의 2%)

방향은 명확했습니다: 엄격한 규칙 → 실용적 유연성 + 고급 기능

변경 폭을 확인하고 나니 선택지는 두 가지였습니다. 커스텀 도구를 최신 규칙에 맞게 전면 개편하거나, 공식 도구로 갈아타거나.

‍

4. 전환 결정: 공식 skill-creator 플러그인

규칙이 바뀐 상태에서, 커스텀 도구를 최신 규칙에 맞게 계속 유지보수할지 다른 방법을 쓸지 판단이 필요했습니다. Anthropic의 공식 skill-creator 플러그인이 현 시점에서 최적의 선택이라고 판단했습니다.

공식 플러그인의 4가지 모드

모드	기능
Create	새 스킬 생성
Eval	테스트 케이스로 스킬 성능 정량 평가 (60/40 분할, 3회 반복)
Improve	평가 결과 기반 자동 개선 (최대 5회 반복)
Benchmark	다중 실행 벤치마크 + 분산 분석, HTML 리포트

커스텀 도구 vs 공식 플러그인 비교

	커스텀 도구	공식 skill-creator
정적 검증	더 세밀 (2인칭 탐지 등)	기본적 (프론트매터 스키마)
동적 평가	없음	있음 (eval 모드)
자동 개선	없음	있음 (improve 모드)
벤치마크	없음	있음 (분산 분석)
규칙 최신성	직접 유지보수	Anthropic이 관리
일괄 검증	`--recursive` 지원	단일 스킬

커스텀 도구의 유일한 강점이었던 "세밀한 스타일 검증"은 가이드라인이 문체 규칙을 완화하면서 더 이상 장점이 아니게 되었습니다.

28개 스킬 전수 검토 결과

공식 플러그인으로 전환하고, 28개 스킬 전체를 최신 가이드라인으로 검토했습니다.

5.0 (모범)    ■          1개  — knowledge-graph
4.0~4.5       ■■■■■■■■■  13개 — slack-analyze, notion-cdp, vpn 등
3.0~3.5       ■■■■■■     10개 — deploy 계열, smart-loop 등
2.0~2.5       ■■         3개  — version-report, projects 등
1.0 (심각)    ■          1개  — milvus-attu

발견된 주요 패턴:

이슈	비율
frontmatter 완전 누락	14% (4/28)
`allowed-tools` 미사용	71% (20/28)
`argument-hint` 미사용	54% (15/28)
파일명 `skill.md` (소문자)	7% (2/28)

frontmatter가 없으면 Claude가 자동으로 스킬을 호출할 수 없습니다. 28개 중 4개가 이 상태였다는 것은, 만들어놓고 수동 슬래시 커맨드로만 쓰고 있었다는 뜻입니다.

새로 추가된 allowed-tools는 스킬이 사용할 수 있는 도구를 제한해서 예측 가능성과 보안을 높입니다. 71%가 미사용 중이었습니다.

28개를 돌려보고 나서야, 도구를 만드는 것보다 유지하는 것이 더 어렵다는 걸 실감했습니다.

‍

마무리

AI 도구 생태계는 매우 빠르게 변화하고 있습니다. 가이드라인, API, 베스트 프랙티스는 몇 개월 단위로 업데이트되며, 한 번 구축한 워크플로우나 도구가 지속적으로 유효하다는 보장은 없습니다.

결국 도구를 사용하는 과정 자체에도 지속적인 모니터링이 필요합니다. 현재 사용 중인 도구의 기반이 여전히 유효한지, 최신 기준에 부합하는지를 정기적으로 확인해야 합니다.

특히 스킬이 점점 늘어나고 있다면, 공식 문서와 자신의 도구 기준을 주기적으로 비교·검토하는 것이 중요합니다. 플랫폼이 변화하면 기존의 베스트 프랙티스가 오히려 비효율적인 안티패턴으로 전환될 수 있기 때문입니다.

‍