Claude Code를 만들며 배운 것들: 우리가 ‘스킬’을 쓰는 방식
TMTSkills는 현재 Claude Code에서 가장 많이 사용되는 확장 포인트 중 하나입니다. 유연하고 만들기 쉽고, 배포도 간단합니다.
하지만 이런 유연함 때문에 무엇이 가장 효과적인 방식인지 파악하기가 어렵습니다. 어떤 종류의 스킬을 만들 가치가 있을까요? 좋은 스킬을 쓰는 비결은 무엇일까요? 언제 다른 사람들과 공유해야 할까요?
Anthropic에서는 Claude Code에서 스킬을 광범위하게 사용해 왔으며, 수백 개의 스킬이 적극적으로 활용되고 있습니다. 여기에는 우리가 스킬을 활용해 개발을 가속화하면서 얻은 교훈들이 담겨 있습니다.
Skills란 무엇인가요?
스킬에 익숙하지 않다면, 먼저 문서를 읽어보거나, 에이전트 스킬에 대한 최신 강의인 new Skilljar on Agent Skills를 시청해 보시는 것을 추천합니다. 이 글은 여러분이 이미 스킬에 어느 정도 익숙하다는 전제 하에 진행됩니다.
우리가 스킬에 대해 자주 듣는 오해 중 하나는 “그냥 마크다운 파일일 뿐”이라는 것입니다. 하지만 스킬에서 가장 흥미로운 점은 단순한 텍스트 파일이 아니라는 데 있습니다. 스킬은 폴더이며, 그 안에는 스크립트, 에셋, 데이터 등이 포함될 수 있고, 에이전트는 이를 탐색하고, 살펴보고, 조작할 수 있습니다.
Claude Code에서 스킬은 동적 훅(dynamically registered hooks)을 등록하는 것을 포함해, 매우 다양한 설정 옵션을 지원합니다.
우리는 Claude Code에서 이런 설정 옵션과 폴더 구조를 창의적으로 활용한 스킬들이 가장 흥미롭다는 것을 발견했습니다.
스킬의 종류
모든 스킬을 분류해 보니 몇 가지 반복적으로 등장하는 카테고리로 묶인다는 것을 알 수 있었습니다. 가장 좋은 스킬들은 이 중 하나에 명확히 속하며, 더 혼란스러운 스킬일수록 여러 범주에 걸쳐 애매하게 걸쳐져 있습니다. 이 목록이 최종적인 기준은 아니지만, 조직 내에서 빠뜨리고 있는 스킬 유형이 있는지 생각해 보는 데에는 좋은 기준이 됩니다.
1. 라이브러리 및 API 레퍼런스
라이브러리, CLI, SDK를 올바르게 사용하는 방법을 설명하는 스킬입니다. 사내 라이브러리일 수도 있고, Claude Code가 때때로 다루기 어려워하는 일반적인 라이브러리일 수도 있습니다. 이런 스킬에는 종종 참고용 코드 스니펫 모음과, Claude가 스크립트를 작성할 때 피해야 할 “주의 사항(gotchas)” 목록이 포함됩니다.
예시:
billing-lib— 사내 결제 라이브러리: 엣지 케이스, 발목을 잡는 포인트 등.internal-platform-cli— 사내 CLI 래퍼의 모든 서브커맨드와, 각 커맨드를 언제 사용해야 하는지에 대한 예시.frontend-design— Claude가 여러분의 디자인 시스템을 더 잘 활용하도록 돕는 스킬.
2. 제품 검증
코드가 제대로 작동하는지 테스트하거나 검증하는 방법을 설명하는 스킬입니다. 이런 스킬은 종종 playwright, tmux 등과 같은 외부 도구와 함께 사용됩니다.
검증 스킬은 Claude의 결과물이 올바른지 보장하는 데 매우 유용합니다. 엔지니어 한 명이 일주일을 써서라도 검증 스킬을 훌륭하게 만드는 가치는 충분합니다.
Claude가 테스트한 내용을 정확히 확인할 수 있도록 결과를 영상으로 녹화하게 하거나, 각 단계마다 상태를 프로그램적으로 검증(assert)하도록 하는 기법도 고려해 보세요. 이런 기능은 보통 스킬 안에 다양한 스크립트를 포함시키는 방식으로 구현됩니다.
예시:
signup-flow-driver— 헤드리스 브라우저에서 가입 → 이메일 인증 → 온보딩 과정을 실행하고, 각 단계마다 상태를 검증할 수 있는 훅을 제공.checkout-verifier— Stripe 테스트 카드로 체크아웃 UI를 구동하고, 실제로 인보이스가 올바른 상태에 도달했는지 검증.tmux-cli-driver— TTY가 필요한 대상을 검증해야 할 때 사용하는, 인터랙티브 CLI 테스트용 드라이버.
3. 데이터 가져오기 및 분석
데이터 및 모니터링 스택에 연결하는 스킬입니다. 이런 스킬에는 자격 증명을 이용해 데이터를 가져오는 라이브러리, 특정 대시보드 ID, 자주 사용하는 워크플로우나 데이터를 얻는 방법에 대한 안내가 포함될 수 있습니다.
예시:
funnel-query— “가입 → 활성화 → 유료 전환을 보려면 어떤 이벤트를 조인해야 하는가”에 대한 설명과, 실제로 canonical user_id를 담고 있는 테이블 정보.cohort-compare— 두 코호트의 리텐션이나 전환율을 비교하고, 통계적으로 유의미한 차이를 표시하며, 세그먼트 정의로 연결.grafana— 데이터소스 UID, 클러스터 이름, 문제 유형 → 대시보드 매핑 테이블.
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 및 배포
코드베이스 안에서 코드를 가져오고(fetch), 푸시하고, 배포하는 데 도움을 주는 스킬입니다. 이런 스킬은 데이터를 수집하기 위해 다른 스킬을 참조할 수도 있습니다.
예시:
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의 “기본적인 사고방식”에서 벗어나도록 도와주는 정보에 집중해 보세요.
예를 들어 frontend design skill 은 Claude의 디자인 취향을 개선하고, Inter 폰트나 보라색 그라데이션 같은 흔한 패턴을 피하도록 하기 위해, Anthropic의 한 엔지니어가 고객과 함께 반복적으로 개선해 가며 만든 스킬입니다.
놓치기 쉬운 함정들(Gotchas)을 정리한 섹션 만들기
어떤 스킬이든 가장 신호가 강한(high-signal) 콘텐츠는 Gotchas 섹션입니다. 이 섹션은 Claude가 스킬을 사용할 때 반복적으로 부딪히는 실패 지점들로부터 만들어야 합니다. 이상적으로는 Claude가 새로운 문제에 부딪힐 때마다, 그때그때 Gotchas를 추가하며 스킬을 발전시켜야 합니다.
파일 시스템과 점진적 공개 기법 활용
앞에서 말했듯이, 스킬은 폴더이지 단순한 마크다운 파일이 아닙니다. 전체 파일 시스템을 컨텍스트 엔지니어링 및 점진적 공개(progressive disclosure)를 위한 수단이라고 생각해야 합니다. 스킬에 어떤 파일들이 있는지 Claude에게 알려주면, Claude는 적절한 시점에 해당 파일을 읽어 활용합니다.
가장 단순한 형태의 점진적 공개는 Claude가 활용해야 할 다른 마크다운 파일을 가리키는 방식입니다. 예를 들어, 자세한 함수 시그니처와 사용 예제를 references/api.md로 분리해 둘 수 있습니다.
또 다른 예로, 최종 산출물이 마크다운 파일이라면 Claude가 복사해서 사용할 수 있도록 assets/ 폴더에 템플릿 파일을 포함할 수도 있습니다.
참조 자료, 스크립트, 예제 등을 모아둔 폴더를 두면, Claude가 더 효과적으로 작업하는 데 큰 도움이 됩니다.
클로드를 정해진 패턴으로만 몰아가지 마세요
Claude는 일반적으로 여러분의 지침을 따르려 노력합니다. 그리고 스킬은 재사용성이 매우 높기 때문에, 지침을 지나치게 구체적으로 작성하면 문제가 될 수 있습니다. Claude에게 필요한 정보는 제공하되, 상황에 맞게 유연하게 대응할 수 있는 여지는 남겨 두세요. 예를 들면:
설정 전체를 꼼꼼하게 고민하세요
일부 스킬은 사용자로부터 제공받은 컨텍스트를 기반으로 셋업이 필요할 수 있습니다. 예를 들어, 스탠드업을 Slack에 게시하는 스킬을 만든다면, 어느 Slack 채널에 게시할지 Claude가 먼저 물어보게 하고 싶을 수 있습니다.
좋은 패턴은 이런 셋업 정보를 스킬 디렉토리 안의 config.json 파일에 저장하는 것입니다. 위 예시처럼 구성해 두면, 설정이 되어 있지 않을 때 에이전트가 사용자에게 필요한 정보를 물어볼 수 있습니다.
사용자에게 구조화된 객관식 질문을 제시하고 싶다면, AskUserQuestion 도구를 사용하도록 Claude에게 지시할 수도 있습니다.
Description 필드는 사용자용이 아니라 모델용입니다
Claude Code가 세션을 시작할 때, 사용 가능한 모든 스킬과 그 설명을 나열한 목록을 만듭니다. Claude는 이 목록을 훑어보면서 “이 요청에 맞는 스킬이 있는가?”를 판단합니다. 즉, 설명(description) 필드는 요약(summary)이 아니라, “언제 이 스킬을 호출해야 하는지”를 모델에게 알려주는 설명이어야 합니다.
메모리 관리와 데이터 저장
일부 스킬은 내부에 데이터를 저장하는 방식으로 일종의 메모리 기능을 포함할 수 있습니다. 단순한 append-only 텍스트 로그 파일이나 JSON 파일처럼 간단한 형태일 수도 있고, SQLite 데이터베이스처럼 더 복잡한 형태일 수도 있습니다.
예를 들어 standup-post 스킬은 지금까지 작성한 모든 스탠드업을 standups.log 파일에 기록해 둘 수 있습니다. 그러면 다음에 실행할 때 Claude가 자신의 기록을 읽고, 어제와 비교해 무엇이 달라졌는지 스스로 파악할 수 있습니다.
스킬 디렉토리에 저장된 데이터는 스킬을 업그레이드할 때 삭제될 수 있으므로, 이런 데이터는 안정적인 폴더에 저장하는 것이 좋습니다. 현재는 플러그인마다 안정적인 데이터 저장 폴더로 ${CLAUDE_PLUGIN_DATA}를 제공하고 있습니다.
스크립트 저장 및 코드 생성
Claude에게 줄 수 있는 가장 강력한 도구 중 하나는 코드입니다. 스크립트와 라이브러리를 제공하면, Claude는 보일러플레이트를 매번 다시 만드는 대신 “다음에 무엇을 해야 할지”를 구성하는 데 더 많은 턴을 쓸 수 있습니다.
예를 들어 데이터 사이언스 스킬 안에 이벤트 소스에서 데이터를 가져오기 위한 함수 라이브러리를 제공할 수 있습니다. 그리고 “화요일에 무슨 일이 있었는지 알려줘”와 같은 프롬프트에 대해 복잡한 분석을 수행할 수 있도록, 다음과 같은 헬퍼 함수들을 제공한다고 해봅시다:
그러면 Claude는 이런 기능을 조합하는 스크립트를 즉석에서 생성해, 더 고급 분석을 수행할 수 있습니다.
온디맨드 훅(요청 기반 훅)
스킬에는 해당 스킬이 호출되었을 때만 활성화되고, 세션이 유지되는 동안에만 동작하는 훅을 포함할 수 있습니다. 항상 켜두기는 어렵지만, 특정 시점에는 매우 유용한, 좀 더 강한 의견을 가진 훅들(opinionated hooks)에 이 방식을 사용하세요.
예를 들어:
/careful— Bash에서rm -rf,DROP TABLE, force-push,kubectl delete를 PreToolUse 매처를 통해 막는 스킬. 프로덕션을 다룬다는 것을 알고 있을 때만 켜두고 싶을 것이며, 항상 켜져 있다면 미치고 말 겁니다./freeze— 특정 디렉토리가 아닌 곳에서의 Edit/Write를 모두 막습니다. 디버깅할 때 “로그를 추가하고 싶은데, 자꾸 관련 없는 부분까지 ‘고쳐버리는’ 상황”에서 유용합니다.
스킬 배포하기
스킬의 가장 큰 장점 중 하나는 팀원들과 공유할 수 있다는 점입니다.
스킬을 다른 사람과 공유하는 방법은 크게 두 가지가 있습니다.
- 스킬을 저장소(repo)에 체크인한다(
./.claude/skills경로 아래). - 플러그인을 만들어 Claude Code 플러그인 마켓플레이스를 구축하고, 사용자가 플러그인을 업로드·설치할 수 있게 한다(자세한 내용은 문서 참고).
상대적으로 적은 수의 저장소에서 작업하는 소규모 팀이라면, 스킬을 저장소에 체크인하는 방식이 잘 동작합니다. 다만, 저장소에 체크인된 각 스킬은 모델의 컨텍스트를 조금씩이나마 더 차지하게 됩니다. 조직이 커질수록, 내부 플러그인 마켓플레이스를 통해 스킬을 배포하고, 팀이 어떤 스킬을 설치할지 선택하게 하는 방식이 더 적합합니다.
마켓플레이스 운영/관리하기
어떤 스킬을 마켓플레이스에 넣을지, 어떻게 제출받을지 어떻게 결정해야 할까요?
우리는 중앙에서 모든 것을 결정하는 전담 팀을 두지 않습니다. 대신, 가장 유용한 스킬들을 자연스럽게 찾으려고 합니다. 누군가 다른 사람들도 써보길 원하는 스킬이 있다면, GitHub의 샌드박스 폴더에 업로드하고 Slack이나 다른 포럼에서 그 스킬을 소개하면 됩니다.
그 후 스킬이 어느 정도 반응을 얻었다고 판단되면(그 판단은 스킬 소유자에게 맡깁니다), 마켓플레이스로 옮기기 위한 PR을 올릴 수 있습니다.
주의할 점은, 형편없거나 중복된 스킬을 만드는 것은 생각보다 아주 쉽다는 것입니다. 따라서 공개 전에 일정 수준의 검증 과정을 거치도록 하는 것이 중요합니다.
스킬을 조합하기
서로 의존 관계를 맺는 스킬들이 필요할 때도 있습니다. 예를 들어 파일을 업로드하는 스킬과, CSV를 생성해서 업로드하는 스킬이 따로 있을 수 있습니다. 이런 종류의 의존성 관리는 아직 마켓플레이스나 스킬 시스템에 네이티브로 내장되어 있지는 않지만, 스킬 이름을 참조하는 것만으로도 해결할 수 있습니다. 해당 스킬이 설치되어 있다면, 모델이 알아서 호출해 줍니다.
스킬 성능 측정하기
스킬이 얼마나 잘 작동하는지 이해하기 위해, 우리는 회사 내부에서 스킬 사용량을 로깅하기 위한 PreToolUse 훅을 사용합니다(예시 코드
참고). 이를 통해 어떤 스킬이 인기 있는지, 기대했던 것보다 덜 호출되는 스킬은 무엇인지 파악할 수 있습니다.
결론
스킬은 에이전트에게 있어 믿을 수 없을 만큼 강력하고 유연한 도구이지만, 아직은 초기 단계이며 우리 모두가 어떻게 활용하는 것이 최선인지 탐색해 나가고 있는 중입니다.
이 글을 결정적인 가이드라기보다는, 우리가 실제로 효과를 본 유용한 팁 모음 정도로 생각해 주시면 좋겠습니다. 스킬을 이해하는 가장 좋은 방법은 직접 만들어 보고, 실험하고, 자신에게 잘 맞는 방식을 찾아보는 것입니다. 우리가 사용하는 대부분의 스킬도 처음에는 몇 줄과 단 하나의 gotcha에서 출발했으며, 사람들이 새로운 엣지 케이스에 부딪힐 때마다 내용을 조금씩 추가해 가며 더 좋아졌습니다.