- 클로드 코드에서 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가 새로운 엣지 케이스를 만날 때마다 사람들이 계속 추가하면서 개선