Anthropic 엔지니어가 직접 공개한 Claude Code 스킬 잘 쓰는 법

ALT

클로드 코드 구축에서 얻은 교훈 우리가 기술을 사용하는 방법

Claude Code 스킬(Skills)을 어떤 유형으로 만들고, 어떻게 잘 작성하고, 팀에 어떻게 배포하는지 — Anthropic 내부에서 수백 개 스킬을 운영하며 검증한 실전 노하우를 한번에 파악할 수 있습니다.

왜 스킬인가?

스킬이 그냥 마크다운 파일 아니냐는 오해를 자주 듣습니다. 하지만 스킬의 진짜 정체는 폴더입니다.

왜 스킬인가? — "마크다운 파일 아닌데요"

"스킬이 그냥 마크다운 파일 아니냐"는 오해를 자주 듣습니다. 하지만 스킬의 진짜 정체는 폴더입니다. SKILL.md 하나가 아니라, 스크립트·자산·데이터·예제 코드까지 포함할 수 있는 구조입니다. Claude Code에서는 동적 훅(Hook) 등록 같은 다양한 설정 옵션까지 제공합니다.

Anthropic의 Thariq(Claude Code 팀)는 사내에서 수백 개의 스킬을 카탈로그화한 뒤, 9가지 반복 유형으로 분류됐다고 밝혔습니다. 좋은 스킬은 하나의 유형에 깔끔하게 들어맞고, 혼란스러운 스킬은 여러 유형에 걸쳐 있다고 합니다.

9개의 스킬 유형

1. 라이브러리 & API 레퍼런스

내부 라이브러리, CLI, SDK를 올바르게 사용하는 방법을 담은 스킬입니다. Claude가 자주 실수하는 라이브러리에 대해 레퍼런스 코드 스니펫 폴더와 주의사항 목록을 포함합니다.

예시:

• billing-lib — 사내 결제 라이브러리의 엣지 케이스와 함정

• internal-platform-cli — 내부 CLI의 모든 서브커맨드 + 언제 쓰는지 예시

• frontend-design — 우리 디자인 시스템에 맞게 Claude 코딩 품질 향상

2. 제품 검증 (Product Verification)

코드가 실제로 작동하는지 테스트하고 검증하는 스킬입니다. Playwright, tmux 같은 외부 도구와 짝을 이뤄 사용합니다.

Anthropic에서는 검증 스킬을 훌륭하게 만드는 데 엔지니어 1명이 1주일을 투자할 가치가 있다고 합니다. Claude의 아웃풋이 정확한지 보장하는 데 결정적이기 때문입니다.

활용 팁:

• Claude가 테스트 과정을 영상으로 녹화하게 해서 실제로 뭘 테스트했는지 확인

• 각 단계에서 프로그래밍 방식으로 상태를 검증하는 assertion 삽입

• 스킬 폴더에 다양한 검증 스크립트를 포함

예시:

• signup-flow-driver — 헤드리스 브라우저에서 회원가입 → 이메일 인증 → 온보딩 자동 테스트

• checkout-verifier — Stripe 테스트 카드로 결제 UI를 구동하고 인보이스 상태 검증

3. 데이터 수집 & 분석

데이터·모니터링 스택에 연결하는 스킬입니다. 인증 정보, 대시보드 ID, 일반적인 데이터 워크플로우 등을 포함합니다.

예시:

• funnel-query — "가입 → 활성화 → 결제 퍼널을 보려면 어떤 이벤트를 조인해야 하는지" + canonical user_id가 있는 테이블 정보

• grafana — 데이터소스 UID, 클러스터 이름, "문제 → 대시보드" 매핑 테이블

4. 비즈니스 프로세스 & 팀 자동화

반복적인 팀 워크플로우를 하나의 명령어로 자동화하는 스킬입니다. 이전 실행 결과를 로그 파일로 저장하면 모델이 이전 실행과의 차이를 파악하고 일관성을 유지할 수 있습니다.

예시:

• standup-post — 티켓 트래커 + GitHub 활동 + Slack 취합 → 포맷팅된 스탠드업, 변경분만 표시

• weekly-recap — 머지된 PR + 닫힌 티켓 + 배포 → 주간 요약 자동 생성

5. 코드 스캐폴딩 & 템플릿

프레임워크 보일러플레이트를 생성하는 스킬입니다. 코드만으로는 커버하기 어려운 자연어 요구사항이 있을 때 특히 유용합니다.

예시:

• new-migration — 마이그레이션 파일 템플릿 + 자주 빠지는 함정

• create-app — 인증, 로깅, 배포 설정이 미리 연결된 새 앱 스캐폴딩

6. 코드 품질 & 리뷰

조직의 코드 품질을 강제하고 코드를 리뷰하는 스킬입니다. 훅이나 GitHub Action의 일부로 자동 실행할 수도 있습니다.

예시:

• adversarial-review — 새로운 눈의 서브에이전트를 생성해서 비판하고, 수정하고, 지적이 사소한 수준으로 떨어질 때까지 반복

• testing-practices — 테스트 작성법과 무엇을 테스트해야 하는지에 대한 지침

7. CI/CD & 배포

코드를 fetch, push, 배포하는 스킬입니다. 다른 스킬을 참조하여 데이터를 수집하기도 합니다.

예시:

• babysit-pr — PR 모니터링 → 불안정한 CI 재시도 → 머지 충돌 해결 → 자동 머지 활성화

• deploy-service — 빌드 → 스모크 테스트 → 점진적 트래픽 롤아웃(에러율 비교) → 회귀 시 자동 롤백

8. 런북 (Runbook)

증상(Slack 스레드, 알림, 에러 시그니처)을 받아서 다단계 조사를 수행하고 구조화된 리포트를 생성하는 스킬입니다.

예시:

• service-debugging — 증상 → 도구 → 쿼리 패턴 매핑

• oncall-runner — 알림 가져오기 → 일반적 원인 확인 → 조사 결과 포맷팅

9. 인프라 운영

정기 유지보수와 운영 절차를 수행하는 스킬입니다. 파괴적 작업에 가드레일을 포함할 수 있습니다.

예시:

• resource-orphans — 고아 파드/볼륨 탐지 → Slack 알림 → 유예 기간 → 사용자 확인 → 정리

• cost-investigation — "스토리지/이그레스 비용이 왜 급증했는지" + 특정 버킷과 쿼리 패턴

스킬 잘 만드는 7가지 팁

9가지 유형을 파악했다면, 이제 실제로 어떻게 잘 만드는지가 중요합니다. Anthropic이 검증한 핵심 팁들입니다.

팁 1: 당연한 걸 쓰지 마세요

Claude는 코딩에 대해 이미 많이 알고 있습니다. 스킬에는 Claude의 기본 사고방식을 밀어내는 정보만 담으세요.

예를 들어 Anthropic의 frontend-design 스킬은 Inter 폰트와 보라색 그래디언트 같은 Claude의 기본 디자인 패턴을 피하도록 고객과 반복 작업하며 만들어졌습니다.

팁 2: Gotchas 섹션을 키우세요

스킬에서 가장 가치 있는 콘텐츠는 Gotchas(주의사항) 섹션입니다. Claude가 스킬을 사용하면서 마주치는 실패 지점들을 시간이 지나면서 계속 추가하세요. 이 섹션이 두꺼울수록 스킬의 품질이 올라갑니다.

팁 3: 파일 시스템을 활용하세요 — Progressive Disclosure

스킬은 마크다운 파일이 아니라 폴더라고 했죠. 전체 파일 시스템을 컨텍스트 엔지니어링과 점진적 정보 공개(Progressive Disclosure)의 도구로 활용하세요.

• 상세 함수 시그니처 → references/api.md로 분리

• 출력 템플릿 → assets/에 복사용 파일 배치

• 레퍼런스 코드, 스크립트, 예제 → 각각의 폴더에 정리

Claude에게 "이 폴더에 이런 파일들이 있다"고 알려주면, 필요할 때 적절한 타이밍에 읽어갑니다.

팁 4: Claude를 너무 조이지 마세요

스킬은 재사용되는 만큼, 지시를 너무 구체적으로 쓰면 특정 상황에서 경직됩니다. 필요한 정보는 주되, 상황에 따라 적응할 수 있는 유연성을 남겨두세요.

팁 5: 셋업을 설계하세요

스킬에 사용자별 설정이 필요한 경우(예: Slack 채널 지정), 스킬 디렉터리 안에 config.json을 두고 최초 실행 시 설정을 받는 패턴이 효과적입니다. 구조화된 질문이 필요하면 AskUserQuestion 도구를 활용하세요.

팁 6: description 필드는 모델을 위한 것

Claude Code가 세션을 시작하면 모든 스킬의 description을 스캔하여 "이 요청에 맞는 스킬이 있는가?"를 판단합니다. description은 사람을 위한 요약이 아니라, 모델이 언제 이 스킬을 트리거해야 하는지 알려주는 필드입니다.

팁 7: 스크립트와 코드를 넣으세요

Claude에게 가장 강력한 도구 중 하나는 코드입니다. 데이터 가져오기용 함수 라이브러리, 헬퍼 스크립트 등을 스킬 폴더에 넣어두면 Claude는 보일러플레이트 재구축 대신 조합(composition)에 집중할 수 있습니다.

예를 들어 데이터 분석 스킬에 이벤트 소스 조회 함수들을 넣어두면, "화요일에 무슨 일이 있었어?"라는 프롬프트에 Claude가 즉석에서 분석 스크립트를 생성·실행합니다.

스킬을 팀에 배포하는 2가지 방법

방법 1: 레포에 체크인

.claude/skills/ 디렉터리에 스킬을 커밋합니다. 소규모 팀이 적은 수의 레포에서 작업할 때 잘 맞습니다. 단, 체크인한 스킬이 늘어나면 모델 컨텍스트에 부하가 갑니다.

방법 2: 플러그인 마켓플레이스

내부 플러그인 마켓플레이스를 구축하여 스킬을 배포하고, 팀원이 필요한 스킬만 골라 설치하는 방식입니다. 규모가 커지면 이 방식이 유리합니다.

Anthropic의 마켓플레이스 운영 방식:

1. 중앙 관리팀이 따로 없음 — 유기적으로 유용한 스킬을 발견

2. 새 스킬은 GitHub의 샌드박스 폴더에 올리고 Slack 등에서 홍보

3. 충분한 견인력이 생기면(스킬 소유자가 판단) PR을 넣어 마켓플레이스로 승격

4. 나쁘거나 중복된 스킬이 만들어지기 쉬우므로 출시 전 큐레이션 과정이 반드시 필요

알아두면 좋은 고급 기법