Claude Skills 사내 배포 — 팀 지식을 에이전트 능력으로 패키징

핵심 요약

같은 사내인데도 팀마다 컨벤션이 다르다. Claude Skills로 각 팀의 SOP·테스트 패턴·로깅 규약을 패키징해 모든 개발자의 Claude Code 세션에 자동 주입. 신입 1주차의 PR 리뷰 코멘트가 60% 감소, 컨벤션 위반 빈도가 8주 만에 80% 줄었다.

1. Skill이란

Skill = 트리거 조건 + 시스템 프롬프트 + 도구 + 참고 자료. 사용자가 "리팩터링 해줘" 같은 자연어를 던지면 매칭되는 Skill이 자동 로드돼 에이전트 능력이 확장된다. Markdown + frontmatter 한 파일이 본체.

2. 디렉터리 구조

~/.claude/skills/
  ./pr-review/SKILL.md
  ./db-migration/SKILL.md
  ./design-system/SKILL.md
  ./oncall-runbook/SKILL.md

SKILL.md frontmatter에 name, description, 필요 도구 목록을 적는다. 사내 git 리포로 배포하고 dotfiles 동기화처럼 관리.

3. 예시 — db-migration Skill

---
name: db-migration
description: Drizzle 마이그레이션을 생성·검증할 때 자동 적용.
allowed-tools: ["Bash","Edit","Read"]
---
# 우리 팀 마이그레이션 규약
- 컬럼 추가는 nullable로 시작 후 backfill, 다음 PR에서 NOT NULL
- 인덱스 생성은 CONCURRENTLY 강제
- 큰 테이블은 pt-online-schema-change 사용

4. 트리거 정밀도

description이 핵심. "drizzle migration", "alter table", "neon branch"처럼 매칭 키워드를 풍부히. 너무 광범위하면 무관한 세션에 강제 로드돼 컨텍스트 낭비. 사내 평균 description 90~140자가 정확도·비용 균형.

5. 팀 단위 배포

Backstage TechDocs에 SKILL.md를 호스팅, claude-code의 --skills-url로 가져오게 함. 팀별 onboarding 스크립트가 5초 만에 동기화. 변경 시 push만 하면 다음 세션부터 반영.

6. 측정

7. 함정

• Skill 충돌 — 같은 트리거 단어로 여러 Skill이 매칭되면 가장 긴 description 우선. 정렬을 명시
• 비밀 정보 — Skill에 API 키 절대 박지 말 것. 환경변수로
• 모니터링 — Skill 로드 빈도를 LangSmith 등으로 추적, 사용 안 되는 Skill은 정리

자주 묻는 질문

Q. CLAUDE.md와 차이? CLAUDE.md는 항상 로드, Skill은 트리거 시. 광범위 컨벤션은 CLAUDE.md, 특정 도메인 지식은 Skill로 분리.