Claude Code Skills 실전 가이드: Anthropic이 수백 개 스킬을 운용하며 배운 것들
안녕하세요, Tom입니다.
Claude Code를 쓰다 보면 Skills라는 개념을 자연스럽게 마주치게 돼요. 처음엔 단순한 마크다운 프롬프트 파일이라고 생각하기 쉬운데, 실제로 Anthropic 내부에서는 수백 개의 스킬을 운용하며 훨씬 정교하게 활용하고 있더라고요.
이번에 Anthropic이 공유한 실전 가이드를 보면서, Skills가 얼마나 강력한 확장 포인트인지 새삼 깨달았어요. 어떤 내용들이 담겨 있는지 하나씩 살펴볼게요.
Skills는 폴더다
가장 먼저 인식을 바꿔야 할 부분이에요. Skills는 단순한 .md 파일 하나가 아니라, 스크립트, 에셋, 데이터를 포함하는 폴더 구조예요.
.claude/commands/my-skill/
├── SKILL.md # 스킬 설명 및 지시사항
├── setup.sh # 환경 설정 스크립트
├── templates/ # 코드 템플릿
├── data/ # 참조 데이터
└── examples/ # 예시 파일들
이렇게 폴더로 구성하면 Claude가 스킬을 실행할 때 필요한 모든 컨텍스트를 한 곳에서 가져올 수 있어요. 마크다운 하나에 모든 걸 우겨넣는 것과는 차원이 다른 접근이죠.
9가지 스킬 카테고리
Anthropic이 내부에서 운용하는 스킬들을 분류하면 크게 9가지 카테고리로 나뉘어요.
1. 라이브러리 레퍼런스
특정 라이브러리나 프레임워크의 API 문서, 사용 패턴, 버전별 변경사항을 담은 스킬이에요. Claude가 최신 API를 정확하게 사용하도록 도와줘요.
2. 제품 검증
PR을 올리기 전에 제품 요구사항을 충족하는지 자동으로 체크하는 스킬이에요. QA 팀의 체크리스트를 코드화한 거라고 보면 돼요.
3. 데이터 수집/분석
로그 파싱, 메트릭 집계, A/B 테스트 결과 분석 같은 데이터 작업을 자동화하는 스킬이에요.
4. 비즈니스 프로세스 자동화
온보딩 문서 생성, 릴리스 노트 작성, 이슈 트리아지 같은 반복적인 비즈니스 프로세스를 자동화해요.
5. 코드 스캐폴딩
새로운 서비스, 컴포넌트, 테스트 파일을 팀의 컨벤션에 맞게 자동 생성하는 스킬이에요. 보일러플레이트 코드를 일일이 작성할 필요가 없어지죠.
6. 코드 품질
린팅 규칙, 코드 리뷰 가이드라인, 보안 체크리스트를 강제하는 스킬이에요.
7. CI/CD 배포
빌드, 테스트, 배포 파이프라인을 관리하고 모니터링하는 스킬이에요.
8. Runbooks
장애 대응, 롤백 절차, 인시던트 관리 같은 운영 매뉴얼을 실행 가능한 형태로 담은 스킬이에요.
9. 인프라 운영
클라우드 리소스 프로비저닝, 모니터링 설정, 스케일링 정책 관리를 위한 스킬이에요.
🎯 핵심 작성 팁
Anthropic이 수백 개의 스킬을 운용하며 찾아낸 핵심 노하우들이에요. 이 부분이 이 가이드에서 가장 가치 있는 내용이라고 생각해요.
Gotchas 섹션이 가장 높은 신호 가치
스킬을 작성할 때 "이렇게 하세요"보다 "이건 절대 하지 마세요"가 훨씬 효과적이에요. Claude는 일반적인 지시사항은 어느 정도 스스로 추론할 수 있지만, 프로젝트 고유의 함정(gotchas)은 명시적으로 알려줘야 하거든요.
## ⚠️ Gotchas
- 절대로 `user.email`을 로깅하지 마세요. PII 규정 위반입니다.
- `DatabasePool.connect()`는 반드시 `try/finally`로 감싸세요.
풀이 고갈되면 전체 서비스가 멈춥니다.
- v3 API에서 `createdAt`은 UTC가 아니라 사용자 타임존입니다.
반드시 `toUTC()`를 호출하세요.이런 Gotchas 섹션 하나가 10줄짜리 일반 지시사항보다 Claude의 출력 품질을 훨씬 높여줘요.
파일 시스템을 컨텍스트 엔지니어링 수단으로 활용
스킬 폴더 안에 예시 코드, 테스트 케이스, 설정 파일을 배치하면 Claude가 자연스럽게 참조해요. 프롬프트에 모든 걸 텍스트로 설명하는 것보다, 실제 파일을 보여주는 게 훨씬 정확한 결과를 만들어 내요.
.claude/commands/api-endpoint/
├── SKILL.md
├── examples/
│ ├── good-endpoint.ts # 모범 사례
│ └── bad-endpoint.ts # 안티패턴 (주석으로 설명)
└── templates/
└── endpoint.ts.hbs # 기본 템플릿
점진적 공개 (Progressive Disclosure)
스킬 문서를 한 번에 다 보여주지 말고, 단계별로 필요한 정보만 제공하세요. Claude의 컨텍스트 윈도우를 효율적으로 사용하는 핵심 전략이에요.
## 기본 사용법
(여기에 핵심 내용)
## 고급 옵션
자세한 내용은 `./advanced-options.md`를 참조하세요.이렇게 하면 기본 작업에서는 가벼운 컨텍스트로 빠르게 처리하고, 복잡한 작업에서만 추가 파일을 로드해요.
CLAUDE_PLUGIN_DATA로 세션 간 메모리 구현
v2.1.78에서 추가된 CLAUDE_PLUGIN_DATA 변수를 활용하면 스킬이 세션 간에 상태를 유지할 수 있어요. 예를 들어, 이전 세션에서 사용자가 선호하는 코드 스타일이나 자주 사용하는 설정값을 기억해 두고 다음 세션에서 자동으로 적용하는 거죠.
## 상태 저장
작업이 완료되면 결과를 CLAUDE_PLUGIN_DATA/state.json에 저장하세요.
다음 실행 시 이 파일이 존재하면 이전 상태를 복원합니다.이건 정말 게임 체인저예요. 스킬이 단발성 스크립트가 아니라 지속적으로 학습하고 개선되는 도구가 될 수 있거든요.
배포 전략
소규모 팀: 리포에 체크인
5~10명 정도의 팀이라면 .claude/commands/ 디렉토리에 스킬을 직접 체크인하는 게 가장 간단해요. 코드 리뷰를 통해 스킬의 품질도 관리할 수 있고, 버전 관리도 자연스럽게 되죠.
my-project/
├── .claude/
│ └── commands/
│ ├── deploy/
│ ├── review/
│ └── scaffold/
├── src/
└── ...
대규모 조직: 내부 플러그인 마켓플레이스
수십~수백 명이 넘어가면 각 팀이 독립적으로 스킬을 개발하고 공유할 수 있는 내부 마켓플레이스를 활용하는 게 효율적이에요. Anthropic 내부에서도 이 방식을 사용하고 있다고 해요.
마켓플레이스를 통해 검증된 스킬을 팀 간에 공유하면 중복 개발을 줄이고, 베스트 프랙티스를 조직 전체로 확산시킬 수 있어요.
💡 PreToolUse 훅으로 스킬 사용량 로깅
스킬이 많아지면 "어떤 스킬이 실제로 많이 쓰이는지"를 파악하는 게 중요해져요. PreToolUse 훅을 활용하면 스킬 호출을 자동으로 로깅할 수 있어요.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Skill",
"command": "echo \"$(date) | $SKILL_NAME\" >> ~/.claude/skill-usage.log"
}
]
}
}이 데이터를 모으면 어떤 스킬에 투자해야 하는지, 어떤 스킬은 폐기해도 되는지 데이터 기반으로 판단할 수 있어요.
Tom의 생각
이 가이드를 읽으면서 가장 인상 깊었던 건 Gotchas 섹션의 중요성이에요. 저도 Claude Code 스킬을 몇 개 만들어 봤는데, "이렇게 해줘"라는 지시보다 "이건 하지 마"라는 제약이 출력 품질에 훨씬 큰 영향을 미치더라고요.
그리고 파일 시스템을 컨텍스트 엔지니어링 수단으로 활용한다는 발상이 정말 좋아요. 프롬프트 엔지니어링에만 집중하다 보면 텍스트로 모든 걸 설명하려고 하는데, 실제 코드 파일을 보여주는 게 훨씬 효과적이라는 건 실전에서 배우는 깨달음이죠.
CLAUDE_PLUGIN_DATA를 활용한 세션 간 메모리도 기대돼요. 이 블로그의 /publish 워크플로우에도 이전 발행 기록을 기억하게 만들면 더 일관된 품질의 포스트를 만들 수 있을 것 같거든요.
Claude Code를 단순한 코딩 도우미가 아니라 팀의 지식과 프로세스를 담는 플랫폼으로 활용하는 시대가 정말 오고 있네요. 여러분도 팀에서 반복하는 작업이 있다면, 스킬로 만들어 보시는 건 어떨까요?
다음에 또 유용한 소식으로 찾아올게요!