Anthropic제품 블로그Claude Code
Claude Code 개발기: 스킬 활용의 핵심 원칙
Anthropic 내부에서 수백 개의 스킬을 직접 구축하고 확장하며 얻은 교훈을 정리했습니다.
스킬(Skill)은 Claude Code에서 가장 많이 활용되는 확장 기능 중 하나입니다. 유연하고 만들기 쉬우며 배포도 간편합니다.
하지만 바로 그 유연성 때문에 무엇이 효과적인지 판단하기가 쉽지 않습니다. 어떤 종류의 스킬을 만들 가치가 있을까요? 스킬은 어떻게 구성해야 할까요? 언제 다른 사람들과 공유해야 할까요?
Anthropic에서는 수백 개의 스킬을 Claude Code에 적극적으로 활용하고 있습니다. 이 글은 스킬을 통해 개발 속도를 높이면서 쌓은 노하우를 정리한 것입니다.
스킬이란 무엇인가?
스킬은 에이전트(agent)가 발견하고 활용할 수 있는 지침, 스크립트, 리소스의 모음으로, 작업을 더 정확하고 효율적으로 수행할 수 있도록 돕습니다. 이 글은 스킬의 기본 개념을 알고 있다는 전제 하에 작성되었습니다. 처음 접하는 분이라면 Skilljar의 에이전트 스킬 입문 강좌부터 시작해 보세요.
스킬에 대한 흔한 오해 중 하나는 "마크다운 파일에 불과하다"는 것입니다. 실제로는 에이전트가 탐색하고 조작할 수 있는 스크립트, 에셋, 데이터 등을 포함한 폴더 구조입니다.
Claude Code에서 스킬은 동적 훅(hook) 등록을 비롯한 다양한 설정 옵션을 지원합니다.
실제로 Claude Code에서 효과적인 스킬일수록 이러한 설정 옵션과 폴더 구조를 잘 활용하고 있었습니다.
스킬의 유형
Anthropic 내부 스킬 전체를 분류해보니 크게 아홉 가지 범주로 나뉘었습니다. 잘 만들어진 스킬은 하나의 범주에 명확히 속했고, 너무 많은 것을 하려는 스킬은 여러 범주에 걸쳐 있어 에이전트를 혼란스럽게 만들었습니다. 이것이 완벽한 분류 체계는 아니지만, 자신의 스킬 라이브러리에서 빈 곳을 파악하는 데 유용한 프레임워크가 될 것입니다.
1. 라이브러리 및 API 레퍼런스
라이브러리, CLI, SDK의 올바른 사용법을 설명하는 스킬입니다. 내부 라이브러리는 물론, Claude Code가 다루기 어려워하는 외부 라이브러리에도 적용할 수 있습니다. 이 유형의 스킬에는 참고용 코드 스니펫 모음과 Claude가 스크립트 작성 시 피해야 할 함정(gotchas) 목록이 자주 포함됩니다.
예시:
billing-lib— 내부 빌링 라이브러리: 엣지 케이스, 주의해야 할 함정 등internal-platform-cli— 내부 CLI 래퍼의 모든 서브커맨드와 사용 예시sandbox-proxy— 개발 환경에서 조직의 이그레스 게이트웨이 설정: 접근 가능한 호스트, "connection refused" 오류 디버깅 방법, 허용 목록 추가 방법
2. 제품 검증
코드가 제대로 동작하는지 테스트하고 검증하는 방법을 기술하는 스킬입니다. Playwright, tmux 등 외부 도구와 함께 활용하는 경우가 많습니다.
검증 스킬은 내부적으로 Claude의 결과물 품질에 가장 측정 가능한 영향을 미쳤습니다. 엔지니어 한 명이 일주일을 투자해 검증 스킬을 고도화하는 것도 충분히 가치 있는 일입니다.
효과적인 기법으로는 Claude가 테스트한 내용을 직접 확인할 수 있도록 출력 결과를 영상으로 녹화하거나, 각 단계마다 상태에 대한 프로그래매틱 어서션(assertion)을 적용하는 방식이 있습니다. 이는 스킬에 다양한 스크립트를 포함하는 방식으로 구현합니다.
예시:
signup-flow-driver— 헤드리스 브라우저로 회원가입 → 이메일 인증 → 온보딩 흐름을 실행하고, 각 단계에서 상태 어서션을 수행하는 훅 포함checkout-verifier— Stripe 테스트 카드로 결제 UI를 구동하고, 인보이스가 올바른 상태로 처리되었는지 검증tmux-cli-driver— TTY가 필요한 인터랙티브 CLI 테스트용
3. 데이터 수집 및 분석
데이터 및 모니터링 스택에 연결하는 스킬입니다. 인증 정보를 포함한 데이터 조회 라이브러리, 특정 대시보드 ID 등과 함께 일반적인 데이터 조회 워크플로우에 대한 지침도 담길 수 있습니다.
예시:
funnel-query— "회원가입 → 활성화 → 결제" 흐름을 보려면 어떤 이벤트를 조인해야 하는지, 그리고 정규 user_id가 있는 실제 테이블cohort-compare— 두 코호트의 리텐션 또는 전환율 비교, 통계적으로 유의미한 차이 플래그 처리, 세그먼트 정의 링크grafana— 데이터소스 UID, 클러스터 이름, 문제별 대시보드 조회 테이블datadog— 필드 레퍼런스(@request_id vs trace_id), 서비스 목록, 메트릭 접두사 규칙
4. 비즈니스 프로세스 및 팀 자동화
반복적인 워크플로우를 단일 명령으로 자동화하는 스킬입니다. 지침 자체는 비교적 단순하지만, 다른 스킬이나 MCP에 대한 복잡한 의존 관계를 가질 수 있습니다. 이 유형의 스킬에서는 이전 실행 결과를 로그 파일로 저장해 두면 모델이 일관성을 유지하고 이전 실행 이력을 참고하는 데 도움이 됩니다.
예시:
standup-post— 티켓 트래커, GitHub 활동, 이전 Slack 메시지를 취합해 변경 사항만 포함한 스탠드업 포맷으로 정리create-<ticket-system>-ticket— 스키마 유효성 검사(유효한 enum 값, 필수 필드)와 생성 후 워크플로우(리뷰어 알림, Slack 링크 첨부) 적용weekly-recap— 머지된 PR, 완료된 티켓, 배포 내역 → 형식화된 회고 포스트 생성
5. 코드 스캐폴딩 및 템플릿
코드베이스의 특정 기능에 맞는 프레임워크 보일러플레이트를 생성하는 스킬입니다. 조합 가능한 스크립트와 함께 활용할 수 있으며, 순수 코드만으로는 표현하기 어려운 자연어 요구사항이 있는 스캐폴딩에 특히 유용합니다.
예시:
new-<framework>-workflow— 조직의 어노테이션이 적용된 새 서비스/워크플로우/핸들러 스캐폴딩new-migration— 마이그레이션 파일 템플릿 및 주요 함정 목록create-app— 인증, 로깅, 배포 설정이 사전 구성된 새 내부 앱
6. 코드 품질 및 리뷰
조직 내 코드 품질 기준을 적용하고 코드 리뷰를 돕는 스킬입니다. 높은 안정성을 위해 결정론적 스크립트나 도구를 포함할 수 있으며, 훅이나 GitHub Action의 일부로 자동 실행하는 것도 고려해 볼 수 있습니다.
adversarial-review— 새로운 시각으로 코드를 검토하는 서브에이전트를 생성해 비판하고, 수정 사항을 구현하며, 지적 사항이 사소한 수준이 될 때까지 반복code-style— 코드 스타일 적용, 특히 Claude가 기본적으로 잘 따르지 않는 스타일 규칙testing-practices— 테스트 작성 방법 및 테스트 대상에 대한 지침
7. CI/CD 및 배포
코드베이스에서 코드를 가져오고, 푸시하고, 배포하는 작업을 돕는 스킬입니다. 데이터 수집을 위해 다른 스킬을 참조하는 경우도 있습니다.
예시:
babysit-pr— PR 모니터링 → 불안정한 CI 재시도 → 머지 충돌 해결 → 자동 머지 활성화deploy-<service>— 빌드 → 스모크 테스트 → 단계적 트래픽 전환과 오류율 비교 → 회귀 시 자동 롤백cherry-pick-prod— 격리된 워크트리 → 체리픽 → 충돌 해결 → 템플릿 기반 PR 생성
8. 런북
증상(Slack 스레드, 알림, 오류 시그니처 등)을 입력받아 멀티 툴 조사 과정을 거쳐 구조화된 리포트를 생성하는 스킬입니다.
예시:
<service>-debugging— 트래픽이 높은 서비스에 대한 증상별 도구 및 쿼리 패턴 매핑oncall-runner— 알림 조회 → 주요 의심 요소 확인 → 발견 내용 포맷 정리<resource>-orphans— 요청 ID를 입력하면 해당 요청이 거쳐간 모든 시스템에서 관련 로그를 수집
9. 인프라 운영
정기적인 유지보수 및 운영 절차를 수행하는 스킬로, 파괴적인 작업이 포함될 수 있어 가드레일(guardrail)이 필요한 경우가 많습니다. 중요한 운영 작업에서 엔지니어가 모범 사례를 쉽게 따를 수 있도록 도와줍니다.
예시:
<resource>-orphans— 고아 파드/볼륨 탐지 → Slack 알림 → 유예 기간 → 사용자 확인 → 연쇄 정리dependency-management— 조직의 의존성 승인 워크플로우cost-investigation— "스토리지/이그레스 비용이 왜 급증했는가"를 특정 버킷과 쿼리 패턴 기준으로 분석
스킬 제작 팁
만들 스킬을 결정했다면, 어떻게 작성해야 할까요? Claude Code 팀이 정리한 스킬 제작 모범 사례와 팁을 소개합니다.
당연한 내용은 쓰지 마세요
Claude는 이미 코딩 방법을 알고 있고 코드베이스도 직접 읽을 수 있습니다. Claude가 기본적으로 하는 행동을 반복하는 스킬은 컨텍스트만 늘릴 뿐 실질적인 가치가 없습니다. 지식 전달이 주목적인 스킬이라면, Claude의 기존 사고 방식에서 벗어나게 만드는 정보에 집중하세요.
프론트엔드 디자인 스킬이 좋은 예시입니다. Anthropic의 한 엔지니어가 고객들과 함께 반복적으로 개선하며 만든 이 스킬은 Inter 폰트나 보라색 그라데이션 같은 진부한 패턴을 피하는 방식으로 Claude의 디자인 감각을 끌어올립니다.
함정(Gotchas) 섹션을 만드세요
스킬에서 가장 핵심적인 내용은 함정 섹션입니다. 이 섹션은 Claude가 스킬을 사용하면서 실제로 마주친 실패 사례를 바탕으로 채워나가야 합니다. 스킬을 지속적으로 업데이트하며 새로운 함정을 꾸준히 추가하는 것이 이상적입니다.
예시:
"subscriptions 테이블은 추가 전용(append-only)입니다. 원하는 행은 가장 최근 created_at이 아니라 version이 가장 높은 행입니다." "이 필드는 API 게이트웨이에서는 @request_id , 빌링 서비스에서는 trace_id로 불립니다. 같은 값입니다." "스테이징 환경은 Stripe 웹훅이 실제로 처리되지 않았더라도 200을 반환합니다. 실제 상태는 payment_events 을 확인하세요."
파일 시스템과 점진적 공개(Progressive Disclosure)를 활용하세요
앞서 언급했듯이 스킬은 단순한 마크다운 파일이 아니라 폴더입니다. 전체 파일 시스템 구조를 컨텍스트 엔지니어링과 점진적 공개의 수단으로 활용하세요. 스킬에 어떤 파일이 있는지 Claude에게 알려주면, Claude는 적절한 시점에 해당 파일을 읽습니다.
점진적 공개의 가장 단순한 형태는 필요에 따라 다른 마크다운 파일을 참조하도록 안내하는 것입니다. 예를 들어 상세한 함수 시그니처와 사용 예시는 references/api.md로 분리할 수 있습니다.
또 다른 예로, 최종 결과물이 마크다운 파일이라면 assets/에 템플릿을 포함해 두고 복사해서 사용하게 할 수 있습니다.
레퍼런스, 스크립트, 예시 등을 담은 폴더를 구성하면 Claude가 더 효과적으로 작업할 수 있습니다.
Claude를 지나치게 통제하지 마세요
Claude는 기본적으로 지침을 충실히 따르려 합니다. 스킬은 재사용성이 높기 때문에 지침이 지나치게 구체적이면 오히려 역효과가 날 수 있습니다. 필요한 정보는 충분히 제공하되, 상황에 유연하게 대응할 수 있는 여지를 남겨두세요.
예시:
초기 설정을 고려하세요
일부 스킬은 사용자로부터 컨텍스트를 받아 초기 설정이 필요합니다. 예를 들어 스탠드업을 Slack에 게시하는 스킬이라면, 어느 채널에 올릴지 Claude가 물어보도록 구성할 수 있습니다.
이를 위한 좋은 패턴은 위 예시처럼 스킬 디렉토리에 config.json 파일로 설정 정보를 저장하는 것입니다. 설정이 되어 있지 않으면 에이전트가 사용자에게 필요한 정보를 물어볼 수 있습니다.
구조화된 객관식 질문을 제시하고 싶다면 Claude에게 AskUserQuestion 도구를 사용하도록 지시할 수 있습니다.
설명은 사람이 아닌 모델을 위해 작성하세요
Claude Code는 세션 시작 시 사용 가능한 모든 스킬과 설명 목록을 구성합니다. Claude는 이 목록을 보고 "이 요청에 맞는 스킬이 있는가?"를 판단합니다. 즉, 설명 필드는 스킬의 요약이 아니라 언제 이 스킬을 실행할지를 알려주는 트리거 역할을 합니다.
Claude가 기억할 수 있도록 도와주세요
일부 스킬은 데이터를 스킬 내부에 저장하는 방식으로 일종의 메모리 기능을 구현할 수 있습니다. 단순한 추가 전용 텍스트 로그 파일이나 JSON 파일부터 SQLite 데이터베이스까지 다양한 방식을 활용할 수 있습니다.
예를 들어 standup-post 스킬이 작성한 모든 스탠드업을 standups.log에 남겨두면, 다음 실행 시 Claude가 자신의 이력을 읽고 어제와 달라진 점을 파악할 수 있습니다.
데이터를 저장할 안정적인 디렉토리는 환경 변수 ${CLAUDE_PLUGIN_DATA} 를 통해 얻을 수 있습니다. 스킬에서 데이터를 영속적으로 저장하는 방법은 여기서 자세히 확인하세요: https://code.claude.com/docs/en/plugins-reference#persistent-data-directory.
스크립트를 저장하고 코드를 생성하세요
Claude에게 줄 수 있는 가장 강력한 도구 중 하나는 코드입니다. 스크립트와 라이브러리를 제공하면 Claude는 보일러플레이트를 다시 작성하는 대신 조합(composition)과 다음 행동 결정에 집중할 수 있습니다.
예를 들어 data-science 스킬에 이벤트 소스에서 데이터를 가져오는 함수 라이브러리가 있다면, 복잡한 분석을 위해 다음과 같은 헬퍼 함수를 제공할 수 있습니다:
그러면 Claude는 "지난 화요일에 무슨 일이 있었나요?"와 같은 요청에 대해 이 기능들을 즉석에서 조합한 스크립트를 생성해 더 고도화된 분석을 수행할 수 있습니다.
온디맨드 훅을 활용하세요
스킬에는 스킬이 호출될 때만 활성화되고 세션이 끝나면 해제되는 훅을 포함할 수 있습니다. 항상 실행하기엔 부담스럽지만 특정 상황에서는 매우 유용한 훅에 활용하세요.
예시:
/careful/freeze— 특정 디렉토리 외의 Edit/Write 차단. 디버깅 중 "로그만 추가하고 싶은데 관련 없는 코드까지 수정하게 된다"는 상황에 유용합니다.
스킬 배포하기
스킬의 가장 큰 장점 중 하나는 팀원들과 쉽게 공유할 수 있다는 점입니다.
스킬을 공유하는 방법은 두 가지입니다:
- 스킬을 저장소에 커밋하기 (
./.claude/skills하위에 저장) - 플러그인으로 만들어 Claude Code 플러그인 마켓플레이스에 올리고 사용자가 직접 설치하도록 하기 (문서 참고)
비교적 적은 수의 저장소를 사용하는 소규모 팀이라면 저장소에 스킬을 커밋하는 방식이 잘 맞습니다. 다만 커밋된 스킬은 하나하나가 모델의 컨텍스트에 추가됩니다. 팀 규모가 커지면 내부 플러그인 마켓플레이스를 통해 스킬을 배포하고, 팀원들이 필요한 것만 선택해 설치하도록 하는 방식이 더 효과적입니다. 초기 설정 플로우도 포함할 수 있습니다.
스킬 마켓플레이스 운영하기
어떤 스킬을 마켓플레이스에 올릴지 어떻게 결정할까요? 제출 절차는 어떻게 운영할까요?
Anthropic에는 이를 결정하는 중앙화된 팀이 없습니다. 대신 유용한 스킬이 자연스럽게 떠오르는 방식을 택합니다. 공유하고 싶은 스킬이 있으면 GitHub의 샌드박스 폴더에 올린 뒤 Slack 등 사내 채널에서 사람들에게 알립니다.
스킬이 어느 정도 호응을 얻으면(기준은 스킬 소유자가 판단), 마켓플레이스로 이동하는 PR을 올립니다.
스킬 조합하기
스킬끼리 서로 의존 관계를 가질 수 있습니다. 예를 들어 파일 업로드 스킬과 CSV를 생성하고 업로드하는 스킬을 각각 만들 수 있습니다. 아직 마켓플레이스나 스킬에 의존성 관리가 기본 기능으로 내장되어 있지는 않지만, 다른 스킬의 이름을 직접 참조하면 해당 스킬이 설치되어 있을 때 모델이 자동으로 호출합니다.
스킬 측정하기
스킬의 활용도를 파악하기 위해 PreToolUse 훅으로 사내 스킬 사용 현황을 로깅합니다 (예시 코드 참고). 이를 통해 인기 있는 스킬이나 예상보다 트리거가 적은 스킬을 파악할 수 있습니다.
시작하기
스킬 모범 사례는 아직 발전하는 중입니다. 내부에서 가장 잘 활용되는 스킬 대부분이 처음에는 몇 줄짜리 지침과 함정 하나로 시작했고, Claude가 새로운 엣지 케이스를 만날 때마다 사람들이 계속 내용을 추가하면서 지금의 모습이 되었습니다.
스킬을 가장 잘 이해하는 방법은 직접 시작해보고, 실험하고, 무엇이 효과적인지 확인하는 것입니다.
이 글은 Claude Code 개발을 담당하는 Anthropic 테크니컬 스태프 Thariq Shihipar가 작성했습니다.