출처: unclejobs.ai — AI Threads
가장 먼저 깨야 할 오해가 있어요.
"스킬은 그냥 .md 파일 아닌가요?"
아닙니다. 스킬은 폴더예요.
마크다운 파일 하나가 아니라, 그 안에 스크립트, 예제 코드, 데이터 파일, 템플릿을 전부 담을 수 있는 폴더 구조입니다. Claude에게 "이 폴더 안에 이런 파일들이 있어"라고 알려주면, 필요한 시점에 알아서 꺼내 읽어요.
SKILL.md 하나에 모든 걸 때려넣는 게 아니라, 폴더 전체를 하나의 지식 체계로 설계하는 거예요. 이게 Anthropic이 "가장 흥미로운 스킬들"이라고 부르는 것들의 공통점이래요. 설정 옵션과 폴더 구조를 창의적으로 쓰고 있다는 거.
좋은 스킬은 하나에 딱 속하고, 헷갈리는 스킬은 여러 개에 걸쳐 있었다고. 이건 "우리 팀에 어떤 유형이 빠졌는지" 체크하는 프레임워크로 쓰면 좋아요.
"이 라이브러리는 이렇게 써야 해"를 가르치는 스킬.
회사에 내부 빌링 라이브러리가 있다고 해봐요. 특정 메서드를 호출할 때 순서를 잘못하면 에러가 나는 함정이 있는데, Claude는 당연히 이걸 모릅니다. 이런 엣지 케이스와 "이렇게 하면 안 돼" 목록을 스킬에 담는 거예요. 레퍼런스 코드 스니펫 폴더도 같이.
외부 라이브러리도 마찬가지. Claude가 자주 실수하는 부분이 있으면 스킬로 교정할 수 있어요.
예시:
- billing-lib — 사내 빌링 라이브러리의 엣지 케이스, 함정 모음
- internal-platform-cli — 사내 CLI의 모든 서브커맨드와 사용 시점 예시
- frontend-design — Claude가 우리 디자인 시스템을 더 잘 다루게 만드는 스킬
"코드가 진짜 돌아가는지 테스트하는 법"을 가르치는 스킬.
Claude가 코드를 짜주긴 하는데, 그게 실제로 맞게 작동하는지는 어떻게 확인하죠? 이 스킬은 Playwright(브라우저 자동화 도구)나 tmux 같은 외부 도구와 짝을 이뤄서, Claude가 직접 테스트를 돌리고 결과를 검증하게 만들어요.
Anthropic이 이렇게까지 말합니다.
"엔지니어 한 명이 일주일을 투자해서 검증 스킬 하나를 완벽하게 만드는 것도 충분히 가치가 있다."
Claude가 테스트 과정을 영상으로 녹화하게 해서 정확히 뭘 테스트했는지 눈으로 볼 수 있게 만들거나, 각 단계에서 프로그래밍적 검증(assertion)을 강제하는 방법도 추천해요.
예시:
- signup-flow-driver — 회원가입 → 이메일 인증 → 온보딩을 헤드리스 브라우저에서 실행, 각 단계마다 상태 검증
- checkout-verifier — Stripe 테스트 카드로 결제 UI를 구동하고 인보이스가 맞는 상태에 도달했는지 확인
- tmux-cli-driver — TTY가 필요한 대화형 CLI 테스트용
"데이터를 어디서 어떻게 가져오는지"를 가르치는 스킬.
회사의 데이터 스택, 모니터링 도구에 연결하는 거예요. 접속 정보, 대시보드 ID, 일반적인 분석 워크플로우를 스킬에 담습니다.
"가입부터 결제까지 퍼널을 보려면 어떤 테이블의 어떤 이벤트를 조인해야 하는지" + 실제 user_id가 들어있는 캐노니컬 테이블이 뭔지. 이런 걸 스킬에 넣어두면 Claude가 매번 "그 테이블 이름이 뭐였죠?"라고 물을 필요가 없어요.
예시:
- funnel-query — 가입 → 활성화 → 결제 퍼널의 이벤트 조인 방법 + 캐노니컬 user_id 테이블
- cohort-compare — 두 코호트의 리텐션/전환율 비교, 통계적 유의성 표시
- grafana — 데이터소스 UID, 클러스터 이름, "이 문제면 이 대시보드" 매핑
매일 반복하는 업무를 한 커맨드로 자동화하는 스킬.
스탠드업 포스트 스킬을 예로 들어볼게요. 티켓 트래커에서 내 할당 업무를 가져오고, GitHub에서 어제 커밋 내역을 모으고, Slack에서 관련 대화를 긁어서 포맷에 맞게 정리합니다. 이전 스탠드업과 비교해서 "어제 대비 뭐가 바뀌었는지"만 보여주는 delta-only 방식.
팁이 하나 있어요. 이런 스킬은 이전 실행 결과를 로그 파일에 저장해두면, Claude가 "지난번에 뭘 했는지"를 읽고 일관성을 유지할 수 있대요.
예시:
- standup-post — 티켓 + GitHub + Slack 집계 → 포맷된 스탠드업(delta-only)
- create-ticket — 스키마 강제(유효한 값, 필수 필드) + 생성 후 워크플로우(리뷰어 핑, Slack 링크)
- weekly-recap — 머지된 PR + 닫힌 티켓 + 배포 → 주간 요약
새 기능을 만들 때 뼈대를 자동 생성하는 스킬.
"새 API 엔드포인트 만들어줘"라고 하면, 우리 조직의 인증 방식, 로깅 설정, 배포 구성이 미리 연결된 상태로 파일 구조를 잡아주는 거예요. 순수 코드 제너레이터로는 커버 안 되는 자연어 요구사항("이 서비스는 이런 컨벤션을 따라야 해")이 있을 때 특히 유용합니다.
예시:
- new-workflow — 조직의 어노테이션이 포함된 새 서비스/핸들러 스캐폴딩
- new-migration — 마이그레이션 파일 템플릿 + 일반적인 함정
- create-app — 인증, 로깅, 배포 설정이 미리 연결된 새 내부 앱
조직의 코드 품질 기준을 강제하는 스킬.
재밌는 예가 있어요. adversarial-review 스킬. 서브에이전트를 하나 더 띄워서 "처음 보는 사람의 눈"으로 코드를 비판하게 합니다. 지적 사항을 수정하고, 다시 리뷰하고, 지적이 사소한 수준(nitpick)까지 내려갈 때까지 반복.
훅이나 GitHub Action에 연결해서 자동 실행되게 할 수도 있어요.
예시:
- adversarial-review — 서브에이전트가 비판 → 수정 → 반복, 지적이 사소해질 때까지
- code-style — Claude가 기본적으로 잘 못하는 코드 스타일 강제
- testing-practices — 테스트 작성법과 무엇을 테스트해야 하는지 안내
코드를 빌드하고 테스트하고 배포하는 과정을 자동화하는 스킬.
babysit-pr 스킬이 대표적이에요. PR을 올리면 CI가 돌아가잖아요. 가끔 환경 문제로 무작위 실패하는 불안정한 테스트가 있는데, 이 스킬이 알아서 재시도하고, 머지 충돌이 생기면 해결하고, 문제없으면 오토 머지까지 켜줍니다.
배포 스킬은 더 정교해요. 빌드 → 스모크 테스트 → 트래픽 점진적 롤아웃 → 에러율 비교 → 리그레션 시 자동 롤백. 사람이 붙어서 모니터링하던 걸 스킬이 대신합니다.
예시:
- babysit-pr — PR 모니터링 → 불안정 CI 재시도 → 머지 충돌 해결 → 오토 머지
- deploy-service — 빌드 → 스모크 테스트 → 점진적 트래픽 → 에러 시 자동 롤백
- cherry-pick-prod — 격리된 워크트리 → 체리픽 → 충돌 해결 → 템플릿 PR
"이런 증상이 나타나면 이렇게 조사해라"를 자동화한 스킬.
장애가 나면 보통 이래요. Slack에서 알림 → 로그 확인 → 관련 시스템 확인 → 원인 파악 → 보고서. 런북 스킬은 이 전체를 자동화합니다.
요청 ID 하나를 주면 그 요청이 지나간 모든 시스템에서 매칭 로그를 뽑아서 하나로 모아주는 log-correlator 같은 거예요.
예시:
- service-debugging — 고트래픽 서비스의 증상 → 도구 → 쿼리 패턴 매핑
- oncall-runner — 알림 → 일반적 원인 확인 → 발견 사항 포맷팅
- log-correlator — 요청 ID → 모든 시스템에서 매칭 로그 추출
정기 유지보수와 운영 절차를 자동화하는 스킬. 특히 "실수하면 큰일 나는" 파괴적 작업에 가드레일을 다는 용도예요.
고아 상태(아무도 안 쓰는) 쿠버네티스 파드나 볼륨을 찾아서 → Slack에 알리고 → 며칠 기다리고(혹시 누가 쓰는지) → 사용자가 확인하면 → 정리. 자동이되 사람의 확인을 거치는 구조.
예시:
- resource-orphans — 고아 파드/볼륨 탐색 → Slack 알림 → 대기 → 확인 → 정리
- dependency-management — 조직의 의존성 승인 워크플로우
- cost-investigation — "왜 스토리지 비용이 급증했나" + 특정 버킷과 쿼리 패턴
Claude는 코딩에 대해 이미 많이 알아요. "변수명은 의미 있게 지어라" 같은 일반 상식을 스킬에 적으면 토큰만 낭비됩니다.
스킬에는 Claude가 평소에 모르거나 틀리는 것만 적어야 해요.
frontend-design 스킬이 좋은 예예요. Anthropic의 한 엔지니어가 고객 피드백을 반복 반영하면서 만들었는데, Claude가 기본적으로 쓰는 Inter 폰트, 보라색 그라데이션 같은 "AI 티 나는 패턴"을 피하게 한 거예요. "일반적인 좋은 디자인"이 아니라 "Claude가 구체적으로 틀리는 부분"에 집중한 겁니다.
모든 스킬에서 가장 가치 있는 부분이 뭐냐고 물었더니 Anthropic의 답은 Gotchas 섹션이래요.
Gotchas는 "Claude가 이 스킬을 쓸 때 자주 빠지는 함정" 목록이에요. 처음에는 하나둘로 시작하지만, Claude가 새 엣지 케이스를 만날 때마다 추가합니다.
이게 스킬의 진짜 성장 방식이에요. 완벽하게 만들어서 배포하는 게 아니라, 실패할 때마다 Gotchas에 한 줄 추가하는 것.
스킬은 폴더라고 했죠. 이걸 제대로 쓰면 "점진적 공개(Progressive Disclosure)"가 가능해요.
모든 정보를 한꺼번에 보여주지 않고, 필요할 때만 꺼내 보는 거예요.
SKILL.md— 핵심 지침만references/api.md— 상세한 API 사용법assets/— 출력 템플릿examples/— 예제 코드
Claude에게 "이 파일들이 있으니 필요하면 읽어"라고 알려주면 적절한 타이밍에 가져옵니다. 하나의 마크다운에 전부 때려넣으면 매번 모든 걸 읽어야 하니까 토큰이 낭비돼요.
스킬은 재사용되는 거잖아요. 지시사항이 너무 구체적이면 상황이 조금만 달라져도 안 맞습니다.
- 나쁜 예: "반드시 A를 호출하고, 그 다음 B를 호출하고, 결과를 C 형식으로 저장하라"
- 좋은 예: "이 함수들이 있고, 각각의 용도는 이렇다. 상황에 맞게 조합해서 써라"
필요한 정보를 주되, 판단의 유연성을 남겨두라는 거예요.
어떤 스킬은 처음에 사용자한테 물어봐야 할 게 있어요. "스탠드업을 어느 Slack 채널에 올릴까요?" 같은 거.
좋은 패턴은 스킬 폴더 안에 config.json을 두는 거예요. 설정 파일이 비어있으면 Claude가 사용자에게 질문합니다. 답을 받아서 저장하면 다음부터는 묻지 않아요.
구조화된 객관식 질문을 제시하고 싶으면 Claude에게 AskUserQuestion 도구를 쓰라고 지시하면 됩니다.
세션이 시작되면 Claude Code는 설치된 모든 스킬의 description을 스캔해서 "이 요청에 맞는 스킬이 있나?"를 판단해요.
그러니까 description은 요약이 아닙니다. "이 스킬을 언제 호출해야 하는지"를 적는 트리거 조건이에요.
- 나쁜 예: "코드 리뷰를 도와주는 스킬입니다"
- 좋은 예: "PR이 올라왔을 때 보안 취약점, 누락된 테스트, 동작 리그레션을 검토합니다. 사용자가 '리뷰해줘', 'PR 체크'라고 말할 때 호출."
이 차이가 스킬이 제때 불리느냐 마느냐를 결정합니다.
스킬 안에 데이터를 저장할 수 있어요. 단순한 텍스트 로그, JSON, 심지어 SQLite까지.
standup-post 스킬이 매일 standups.log에 기록을 남기면, 다음에 실행할 때 Claude가 이전 기록을 읽고 "어제 대비 뭐가 바뀌었는지"를 알 수 있어요.
주의: 스킬 업그레이드 시 디렉토리가 삭제될 수 있어요.
${CLAUDE_PLUGIN_DATA}같은 안정적인 경로에 저장하라고 합니다.
데이터 분석 스킬에 데이터 페칭 함수 라이브러리를 넣어두면, Claude는 매번 데이터를 가져오는 코드를 처음부터 쓰는 대신, 이 함수들을 조합해서 분석하는 데 집중할 수 있어요.
"화요일에 무슨 일이 있었어?"라고 물으면 Claude가 미리 준비된 함수를 조합해서 스크립트를 즉석으로 짜고 실행합니다. 보일러플레이트에 턴을 쓰지 않으니까 토큰이 줄어요.
스킬이 호출될 때만 활성화되고 세션 동안만 유지되는 훅을 넣을 수 있어요. 항상 켜두면 짜증나지만, 특정 상황에서는 꼭 필요한 것들.
- /careful —
rm -rf,DROP TABLE,force-push,kubectl delete를 전부 차단. 프로덕션 작업할 때만 켜는 거예요. 항상 켜두면 일상 작업이 불가능해집니다. - /freeze — 특정 디렉토리 이외의 파일 수정을 전부 차단. 디버깅할 때 "로그만 추가하려고 했는데 실수로 다른 파일까지 고쳐버렸다"를 방지.
두 가지 방법이 있어요.
레포에 체크인
.claude/skills/ 폴더에 넣어서 Git으로 관리. 팀 전원이 같은 스킬을 씁니다. 작은 팀에 적합. 단점은 스킬이 많아지면 전부 Claude 컨텍스트에 올라간다는 것.
사내 플러그인 마켓플레이스 규모가 커지면 이쪽. 팀원이 필요한 스킬만 골라서 설치하는 구조.
Anthropic의 마켓플레이스 운영 방식이 재밌어요. 중앙 팀이 결정하지 않습니다.
- 스킬을 만들면 GitHub 샌드박스 폴더에 올림
- Slack에서 "이거 써봐" 하고 공유
- 견인력이 생기면(스킬 오너가 판단) 마켓플레이스에 PR
유기적으로 떠오르게 하는 거예요. 경고도 하나 남겼습니다.
"나쁘거나 중복된 스킬을 만드는 건 쉽다. 릴리스 전에 큐레이션 과정이 반드시 필요하다."
Anthropic은 PreToolUse 훅으로 사내 스킬 사용량을 로깅하고 있대요. 어떤 스킬이 많이 쓰이는지, 기대보다 호출이 적은 건 뭔지 데이터로 파악합니다.
기대보다 안 쓰이면 description(트리거 조건)을 다시 쓰고, 인기 있는 스킬은 더 다듬고.