Claude Code를 만든 사람들이 자기네 팀에서 스킬을 어떻게 쓰는지 공개했어요. 그냥 "이렇게 만들면 좋다" 수준이 아니라, 수백 개의 스킬을 실전에서 돌리면서 뭐가 되고 뭐가 안 되는지를 정리한 거예요. 글을 쓴 건 Thariq Shihipar — Claude Code 팀 엔지니어이자, "Claude Code is All You Need"로 120만 뷰를 찍은 사람이에요.
이게 뭔데?
Anthropic은 사내에서 Claude Code를 개발하면서 동시에 자기들이 가장 큰 사용자이기도 해요. 9개 팀 — 보안, 법무, 인프라, 프론트엔드, 데이터 등 — 이 각자의 스킬을 만들어 쓰고 있고, 그 수가 수백 개에 달해요.
이번에 공개된 건 크게 두 가지예요. 첫째, Claude Code 공식 문서에 추가된 Best Practices와 Skills 가이드. 둘째, Thariq가 X에서 공유한 사내 운용 경험이에요. 기존에 있던 33페이지 PDF 가이드가 "스킬을 어떻게 만드는가"였다면, 이건 "수백 개를 실전에서 굴려보니 이게 진짜 중요하더라"는 이야기예요.
핵심 메시지는 명확해요 — 스킬의 성패는 작성 전 설계에서 거의 결정된다. 코드를 한 줄도 안 쓰고 use case 3개를 먼저 정의하라는 거예요.
뭐가 달라지는 건데?
기존 33페이지 가이드는 "스킬이란 이런 거고 이렇게 만들어라"였어요. 이번 공개는 레벨이 다릅니다 — 실전에서 뭐가 되고 뭐가 안 되는지, 그리고 팀 규모에서 어떻게 관리하는지를 다뤄요.
| 기존 33p 가이드 | 사내 플레이북 (이번 공개) | |
|---|---|---|
| 초점 | 스킬 개념과 만드는 법 | 수백 개 운용하며 배운 패턴과 안티패턴 |
| 설계 원칙 | SKILL.md 포맷 설명 | use case 3개 먼저 → 그다음 작성 |
| 품질 관리 | 기본 테스트 언급 | 트리거/기능/성능 3단계 검증 체계 |
| 팀 공유 | 경로만 언급 | Enterprise → Personal → Project 우선순위 체계 + 플러그인 배포 |
| 컨텍스트 관리 | 간략히 언급 | character budget 2% 규칙 + 500줄 상한 + progressive disclosure |
| 트리거 제어 | 기본 설명 | Hook으로 강제 트리거 + disable-model-invocation 분리 |
특히 인상적인 건 70% 규칙이에요. Anthropic 내부 팀들에서 공통적으로 나타나는 패턴인데 — Claude Code가 구현 작업의 약 70%를 안정적으로 처리하고, 나머지 30%를 사람이 한다는 거예요. 이 30%가 바로 스킬의 설계, 검증 루프, 엣지 케이스 처리예요.
핵심만 정리: 시작하는 법
- Use Case 3개부터 정의하기
스킬을 만들기 전에, "누가, 뭘 말하면, 어떤 결과가 나와야 하는지"를 3개 시나리오로 적어보세요. Anthropic은 이 단계를 건너뛰면 스킬 품질이 극적으로 떨어진다고 말해요.시나리오 예시: "PR 리뷰해줘" → 3개 병렬 에이전트로 보안/코드품질/효율성 검토 → 통합 리포트 - description을 정밀하게 작성하기
Claude는 스킬을 "progressive disclosure"로 로드해요. 먼저 name + description만 시스템 프롬프트에 올리고(약 100토큰), 사용자 요청이 매칭되면 그때 SKILL.md 전문을 읽어요. description이 모호하면 트리거가 안 되고, 너무 넓으면 엉뚱한 때 발동돼요. - 검증 루프를 body에 넣기
Anthropic이 가장 강조하는 부분이에요. 실행 → 검증 → 수정 → 재검증 루프를 스킬 본문에 체크리스트로 넣으세요. 예를 들어 코드 생성 스킬이라면 "생성 후 lint 실행 → 테스트 실행 → 실패 시 수정 → 재실행"을 명시적으로 적어야 해요. - 500줄 이하로 유지하기
SKILL.md가 길어지면 Claude가 지시를 놓쳐요. 상세 내용은 references/ 폴더에 분리하고, SKILL.md는 목차와 핵심 지침만 남기세요. 참조 파일이 길면 맨 위에 목차를 넣어야 Claude가 head -100으로 읽을 때 구조를 파악해요. - 팀에 공유하기
스킬을.claude/skills/에 넣고 git에 커밋하면 팀 전체가 씁니다. 개인용은~/.claude/skills/, 조직 전체는 managed settings로 배포할 수 있어요. 우선순위는 Enterprise > Personal > Project 순이에요.
Anthropic이 실전에서 배운 5가지 교훈
공식 문서와 Thariq의 공유에서 추출한, 수백 개 스킬을 운용하며 얻은 핵심 교훈들이에요.
교훈 1: SKILL.md body에 "When to Use"를 쓰지 마라
description에서 이미 트리거 판단이 끝나고 body가 로드되는 시점이에요. body에 "이 스킬은 ~할 때 사용합니다"를 쓰면 이미 발동된 후에 읽히는 거라 컨텍스트만 낭비해요. body에는 "어떻게 실행하는가"만 적으세요.
교훈 2: 사이드 이펙트가 있는 스킬은 반드시 수동 트리거로
disable-model-invocation: true를 설정하세요. 배포, 커밋, 슬랙 메시지 전송 같은 스킬은 Claude가 "코드가 준비된 것 같으니 배포할게요"라고 자동 실행하면 안 돼요.
교훈 3: 스킬이 너무 많으면 아무것도 안 된다
Claude는 스킬 목록을 컨텍스트 윈도우의 2% 예산(최소 16,000자) 안에서 관리해요. 스킬이 이 예산을 넘으면 일부가 아예 제외돼요. /context로 확인할 수 있어요.
교훈 4: Hook으로 트리거 확률을 높여라
스킬이 안 불리는 가장 큰 이유는 Claude가 description을 못 매칭하는 거예요. 이때 Hook을 쓰면 사용자 입력에 스킬 추천을 직접 덧붙일 수 있어요 — "기능 구현 좀 도와줘"에 "CRITICAL SKILLS: session-management"를 자동 삽입하는 식이에요.
교훈 5: context: fork로 메인 컨텍스트를 보호하라
리서치나 리뷰 같은 스킬은 파일을 많이 읽어서 메인 컨텍스트를 오염시켜요. context: fork를 설정하면 서브에이전트에서 격리 실행되고, 결과 요약만 돌아와요.
실전 스킬 구조 예시
Anthropic이 실제로 사용하는 패턴을 기반으로, 팀 규모에서 효과적인 스킬 구조를 정리했어요.
| 스킬 유형 | 예시 | 핵심 설정 | 위치 |
|---|---|---|---|
| 레퍼런스 (지식) | api-conventions, legacy-system-context | user-invocable: false (Claude만 호출) | Project (.claude/skills/) |
| 태스크 (실행) | deploy, fix-issue, pr-summary | disable-model-invocation: true | Project (.claude/skills/) |
| 개인 워크플로 | explain-code, debug-session | 기본값 (자동+수동 모두) | Personal (~/.claude/skills/) |
| 조직 표준 | code-review, security-audit | managed settings로 배포 | Enterprise |
여기서 핵심은 "레퍼런스 스킬"과 "태스크 스킬"을 명확히 분리하는 것이에요. 레퍼런스는 Claude가 맥락으로 쓰는 지식이고, 태스크는 사용자가 명시적으로 실행하는 워크플로예요. 이걸 섞으면 스킬이 엉뚱한 때 발동하거나, 필요할 때 안 불려요.
기존 claude-skills-guide 포스트와의 차이
이전 포스트(Claude Skills 33페이지 가이드 완전 정리)는 Anthropic이 공개한 PDF 가이드를 다뤘어요 — 스킬의 개념, SKILL.md 작성법, 기본 구조 설명이 중심이었어요. 이 포스트는 그 이후에 나온 사내 실전 경험을 다뤄요. 공식 문서 업데이트 + Thariq의 X 스레드 + 커뮤니티 분석을 종합한 거예요.
