Claude Code에서 Skills를 확장 포인트로 활용하며 얻은 교훈: 어떤 스킬이 유용한지, 잘 만드는 법, 공유와 배포 방법, 그리고 조직에서 운영하는 방식까지 정리한다.
Skills는 Claude Code에서 가장 많이 사용되는 확장 포인트 중 하나가 되었습니다. 유연하고, 만들기 쉽고, 배포도 간단합니다.
하지만 이런 유연성 때문에 무엇이 가장 잘 작동하는지 알기 어렵기도 합니다. 어떤 유형의 스킬을 만들 가치가 있을까요? 좋은 스킬을 쓰는 비결은 무엇일까요? 언제 다른 사람들과 공유해야 할까요?
Anthropic에서는 Claude Code에서 스킬을 광범위하게 사용해 왔고, 실제로 수백 개의 스킬이 활발히 쓰이고 있습니다. 아래는 스킬을 활용해 개발 속도를 높이면서 우리가 배운 교훈들입니다.
스킬이 처음이라면, 저는
또는
에 대한 최신 코스를 시청하는 것을 권합니다. 이 글은 스킬에 이미 어느 정도 익숙하다는 전제하에 진행합니다.
스킬에 대해 우리가 흔히 듣는 오해는 스킬이 “그냥 markdown 파일”이라는 것입니다. 하지만 스킬에서 가장 흥미로운 점은 스킬이 단순한 텍스트 파일이 아니라는 데 있습니다. 스킬은 폴더이며, 그 안에 에이전트가 발견하고, 탐색하고, 조작할 수 있는 스크립트, 에셋, 데이터 등을 포함할 수 있습니다.
Claude Code에서 스킬은 또한
을 갖고 있으며, 동적 훅을 등록하는 것도 포함됩니다.
우리는 Claude Code에서 가장 흥미로운 스킬들 중 일부가 이런 설정 옵션과 폴더 구조를 창의적으로 활용한다는 것을 발견했습니다.
모든 스킬을 목록화해 보니 몇 가지 반복되는 범주로 군집화되는 것을 확인했습니다. 최고의 스킬은 깔끔하게 한 범주에 들어맞습니다. 반대로 헷갈리는 스킬은 여러 범주에 걸쳐 있습니다. 아래는 확정적인 목록은 아니지만, 조직 내부에서 어떤 것이 빠져 있는지 생각해 보는 데 좋은 틀입니다.
라이브러리, CLI, 또는 SDK를 올바르게 사용하는 방법을 설명하는 스킬입니다. 내부 라이브러리일 수도 있고, Claude Code가 가끔 어려워하는 일반 라이브러리일 수도 있습니다. 이런 스킬에는 참조 코드 스니펫 폴더와, 스크립트를 작성할 때 Claude가 피해야 할 함정(gotcha) 목록이 포함되는 경우가 많았습니다.
예시:
billing-lib — 내부 결제 라이브러리: 엣지 케이스, 위험한 함정 등
internal-platform-cli — 내부 CLI 래퍼의 모든 서브커맨드를, 언제 써야 하는지 예시와 함께
frontend-design — Claude가 디자인 시스템을 더 잘 다루게 만들기
코드가 제대로 동작하는지 테스트하거나 검증하는 방법을 설명하는 스킬입니다. 이런 스킬은 검증을 위해 playwright, tmux 같은 외부 도구와 함께 쓰이는 경우가 많습니다.
검증 스킬은 Claude의 출력이 정확한지 보장하는 데 매우 유용합니다. 엔지니어가 1주일 정도를 들여 검증 스킬을 아주 훌륭하게 만드는 일은 충분히 가치가 있을 수 있습니다.
Claude가 출력 결과를 영상으로 녹화해서 무엇을 테스트했는지 정확히 볼 수 있게 하거나, 각 단계에서 상태에 대한 프로그램적 assertion을 강제하는 기법을 고려해 보세요. 이런 것들은 보통 스킬에 다양한 스크립트를 포함하는 방식으로 구현합니다.
예시:
signup-flow-driver — 헤드리스 브라우저에서 가입 → 이메일 인증 → 온보딩을 순회 실행하며, 각 단계에서 상태를 assertion할 수 있는 훅 포함
checkout-verifier — Stripe 테스트 카드로 체크아웃 UI를 구동하고, 인보이스가 실제로 올바른 상태로 들어갔는지 검증
tmux-cli-driver — 검증 대상이 TTY를 필요로 하는 대화형 CLI 테스트용
데이터 및 모니터링 스택에 연결하는 스킬입니다. 이런 스킬에는 자격 증명으로 데이터를 가져오는 라이브러리, 특정 대시보드 id 등과 함께, 흔한 워크플로우나 데이터를 얻는 방법에 대한 지침이 들어갈 수 있습니다.
예시:
funnel-query — “가입 → 활성화 → 결제 전환을 보려면 어떤 이벤트를 조인해야 하나” + 정식 canonical user_id가 들어 있는 테이블
cohort-compare — 두 코호트의 리텐션 또는 전환을 비교하고, 통계적으로 유의미한 델타를 표시하며, 세그먼트 정의로 링크
grafana — datasource UID, 클러스터 이름, 문제 → 대시보드 조회 테이블
반복적인 워크플로우를 한 번의 명령으로 자동화하는 스킬입니다. 이런 스킬은 대개 지침 자체는 비교적 단순하지만, 다른 스킬이나 MCP에 대한 의존성이 더 복잡할 수 있습니다. 이 유형의 스킬에서는 이전 결과를 로그 파일에 저장하면 모델이 일관성을 유지하고 과거 실행을 반추하는 데 도움이 됩니다.
예시:
standup-post — 티켓 트래커, GitHub 활동, 이전 Slack을 집계 → 포맷된 스탠드업 작성, 변경분만(delta-only)
create-<ticket-system>-ticket — 스키마 강제(유효한 enum 값, 필수 필드) + 생성 후 워크플로우(리뷰어 핑, Slack에 링크)
weekly-recap — 머지된 PR + 닫힌 티켓 + 배포 → 포맷된 리캡 포스트
코드베이스 내 특정 기능을 위한 프레임워크 보일러플레이트를 생성하는 스킬입니다. 이런 스킬은 조합 가능한 스크립트와 함께 결합할 수 있습니다. 특히 스캐폴딩에 자연어 요구사항이 포함되어 코드만으로 완전히 커버하기 어려울 때 유용합니다.
예시:
new-<framework>-workflow — 주석/애노테이션을 포함하여 새 서비스/워크플로우/핸들러 스캐폴딩
new-migration — 마이그레이션 파일 템플릿 + 흔한 함정
create-app — 인증, 로깅, 배포 설정이 미리 연결된 새 내부 앱
조직 내부에서 코드 품질을 강제하고 코드 리뷰를 돕는 스킬입니다. 최대한의 견고함을 위해 결정론적 스크립트나 도구를 포함할 수 있습니다. 훅의 일부로 또는 GitHub Action 안에서 이런 스킬을 자동으로 실행하고 싶을 수도 있습니다.
adversarial-review — 새 시각의 서브에이전트를 띄워 비판적으로 리뷰하고, 수정하고, 지적 사항이 사소한 트집 수준으로 떨어질 때까지 반복
code-style — 코드 스타일을 강제, 특히 Claude가 기본으로는 잘 못 맞추는 스타일들
testing-practices — 테스트를 어떻게 쓰고 무엇을 테스트해야 하는지에 대한 지침
코드베이스 안에서 코드를 가져오고(fetch), 푸시하고(push), 배포하는(deploy) 데 도움을 주는 스킬입니다. 이런 스킬은 데이터를 수집하기 위해 다른 스킬을 참조할 수 있습니다.
예시:
babysit-pr — PR을 모니터링 → 불안정한 CI 재시도 → 머지 충돌 해결 → 자동 머지 활성화
deploy-<service> — 빌드 → 스모크 테스트 → 에러율 비교를 포함한 점진적 트래픽 롤아웃 → 회귀(regression) 시 자동 롤백
cherry-pick-prod — 격리된 worktree → 체리픽 → 충돌 해결 → 템플릿 포함 PR
증상(예: Slack 스레드, 알림, 에러 시그니처)을 입력으로 받아 멀티툴 조사를 진행하고, 구조화된 보고서를 산출하는 스킬입니다.
예시:
<service>-debugging — 증상 → 도구 → 쿼리 패턴을, 트래픽이 가장 높은 서비스들에 대해 매핑
oncall-runner — 알림을 가져옴 → 흔한 원인들을 확인 → 결과를 포맷
log-correlator — 요청 ID가 주어지면, 해당 요청이 거쳤을 수 있는 모든 시스템에서 매칭 로그를 가져옴
정기적인 유지보수 및 운영 절차를 수행하는 스킬입니다. 일부는 파괴적 작업을 포함할 수 있어 가드레일이 도움이 됩니다. 이런 스킬은 엔지니어가 중요한 운영에서 모범 사례를 따르기 쉽게 만들어 줍니다.
예시:
<resource>-orphans — 고아가 된 pod/volume 찾기 → Slack에 게시 → 유예 기간(soak period) → 사용자 확인 → 연쇄 정리(cascading cleanup)
dependency-management — 조직의 의존성 승인 워크플로우
cost-investigation — “왜 스토리지/이그레스 비용이 급등했나”를, 특정 버킷과 쿼리 패턴과 함께
만들 스킬을 결정했다면, 이제 어떻게 작성할까요? 아래는 우리가 찾은 모범 사례(best practices), 팁, 트릭들입니다.
또한 최근에는
도 공개했는데, Claude Code에서 스킬을 더 쉽게 만들 수 있게 해 줍니다.
Claude Code는 여러분의 코드베이스에 대해 많이 알고 있고, Claude는 코딩에 대해 많이 알고 있으며 기본적으로 여러 “기본 의견”도 갖고 있습니다. 주로 지식 전달이 목적이라면, Claude의 평소 사고방식에서 벗어나도록 밀어주는 정보에 집중해 보세요.
은 훌륭한 예시입니다 — Anthropic의 한 엔지니어가 고객들과 반복적으로 개선해 가며 Claude의 디자인 취향을 더 좋게 만들기 위해 만들었습니다. Inter 폰트와 보라색 그라디언트 같은 전형적 패턴을 피하는 것 등이 포함됩니다.
어떤 스킬에서든 신호 대비 정보량(highest-signal)이 가장 높은 콘텐츠는 Gotchas 섹션입니다. 이 섹션은 Claude가 해당 스킬을 사용할 때 자주 부딪히는 실패 지점들로부터 구축되어야 합니다. 이상적으로는 시간이 지남에 따라 이런 gotcha를 포착하도록 스킬을 업데이트하게 됩니다.
앞에서 말했듯, 스킬은 markdown 파일이 아니라 폴더입니다. 전체 파일 시스템을 컨텍스트 엔지니어링과 점진적 공개(progressive disclosure)의 한 형태로 생각해야 합니다. 스킬 안에 어떤 파일이 있는지 Claude에게 알려주면, Claude는 적절한 타이밍에 그 파일들을 읽습니다.
점진적 공개의 가장 단순한 형태는 Claude가 사용할 다른 markdown 파일을 가리키는 것입니다. 예를 들어 상세한 함수 시그니처와 사용 예시를 references/api.md로 분리할 수 있습니다.
또 다른 예: 최종 결과물이 markdown 파일이라면, assets/에 그에 대한 템플릿 파일을 넣어 복사해 사용하게 할 수 있습니다.
참조, 스크립트, 예시 등의 폴더를 둘 수 있고, 이는 Claude가 더 효과적으로 작업하는 데 도움을 줍니다.
Claude는 일반적으로 지시를 지키려 하고, Skills는 재사용성이 매우 높기 때문에 지시가 지나치게 구체적이지 않도록 조심해야 합니다. Claude에게 필요한 정보는 주되, 상황에 맞게 적응할 수 있는 유연성도 주어야 합니다. 예를 들어:
어떤 스킬은 사용자로부터 컨텍스트를 받아 설정해야 할 수 있습니다. 예를 들어 스탠드업을 Slack에 게시하는 스킬을 만든다면, 어떤 Slack 채널에 올릴지 Claude가 물어보게 하고 싶을 수 있습니다.
이를 위한 좋은 패턴은 위 예시처럼 스킬 디렉터리에 config.json 파일로 이런 설정 정보를 저장하는 것입니다. config가 설정되지 않았다면, 에이전트는 사용자에게 정보를 요청할 수 있습니다.
에이전트가 구조화된 객관식 질문을 제시하길 원한다면, Claude에게 AskUserQuestion 도구를 사용하라고 지시할 수 있습니다.
Claude Code가 세션을 시작하면, 사용 가능한 모든 스킬의 목록을 설명(description)과 함께 구축합니다. Claude는 이 목록을 스캔하며 “이 요청에 해당하는 스킬이 있나?”를 결정합니다. 즉 description 필드는 요약이 아니라, 이 PR을 언제 트리거할지에 대한 설명입니다.
일부 스킬은 내부에 데이터를 저장하여 일종의 메모리 형태를 포함할 수 있습니다. append-only 텍스트 로그 파일이나 JSON 파일처럼 단순한 형태부터, SQLite 데이터베이스처럼 복잡한 형태까지 무엇이든 사용할 수 있습니다.
예를 들어 standup-post 스킬은 작성한 모든 게시물을 standups.log로 남겨둘 수 있습니다. 그러면 다음에 실행할 때 Claude가 자신의 히스토리를 읽고, 어제 이후 무엇이 바뀌었는지 알 수 있습니다.
스킬 디렉터리에 저장된 데이터는 스킬을 업그레이드할 때 삭제될 수 있으므로, 안정적인 폴더에 저장해야 합니다. 현재 우리는 플러그인별로 데이터를 저장할 수 있는 안정적인 폴더로 ${CLAUDE_PLUGIN_DATA}를 제공합니다.
Claude에게 줄 수 있는 가장 강력한 도구 중 하나는 코드입니다. Claude에게 스크립트와 라이브러리를 제공하면, Claude는 보일러플레이트를 재구성하는 대신 구성(composition)과 다음 행동 결정에 턴을 쓸 수 있습니다.
예를 들어 데이터 사이언스 스킬에서는 이벤트 소스에서 데이터를 가져오는 함수 라이브러리를 둘 수 있습니다. Claude가 복잡한 분석을 하게 만들려면 아래처럼 헬퍼 함수 세트를 제공할 수 있습니다:
그러면 Claude는 “화요일에 무슨 일이 있었어?” 같은 프롬프트에 대해 더 고급 분석을 수행하기 위해, 이런 기능을 조합하는 스크립트를 그때그때 생성할 수 있습니다.
스킬은 스킬이 호출될 때만 활성화되고, 세션 동안 지속되는 훅을 포함할 수 있습니다. 항상 실행하고 싶지는 않지만, 때때로 매우 유용한 더 강한 의견(opinionated) 훅에 이를 활용하세요.
예를 들어:
/careful — Bash에 대한 PreToolUse matcher로 rm -rf, DROP TABLE, force-push, kubectl delete를 차단. 프로덕션을 건드린다는 걸 알고 있을 때만 원합니다 — 항상 켜 두면 미쳐버릴 겁니다
/freeze — 특정 디렉터리 밖에서의 Edit/Write를 차단. 유용함
디버깅 시: “로그를 추가하고 싶은데 자꾸 실수로 관련 없는 것을 ‘수정’하고 있어”
Skills의 가장 큰 장점 중 하나는 팀의 나머지 사람들과 공유할 수 있다는 점입니다.
스킬을 다른 사람들과 공유하는 방법은 두 가지가 있습니다:
스킬을 리포지토리에 체크인하기(./.claude/skills 아래)
플러그인을 만들고, 사용자가 플러그인을 업로드하고 설치할 수 있는 Claude Code Plugin 마켓플레이스를 운영하기(자세한 내용은
에서 읽기)
상대적으로 적은 수의 리포지토리를 두고 일하는 작은 팀에게는, 리포지토리에 스킬을 체크인하는 방식이 잘 맞습니다. 하지만 체크인된 모든 스킬은 모델의 컨텍스트에 조금씩 추가됩니다. 규모가 커질수록 내부 플러그인 마켓플레이스를 통해 스킬을 배포하고, 팀이 어떤 스킬을 설치할지 스스로 결정하도록 하는 편이 좋습니다.
그렇다면 어떤 스킬을 마켓플레이스에 넣을지 어떻게 결정할까요? 사람들은 어떻게 제출할까요?
우리는 이를 결정하는 중앙화된 팀을 두고 있지 않습니다. 대신 가장 유용한 스킬이 유기적으로 드러나도록 합니다. 사람들이 시험해 보길 원하는 스킬이 있다면, GitHub의 sandbox 폴더에 업로드하고 Slack이나 다른 포럼에서 그쪽으로 안내하면 됩니다.
스킬이 충분한 사용을 얻으면(어느 정도가 충분한지는 스킬 소유자가 결정), 마켓플레이스로 옮기기 위한 PR을 올릴 수 있습니다.
주의할 점이 하나 있습니다. 나쁘거나 중복되는 스킬을 만들기는 아주 쉽기 때문에, 릴리스 전에 큐레이션하는 방법을 반드시 마련하는 것이 중요합니다.
스킬들이 서로 의존하도록 만들고 싶을 수도 있습니다. 예를 들어 파일 업로드 스킬이 파일을 업로드하고, CSV 생성 스킬이 CSV를 만든 뒤 업로드하는 식입니다. 이런 의존성 관리는 아직 마켓플레이스나 스킬에 기본으로 내장되어 있지 않지만, 다른 스킬을 이름으로 참조하면 되고, 모델은 설치되어 있다면 그것들을 호출할 것입니다.
스킬이 어떻게 쓰이고 있는지 이해하기 위해, 우리는 회사 내 스킬 사용량을 로깅할 수 있게 해주는 PreToolUse 훅을 사용합니다(
). 이를 통해 인기 있는 스킬이나, 예상 대비 트리거가 덜 되는(undertriggering) 스킬을 찾을 수 있습니다.
Skills는 에이전트를 위한 믿을 수 없을 만큼 강력하고 유연한 도구지만, 아직은 초반 단계이고 우리 모두가 최선의 사용법을 찾아가는 중입니다.
이 글을 확정적인 가이드라기보다, 실제로 효과가 있었던 유용한 팁들의 모음(grab bag)으로 생각해 주세요. 스킬을 이해하는 가장 좋은 방법은 시작해서 실험해 보고, 여러분에게 무엇이 잘 맞는지 확인하는 것입니다. 우리 스킬 대부분도 몇 줄과 gotcha 하나로 시작했고, Claude가 새로운 엣지 케이스를 만날 때마다 사람들이 계속 덧붙이면서 더 좋아졌습니다.
도움이 되었길 바랍니다. 질문이 있으면 알려 주세요.
