스킬은 Claude Code에서 가장 많이 사용되는 확장 기능 중 하나가 되었습니다. 유연하고, 만들기 쉬우며, 배포도 간단합니다.
하지만 이러한 유연성 덕분에 어떤 방식이 가장 효과적인지 파악하기 어렵기도 합니다. 어떤 유형의 스킬을 만드는 것이 가치 있을까요? 좋은 스킬을 작성하는 비결은 무엇일까요? 언제 다른 사람들과 공유해야 할까요?
Anthropic에서는 Claude Code에서 수백 개의 스킬을 활발히 사용하며 경험하고 있습니다. 이 글은 개발 속도를 높이기 위해 스킬을 활용하면서 배운 교훈을 공유합니다.
스킬이란?
스킬이 처음이라면 공식 문서를 읽거나 Skilljar의 에이전트 스킬에 관한 새로운 강좌를 시청하는 것을 추천합니다. 이 글은 이미 스킬에 대해 어느 정도 익숙하다고 가정합니다.
스킬에 대해 흔히 듣는 오해는 스킬이 "단순한 마크다운 파일"이라는 것입니다. 하지만 스킬의 가장 흥미로운 점은 단순한 텍스트 파일이 아니라는 데 있습니다. 스킬은 에이전트가 발견하고, 탐색하고, 조작할 수 있는 스크립트, 자산, 데이터 등을 포함할 수 있는 폴더입니다.
Claude Code에서 스킬은 또한 다양한 설정 옵션을 제공하며, 여기에는 동적 후크 등록도 포함됩니다.
Claude Code에서 가장 흥미로운 스킬 중 일부는 이러한 설정 옵션과 폴더 구조를 창의적으로 활용한다는 것을 발견했습니다.
스킬의 유형
모든 스킬을 분류한 결과, 몇 가지 반복되는 카테고리로 묶이는 것을 확인했습니다. 가장 좋은 스킬은 한 가지 카테고리에 깔끔하게 들어맞는 반면, 더 혼란스러운 스킬은 여러 카테고리에 걸쳐 있습니다. 이것이 완전한 목록은 아니지만, 조직 내에서 어떤 스킬이 부족한지 생각해볼 수 있는 좋은 방법입니다.
1. 라이브러리 및 API 참조
라이브러리, CLI 또는 SDK를 올바르게 사용하는 방법을 설명하는 스킬입니다. 내부 라이브러리와 Claude Code가 가끔 어려워하는 일반 라이브러리 모두에 해당할 수 있습니다. 이러한 스킬은 종종 참조 코드 스니펫 폴더와 Claude가 스크립트를 작성할 때 피해야 할 주의사항 목록을 포함합니다.
예시:
- billing-lib — 내부 청구 라이브러리: 엣지 케이스, 함정 등
- internal-platform-cli — 내부 CLI 래퍼의 모든 서브 명령어와 사용 시점에 대한 예시
- frontend-design — 디자인 시스템에서 Claude의 성능 향상
2. 제품 검증
코드가 제대로 작동하는지 테스트하거나 검증하는 방법을 설명하는 스킬입니다. 이러한 스킬은 종종 검증을 위해 Playwright, tmux 등의 외부 도구와 함께 사용됩니다.
검증 스킬은 Claude의 출력이 올바른지 확인하는 데 매우 유용합니다. 엔지니어가 일주일을 투자하여 검증 스킬을 개선하는 것도 가치 있는 일입니다.
Claude가 출력 결과를 비디오로 기록하여 정확히 무엇을 테스트했는지 확인하거나, 각 단계에서 상태에 대한 프로그래밍 방식의 어설션을 적용하는 등의 기법을 고려해보세요. 이러한 작업은 스킬에 다양한 스크립트를 포함함으로써 수행되는 경우가 많습니다.
예시:
- signup-flow-driver — 헤드리스 브라우저에서 가입 → 이메일 인증 → 온보딩을 진행하며, 각 단계에서 상태를 어설션하는 후크 포함
- checkout-verifier — Stripe 테스트 카드로 체크아웃 UI를 구동하고, 인보이스가 올바른 상태로 도착하는지 확인
- tmux-cli-driver — 검증 대상이 TTY를 필요로 하는 대화형 CLI 테스트용
3. 데이터 가져오기 및 분석
데이터 및 모니터링 스택에 연결하는 스킬입니다. 이러한 스킬에는 자격 증명을 사용하여 데이터를 가져오는 라이브러리, 특정 대시보드 ID 등과 함께 일반적인 워크플로우나 데이터를 가져오는 방법에 대한 지침이 포함될 수 있습니다.
예시:
- funnel-query — "가입 → 활성화 → 유료 전환을 보려면 어떤 이벤트를 조인해야 하며, 실제 표준 user_id가 있는 테이블은 무엇인가"
- cohort-compare — 두 코호트의 리텐션 또는 전환율을 비교하고, 통계적으로 유의미한 차이를 플래그 지정하며, 세그먼트 정의에 연결
- grafana — 데이터 소스 UID, 클러스터 이름, 문제 → 대시보드 조회 테이블
4. 비즈니스 프로세스 및 팀 자동화
반복적인 워크플로우를 하나의 명령어로 자동화하는 스킬입니다. 이러한 스킬은 일반적으로 비교적 간단한 지침으로 구성되지만, 다른 스킬이나 MCP에 대한 더 복잡한 종속성을 가질 수 있습니다. 이러한 스킬의 경우, 이전 결과를 로그 파일에 저장하면 모델이 일관성을 유지하고 워크플로우의 이전 실행에 대해 반성하는 데 도움이 될 수 있습니다.
예시:
- standup-post — 티켓 트래커, GitHub 활동 및 이전 Slack 내용을 종합하여 변경 사항만 포함된 포맷된 스탠드업 게시물 생성
- create-<ticket-system>-ticket — 스키마(유효한 열거형 값, 필수 필드)를 적용하고, 생성 후 워크플로우(리뷰어에게 알림, 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 — 알림 가져오기 → 일반적인 원인 확인 → 조사 결과 포맷팅
- log-correlator — 요청 ID가 주어지면 관련된 모든 시스템에서 일치하는 로그 가져오기
9. 인프라 운영
일상적인 유지보수 및 운영 절차를 수행하는 스킬입니다. 일부는 안전장치가 필요한 파괴적인 작업을 포함합니다. 이러한 스킬은 엔지니어가 중요한 운영에서 모범 사례를 따르도록 돕습니다.
예시:
- <resource>-orphans — 고아가 된 파드/볼륨 찾기 → Slack에 게시 → 대기 기간 → 사용자 확인 → 계단식 정리
- dependency-management — 조직의 의존성 승인 워크플로우
- cost-investigation — "스토리지/이그레스 비용이 급증한 이유"를 특정 버킷 및 쿼리 패턴과 함께 분석
스킬 제작 팁
만들 스킬을 결정했다면, 어떻게 작성할까요? 다음은 우리가 발견한 모범 사례, 팁 및 요령입니다.
최근에는 Claude Code에서 스킬을 더 쉽게 만들 수 있도록 Skill Creator도 출시했습니다.
명확한 것은 굳이 말하지 마세요
Claude Code는 코드베이스에 대해 많은 것을 알고 있으며, Claude는 코딩에 대해 많은 기본 의견을 포함하여 많은 것을 알고 있습니다. 주로 지식에 관한 스킬을 게시하는 경우, Claude가 평소와 다른 사고 방식을 갖도록 유도하는 정보에 초점을 맞추세요.
프론트엔드 디자인 스킬이 좋은 예입니다 — Anthropic의 한 엔지니어가 고객과의 반복적인 협업을 통해 Claude의 디자인 감각을 개선하고, Inter 폰트나 보라색 그라데이션과 같은 전형적인 패턴을 피하도록 구축했습니다.
주의사항 섹션 만들기
모든 스킬에서 가장 신호가 강한 콘텐츠는 주의사항(Gotchas) 섹션입니다. 이 섹션은 스킬을 사용할 때 Claude가 자주 직면하는 실패 지점을 바탕으로 구축해야 합니다. 이상적으로는 시간이 지남에 따라 이러한 주의사항을 포착하여 스킬을 업데이트해야 합니다.
파일 시스템 및 점진적 공개 활용
앞서 말했듯이, 스킬은 단순한 마크다운 파일이 아니라 폴더입니다. 전체 파일 시스템을 컨텍스트 엔지니어링 및 점진적 공개의 한 형태로 생각해야 합니다. 스킬에 어떤 파일이 있는지 Claude에게 알려주면, Claude는 적절한 시점에 해당 파일을 읽습니다.
가장 간단한 형태의 점진적 공개는 Claude가 사용할 다른 마크다운 파일을 가리키는 것입니다. 예를 들어, 상세한 함수 시그니처와 사용 예시를 references/api.md로 분리할 수 있습니다.
또 다른 예: 최종 출력이 마크다운 파일이라면, 복사하여 사용할 템플릿 파일을 assets/에 포함시킬 수 있습니다.
참조, 스크립트, 예시 등의 폴더를 두어 Claude가 더 효과적으로 작업할 수 있도록 도울 수 있습니다.
Claude를 지나치게 제한하지 마세요
Claude는 일반적으로 지침을 따르려고 노력하며, 스킬은 재사용성이 높기 때문에 지침이 너무 구체적이지 않도록 주의해야 합니다. Claude에게 필요한 정보를 제공하되, 상황에 맞게 적응할 수 있는 유연성을 제공하세요. 예를 들어:
설정 고려하기
일부 스킬은 사용자로부터 컨텍스트를 제공받아 설정해야 할 수 있습니다. 예를 들어, 스탠드업을 Slack에 게시하는 스킬을 만드는 경우, Claude가 어떤 Slack 채널에 게시할지 물어보도록 할 수 있습니다.
이를 위한 좋은 패턴은 위의 예시와 같이 스킬 디렉토리의 config.json 파일에 설정 정보를 저장하는 것입니다. 설정이 완료되지 않은 경우, 에이전트는 사용자에게 정보를 요청할 수 있습니다.
에이전트가 구조화된 객관식 질문을 제시하도록 하려면 AskUserQuestion 도구를 사용하도록 지시할 수 있습니다.
설명 필드는 모델을 위한 것입니다
Claude Code가 세션을 시작할 때, 설명과 함께 사용 가능한 모든 스킬의 목록을 작성합니다. 이 목록을 통해 Claude는 "이 요청에 맞는 스킬이 있는가?"를 결정합니다. 즉, 설명 필드는 요약이 아니라 이 PR을 트리거해야 하는 시점에 대한 설명입니다.
메모리 및 데이터 저장
일부 스킬은 내부에 데이터를 저장하여 일종의 메모리 형태를 포함할 수 있습니다. 추가 전용 텍스트 로그 파일이나 JSON 파일처럼 간단한 형태부터 SQLite 데이터베이스처럼 복잡한 형태까지 데이터를 저장할 수 있습니다.
예를 들어, standup-post 스킬은 작성된 모든 게시물이 포함된 standups.log를 유지할 수 있습니다. 다음에 실행할 때 Claude는 자신의 기록을 읽고 어제 이후 변경된 사항을 알 수 있습니다.
스킬 디렉토리에 저장된 데이터는 스킬을 업그레이드할 때 삭제될 수 있으므로 안정적인 폴더에 저장해야 합니다. 현재 플러그인당 데이터를 저장할 수 있는 안정적인 폴더로 ${**CLAUDE_PLUGIN_DATA**}를 제공합니다.
스크립트 저장 및 코드 생성
Claude에게 제공할 수 있는 가장 강력한 도구 중 하나는 코드입니다. 스크립트와 라이브러리를 제공하면 Claude가 보일러플레이트를 재구성하는 대신 구성에 시간을 사용하여 다음에 무엇을 할지 결정할 수 있습니다.
예를 들어, 데이터 과학 스킬에서 이벤트 소스에서 데이터를 가져오는 함수 라이브러리를 가질 수 있습니다. Claude가 복잡한 분석을 수행할 수 있도록 다음과 같은 도우미 함수 세트를 제공할 수 있습니다.
Claude는 "화요일에 무슨 일이 있었나요?"와 같은 프롬프트에 대해 이 기능을 구성하여 더 고급 분석을 수행하는 스크립트를 즉석에서 생성할 수 있습니다.
온디맨드 후크
스킬에는 스킬이 호출될 때만 활성화되고 세션 기간 동안 지속되는 후크를 포함할 수 있습니다. 항상 실행할 필요는 없지만 가끔 매우 유용한 보다 엄격한 후크에 사용하세요.
예를 들어:
- /careful — PreToolUse 매처를 통해 Bash의 rm -rf, DROP TABLE, 강제 푸시, kubectl delete를 차단합니다. 프로덕션을 건드리고 있다는 것을 알 때만 필요합니다. 항상 켜져 있으면 미칠 노릇입니다.
- /freeze — 특정 디렉토리가 아닌 경우 모든 편집/쓰기를 차단합니다. 디버깅할 때 유용합니다. "로그를 추가하고 싶은데 관련 없는 것을 계속 실수로 '수정'합니다.
스킬 배포
스킬의 가장 큰 장점 중 하나는 팀의 다른 구성원과 공유할 수 있다는 것입니다.
스킬을 다른 사람과 공유하는 방법은 두 가지가 있습니다:
- 스킬을 저장소(./.claude/skills 아래)에 체크인
- 플러그인을 만들어 사용자가 플러그인을 업로드하고 설치할 수 있는 Claude Code 플러그인 마켓플레이스를 만드는 것(자세한 내용은 문서 참조)
상대적으로 적은 수의 저장소에서 작업하는 소규모 팀의 경우, 스킬을 저장소에 체크인하는 것이 효과적입니다. 하지만 체크인된 모든 스킬은 모델의 컨텍스트에 약간의 부담을 추가합니다. 규모가 커짐에 따라 내부 플러그인 마켓플레이스를 통해 스킬을 배포하고 팀이 설치할 스킬을 결정하도록 할 수 있습니다.
마켓플레이스 관리
어떤 스킬을 마켓플레이스에 넣을지 결정하는 방법은 무엇일까요? 사람들은 어떻게 스킬을 제출할까요?
우리는 중앙 집중식 결정 팀이 없습니다. 대신 유기적으로 가장 유용한 스킬을 찾으려고 합니다. 사람들이 사용해보길 원하는 스킬이 있다면, GitHub의 샌드박스 폴더에 업로드하고 Slack이나 다른 포럼에서 사람들에게 알릴 수 있습니다.
스킬이 인기를 얻으면(스킬 소유자가 판단), 마켓플레이스로 이동시키기 위한 PR을 제출할 수 있습니다.
주의할 점은, 나쁘거나 중복된 스킬을 만드는 것이 매우 쉬울 수 있으므로 출시 전에 어떤 형태로든 큐레이션 방법을 마련하는 것이 중요합니다.
스킬 구성
서로에게 의존하는 스킬을 가질 수 있습니다. 예를 들어, 파일을 업로드하는 파일 업로드 스킬과 CSV를 생성하여 업로드하는 CSV 생성 스킬이 있을 수 있습니다. 이러한 종류의 의존성 관리는 아직 마켓플레이스나 스킬에 기본적으로 내장되어 있지 않지만, 이름으로 다른 스킬을 참조할 수 있으며, 해당 스킬이 설치되어 있으면 모델이 이를 호출합니다.
스킬 측정
스킬의 성과를 이해하기 위해, 우리는 회사 내에서 스킬 사용을 기록할 수 있는 PreToolUse 후크를 사용합니다(예제 코드). 이를 통해 인기 있는 스킬이나 기대에 비해 트리거가 적은 스킬을 찾을 수 있습니다.
결론
스킬은 에이전트를 위한 매우 강력하고 유연한 도구이지만, 아직 초기 단계이며 우리 모두 최적으로 사용하는 방법을 알아가고 있는 중입니다.
이 글을 최종 가이드라기보다는 실제로 효과를 본 유용한 팁 모음집으로 생각해주세요. 스킬을 이해하는 가장 좋은 방법은 시작하고, 실험하고, 자신에게 맞는 것이 무엇인지 알아보는 것입니다. 대부분의 스킬은 몇 줄과 하나의 주의사항으로 시작했으며, Claude가 새로운 엣지 케이스를 만날 때마다 사람들이 계속 추가하면서 개선되었습니다.
도움이 되었기를 바랍니다. 질문이 있으면 알려주세요.
