Anthropic의 Claude Code 팀이 자사 내부 스킬 운영 경험을 공개했습니다. Claude Code에서 스킬이 어떤 카테고리로 나뉘는지, 그리고 품질 높은 스킬을 만드는 데 어떤 원칙을 따르는지를 담은 글입니다. 특히 “Verification 스킬이 출력 품질에 가장 측정 가능한 영향을 미쳤다”는 내부 증언은 실무자라면 눈여겨볼 만합니다.
출처: Lessons from building Claude Code: How we use skills – Anthropic Blog
스킬이란 무엇인가
Claude Code에서 스킬은 단순한 마크다운 파일이 아닙니다. 하나의 폴더입니다. SKILL.md를 중심으로 레퍼런스 코드, 스크립트, 예시 파일 등을 함께 담아두는 구조로, Claude는 필요한 시점에 해당 파일들을 꺼내 읽습니다. Anthropic은 이 파일 시스템 전체를 “컨텍스트 엔지니어링”이라고 부릅니다.
Claude Code를 그냥 쓰는 것과, 조직의 맥락을 담은 스킬로 무장해서 쓰는 것은 출력 품질에서 실질적인 차이를 만듭니다. Claude는 코드 작성법은 이미 알고 있지만, 여러분 조직의 내부 라이브러리 규칙, 특이한 데이터 구조, 반복되는 배포 절차는 모릅니다. 스킬이 그 간격을 채웁니다.
Anthropic이 분류한 스킬 9가지
Anthropic은 내부 스킬 전체를 정리해보니 9개 카테고리로 묶였다고 밝혔습니다. 하나의 스킬이 여러 카테고리에 걸치면 오히려 에이전트가 혼란스러워진다는 점도 함께 지적했습니다.
- 라이브러리·API 레퍼런스 — 내부 라이브러리나 CLI 사용법, 흔히 실수하는 지점(gotchas)을 담은 스킬
- 코드 검증(Product verification) — Playwright, tmux 등을 활용해 결과물을 테스트하는 스킬. Anthropic 내부에서 출력 품질에 가장 눈에 띄는 영향을 미친 유형
- 데이터 조회·분석 — 데이터 스택에 접근하고 일반적인 분석 워크플로를 수행하는 스킬
- 비즈니스 프로세스·팀 자동화 — 스탠드업 포스팅, 티켓 생성 등 반복적인 업무 흐름을 자동화하는 스킬
- 코드 스캐폴딩·템플릿 — 특정 프레임워크나 기능의 보일러플레이트를 생성하는 스킬
- 코드 품질·리뷰 — 코드 스타일 적용, 테스트 작성 기준 등 품질 기준을 강제하는 스킬
- CI/CD·배포 — PR 모니터링, 배포, 롤백 등 코드 이동과 관련된 스킬
- 런북(Runbooks) — 증상(Slack 알림, 에러 서명 등)을 입력으로 받아 다중 도구 조사 후 구조화된 리포트를 만드는 스킬
- 인프라 운영 — 고아 리소스 정리, 의존성 관리, 비용 조사 등 운영 절차를 담은 스킬
잘 만든 스킬의 세 가지 특징
Gotchas 섹션이 핵심이다
Anthropic 팀은 스킬에서 신호 대비 가장 가치 있는 내용이 Gotchas 섹션이라고 강조합니다. Claude가 기본적으로 하는 행동을 다시 설명하는 스킬은 컨텍스트만 낭비합니다. 반면 Claude가 반복적으로 틀리는 지점을 포착해 쌓아둔 Gotchas는 실질적인 출력 개선으로 이어집니다.
예를 들어 “이 필드는 API 게이트웨이에서는 @request_id라고 부르고, 빌링 서비스에서는 trace_id라고 부른다. 같은 값이다”처럼 조직 내부에서만 알 수 있는 함정을 기록해두는 방식입니다.
description은 사람이 아니라 모델이 읽는다
Claude Code가 세션을 시작할 때, 설치된 모든 스킬의 description을 훑어보고 “이 요청에 쓸 스킬이 있는가”를 판단합니다. 즉 description은 스킬 소개가 아니라, 언제 이 스킬을 실행할지를 모델에게 알려주는 트리거입니다. “standup을 작성할 때”, “PR을 babysit할 때”처럼 실제 실행 조건을 명시해야 합니다.
파일 시스템 전체를 활용하라
스킬 폴더 안에는 다른 마크다운 파일, 스크립트, 템플릿, 헬퍼 함수 라이브러리 등을 함께 넣을 수 있습니다. SKILL.md가 상황에 따라 Claude에게 참조할 파일을 안내하면, Claude는 그때그때 필요한 파일을 꺼내 읽습니다. 복잡한 스킬일수록 이 구조를 활용해 맥락을 필요한 시점에만 불러오는 점진적 공개 방식이 효과적입니다.
스킬 설계력이 AI 활용 역량이 되는 시대
이 글이 흥미로운 이유는 단순한 사용법 소개가 아니라, Anthropic 팀이 자기 자신을 위해 만든 스킬 체계를 그대로 공개했다는 점입니다. Claude Code에 어떤 지식을 어떻게 담을지 설계하는 능력, 즉 스킬 설계력이 AI 도구 활용 역량의 핵심으로 부상하고 있다는 신호로도 읽힙니다.
원문은 이 외에도 스킬 마켓플레이스 운영 방식, 스킬 간 의존성 관리, PreToolUse 훅을 통한 스킬 사용량 측정 방법도 다룹니다. 스킬을 팀 단위로 운영하려는 분이라면 원문에서 더 구체적인 내용을 확인해보세요.
답글 남기기