# Claude Code를 만들며 배운 것: 우리가 Skills를 사용하는 방법

> Clean Markdown view of GeekNews topic #27640. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=27640](https://news.hada.io/topic?id=27640)
- GeekNews Markdown: [https://news.hada.io/topic/27640.md](https://news.hada.io/topic/27640.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-03-19T11:09:01+09:00
- Updated: 2026-03-19T11:09:01+09:00
- Original source: [x.com/trq212](https://x.com/trq212/status/2033949937936085378?s=12&t=1bi3eg1xL3Pa2E0i0jg18g)
- Points: 102
- Comments: 1

## Summary

에이전트가 코드를 다루는 방식이 바뀌고 있습니다. Anthropic이 공개한 **Skills** 개념은 단순한 프롬프트 확장이 아니라, 폴더 단위로 스크립트·데이터·에셋을 묶어 모델이 직접 탐색하고 실행할 수 있게 하는 구조입니다. 개발자 입장에서는 “모델이 어떤 도구를 언제 써야 하는가”를 코드로 정의할 수 있게 된 셈이며, 특히 gotchas 섹션과 점진적 공개 패턴은 프롬프트 엔지니어링보다 훨씬 재현성 있는 협업 단위를 제공합니다. 스킬은 모델의 능력을 늘리는 게 아니라, 조직의 개발 문화를 코드화하는 새로운 인터페이스 입니다.

## Topic Body

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

## Comments



### Comment 53359

- Author: xguru
- Created: 2026-03-19T13:09:51+09:00
- Points: 3

요즘 Anthropic을 보며 느끼는 건, 개발 담당자들이 최대한 경험한 것들을 공유하면서 자신들의 제품을 더 잘 쓰도록 유도한다는 것  
  
"AI 시대의 개발 생태계는 이렇게 만들어 가는 겁니다" 를 몸소 보여주는 사례 같아요.