클로드 코드에서 Skills는 가장 많이 사용되는 확장 포인트 중 하나로, Anthropic 내부에서 수백 개의 스킬을 실제로 운용하며 축적한 실전 노하우를 공개
스킬은 단순 마크다운 파일이 아니라 스크립트, 에셋, 데이터 등을 포함하는 폴더 구조이며, 에이전트가 탐색하고 활용할 수 있는 형태
라이브러리 레퍼런스, 제품 검증, 데이터 분석, 코드 스캐폴딩, CI/CD 등 9가지 스킬 카테고리로 분류되며, 좋은 스킬은 하나의 카테고리에 깔끔히 맞아야 함
스킬 작성 시 Gotchas 섹션, 파일 시스템 활용, 점진적 공개(Progressive Disclosure), 데이터 저장 등의 실전 팁이 핵심
조직 확장 시에는 내부 플러그인 마켓플레이스를 통해 스킬을 배포하고, 사용량 측정 훅으로 효과를 추적하는 구조 권장
Skills란 무엇인가
Skills에 대한 흔한 오해는 "그냥 마크다운 파일"이라는 것이지만, 실제로는 스크립트, 에셋, 데이터 등을 포함하는 폴더 구조
에이전트가 이 폴더를 탐색하고, 내용을 발견하고, 조작할 수 있음
Claude Code에서 Skills는 다양한 설정 옵션을 제공하며, 동적 훅(dynamic hooks) 등록도 가능
가장 흥미로운 스킬들은 이러한 설정 옵션과 폴더 구조를 창의적으로 활용하는 것들
스킬의 9가지 카테고리
내부에서 사용 중인 스킬을 모두 분류한 결과, 반복적으로 나타나는 몇 가지 카테고리로 클러스터링됨
좋은 스킬은 하나의 카테고리에 깔끔히 맞고, 혼란스러운 스킬은 여러 카테고리에 걸쳐 있음
1. Library & API Reference
라이브러리, CLI, SDK를 올바르게 사용하는 방법을 설명하는 스킬
내부 라이브러리뿐 아니라 Claude Code가 자주 실수하는 일반 라이브러리도 대상
레퍼런스 코드 스니펫 폴더와 주의사항(gotchas) 목록을 포함하는 경우가 많음
예시: billing-lib(내부 결제 라이브러리의 엣지 케이스), internal-platform-cli(내부 CLI 래퍼의 모든 서브커맨드와 사용 예시), frontend-design(디자인 시스템 적용 개선)
2. Product Verification
코드가 정상 동작하는지 테스트하고 검증하는 방법을 기술하는 스킬
Playwright, tmux 등 외부 도구와 결합하여 사용하는 경우가 많음
Claude의 출력 정확성 보장에 매우 유용하며, 엔지니어가 일주일을 투자해서라도 검증 스킬을 우수하게 만들 가치가 있음
Claude가 출력을 영상으로 녹화하도록 하거나, 각 단계에서 상태에 대한 프로그래매틱 어설션을 강제하는 기법 권장
예시: signup-flow-driver(가입→이메일 인증→온보딩을 헤드리스 브라우저로 수행), checkout-verifier(Stripe 테스트 카드로 결제 UI 구동 후 인보이스 상태 검증), tmux-cli-driver(TTY가 필요한 인터랙티브 CLI 테스트용)
3. Data Fetching & Analysis
데이터 및 모니터링 스택에 연결하는 스킬
크레덴셜이 포함된 데이터 가져오기 라이브러리, 특정 대시보드 ID, 일반적 워크플로우 안내 등을 포함
예시: funnel-query(가입→활성화→결제 퍼널에 필요한 이벤트와 canonical user_id가 있는 테이블), cohort-compare(두 코호트의 리텐션/전환율 비교 및 통계적 유의성 플래깅), grafana(데이터소스 UID, 클러스터명, 문제→대시보드 룩업 테이블)
4. Business Process & Team Automation
반복적인 워크플로우를 하나의 명령으로 자동화하는 스킬
비교적 단순한 지시문이지만 다른 스킬이나 MCP에 대한 복잡한 의존성을 가질 수 있음
이전 실행 결과를 로그 파일에 저장하면 모델이 일관성을 유지하고 이전 실행을 반영하는 데 도움
예시: standup-post(티켓 트래커, GitHub 활동, Slack을 종합한 포맷 스탠드업), create-ticket(스키마 강제 및 생성 후 워크플로우), weekly-recap(머지된 PR+닫힌 티켓+배포를 요약 포스트로 작성)
5. Code Scaffolding & Templates
코드베이스의 특정 기능에 대한 프레임워크 보일러플레이트를 생성하는 스킬
조합 가능한 스크립트와 결합할 수 있으며, 코드만으로는 다 커버할 수 없는 자연어 요구사항이 있을 때 특히 유용
예시: new-framework-workflow(어노테이션 포함 새 서비스/워크플로우/핸들러 스캐폴딩), new-migration(마이그레이션 파일 템플릿과 주의사항), create-app(인증, 로깅, 배포 설정이 미리 연결된 새 내부 앱)
6. Code Quality & Review
조직 내 코드 품질을 강제하고 코드 리뷰를 돕는 스킬
최대한의 견고성을 위해 결정론적 스크립트나 도구를 포함할 수 있음
훅이나 GitHub Action의 일부로 자동 실행할 수도 있음
예시: adversarial-review(새로운 시각의 서브에이전트가 비판→수정→반복하여 지적이 니트픽 수준으로 떨어질 때까지 진행), code-style(Claude가 기본적으로 잘 못하는 코드 스타일 강제), testing-practices(테스트 작성 방법과 테스트 대상 안내)
7. CI/CD & Deployment
코드베이스 내에서 코드를 가져오고, 푸시하고, 배포하는 스킬
다른 스킬을 참조하여 데이터를 수집할 수 있음
예시: babysit-pr(PR 모니터링→flaky CI 재시도→머지 충돌 해결→자동 머지 활성화), deploy-service(빌드→스모크 테스트→점진적 트래픽 롤아웃→에러율 비교→회귀 시 자동 롤백), cherry-pick-prod(격리된 worktree→cherry-pick→충돌 해결→템플릿 PR 생성)
8. Runbooks
증상(Slack 스레드, 알림, 에러 시그니처 등)을 입력받아 멀티 도구 조사를 수행하고 구조화된 리포트를 생성하는 스킬
예시: service-debugging(증상→도구→쿼리 패턴 매핑), oncall-runner(알림 가져오기→일반적 원인 체크→결과 포맷팅), log-correlator(요청 ID로 관련 시스템 전체 로그 수집)
9. Infrastructure Operations
일상적 유지보수와 운영 절차를 수행하며, 파괴적 작업에 대한 가드레일을 포함하는 스킬
엔지니어가 중요 운영에서 베스트 프랙티스를 따르기 쉽게 해줌
예시: resource-orphans(고아 Pod/볼륨 탐색→Slack 알림→대기 기간→사용자 확인→계단식 정리), dependency-management(조직의 의존성 승인 워크플로우), cost-investigation(스토리지/이그레스 비용 급증 원인 조사용 버킷 및 쿼리 패턴)
스킬 작성 팁
당연한 것은 쓰지 말 것
Claude Code는 코드베이스에 대해 이미 많이 알고 있고, 코딩에 대한 기본 의견도 가지고 있음
지식 중심 스킬을 만든다면 Claude의 일반적 사고방식에서 벗어나게 하는 정보에 집중해야 함
frontend-design 스킬이 좋은 예시로, Anthropic 엔지니어가 고객과 반복하며 Claude의 디자인 감각을 개선하기 위해 만든 것이며, Inter 폰트와 보라색 그라디언트 같은 전형적 패턴을 피하도록 구성
Gotchas 섹션 구축
모든 스킬에서 가장 높은 신호 가치를 가지는 콘텐츠가 Gotchas 섹션
Claude가 스킬 사용 시 흔히 만나는 실패 지점에서 축적해야 함
시간이 지나면서 이러한 gotchas를 계속 업데이트하는 것이 이상적
파일 시스템과 점진적 공개 활용
스킬은 폴더이므로 전체 파일 시스템을 컨텍스트 엔지니어링과 점진적 공개의 수단으로 활용해야 함
Claude에게 스킬에 어떤 파일이 있는지 알려주면, 적절한 시점에 읽음
가장 단순한 형태: 상세 함수 시그니처와 사용 예시를 references/api.md 같은 별도 마크다운으로 분리
최종 출력이 마크다운인 경우 assets/ 폴더에 템플릿 파일 포함 가능
레퍼런스, 스크립트, 예시 등의 폴더가 Claude의 작업 효율을 높임
Claude를 과도하게 제약하지 말 것
Claude는 지시사항을 따르려 하지만, 스킬은 재사용성이 높으므로 지나치게 구체적인 지시는 주의해야 함
필요한 정보는 주되, 상황에 유연하게 적응할 수 있는 여지를 줘야 함
설정(Setup) 과정 설계
일부 스킬은 사용자로부터 컨텍스트를 수집하는 설정 단계가 필요
예: 스탠드업을 Slack에 올리는 스킬이라면 어느 채널에 올릴지 물어야 함
좋은 패턴: 설정 정보를 스킬 디렉토리의 config.json 파일에 저장, 설정이 안 되어 있으면 에이전트가 사용자에게 질문
구조화된 다중 선택 질문을 제시하려면 AskUserQuestion 도구 사용을 지시 가능
Description 필드는 모델을 위한 것
Claude Code가 세션을 시작하면 모든 가용 스킬의 description 목록을 빌드함
이 목록을 Claude가 스캔하여 "이 요청에 맞는 스킬이 있는가?"를 판단
따라서 description 필드는 요약이 아니라 이 스킬을 언제 트리거해야 하는지의 설명
메모리 및 데이터 저장
스킬에 데이터를 저장하는 형태의 메모리를 포함할 수 있음
단순한 텍스트 로그 파일이나 JSON 파일부터 SQLite 데이터베이스까지 다양한 형태 가능
예: standup-post 스킬이 standups.log에 모든 작성 이력을 저장하면, 다음 실행 시 Claude가 자신의 이력을 읽고 어제 이후 변경사항을 파악
스킬 디렉토리에 저장한 데이터는 스킬 업그레이드 시 삭제될 수 있으므로 ${CLAUDE_PLUGIN_DATA}라는 안정적 폴더에 저장해야 함
스크립트 저장 및 코드 생성
Claude에게 줄 수 있는 가장 강력한 도구 중 하나가 코드 자체
스크립트와 라이브러리를 제공하면 Claude가 보일러플레이트 재구성 대신 구성(composition)에 집중 가능
예: 데이터 과학 스킬에 이벤트 소스에서 데이터를 가져오는 헬퍼 함수 라이브러리 포함
Claude가 이 기능들을 조합하여 즉석에서 스크립트를 생성, "화요일에 무슨 일이 있었나?" 같은 복잡한 분석에 활용
On Demand Hooks
스킬이 호출될 때만 활성화되고 세션 동안만 지속되는 훅을 포함할 수 있음
항상 실행하기에는 부담스럽지만 특정 상황에서 매우 유용한 강한 의견의 훅에 적합
예시:
/careful — rm -rf, DROP TABLE, force-push, kubectl delete를 PreToolUse 매처로 차단, 프로덕션 작업 시에만 활성화
/freeze — 특정 디렉토리 외의 모든 Edit/Write를 차단, 디버깅 시 의도치 않은 수정 방지에 유용
스킬 배포
스킬의 큰 장점 중 하나는 팀 전체와 공유 가능하다는 점
두 가지 공유 방식 존재:
스킬을 리포에 체크인 (./.claude/skills 아래)
플러그인으로 만들어 Claude Code Plugin 마켓플레이스에 업로드, 사용자가 설치
마켓플레이스 관리
소규모 팀이 소수 리포에서 작업할 때는 리포에 체크인하는 방식이 적합
체크인된 스킬은 모델의 컨텍스트에 조금씩 추가되므로, 규모가 커지면 내부 플러그인 마켓플레이스가 유리
마켓플레이스에 들어갈 스킬을 결정하는 중앙 팀은 없으며, 가장 유용한 스킬이 자연스럽게 발견되는 방식
시도해볼 스킬이 있으면 GitHub의 sandbox 폴더에 업로드하고 Slack 등에서 안내
충분한 견인력(traction)을 얻으면 스킬 소유자가 마켓플레이스로 이동하는 PR을 올림
나쁘거나 중복된 스킬이 쉽게 만들어질 수 있으므로 릴리스 전 큐레이션 메커니즘이 중요
스킬 조합(Composing Skills)
스킬 간 의존성이 필요할 수 있음 (예: 파일 업로드 스킬 + CSV 생성 및 업로드 스킬)
마켓플레이스나 스킬에 의존성 관리가 네이티브로 내장되어 있지는 않지만, 다른 스킬을 이름으로 참조하면 설치되어 있는 경우 모델이 호출
스킬 측정
스킬의 성과를 파악하기 위해 PreToolUse 훅으로 회사 내 스킬 사용량을 로깅
인기 있는 스킬이나 기대 대비 트리거가 부족한 스킬을 찾는 데 활용
결론
Skills는 에이전트를 위한 매우 강력하고 유연한 도구이지만, 아직 초기 단계이며 모두가 최선의 활용법을 찾아가는 과정
이 글은 확정적 가이드가 아니라 실전에서 효과가 있었던 팁 모음
대부분의 스킬은 몇 줄과 하나의 gotcha에서 시작했으며, Claude가 새로운 엣지 케이스를 만날 때마다 사람들이 계속 추가하면서 개선