Anthropic 내부에서 수백 개의 Skills를 운영하고 있다면 어떤 모습일까요? Claude Code를 개발하는 엔지니어 Thariq이 팀의 실전 경험을 X(트위터)에 공개했습니다. Skills가 단순한 텍스트 파일이라는 흔한 오해를 깨고, 실제로 어떤 유형이 효과적이며 어떻게 만들어야 하는지를 담은 긴 글입니다.

출처: Lessons from Building Claude Code: How We Use Skills – Thariq (@trq212) on X

Skills는 폴더입니다, 파일이 아니라

“Skills는 그냥 마크다운 파일 아닌가요?” 가장 흔한 오해입니다. Thariq에 따르면 Skills의 핵심은 스크립트, 에셋, 데이터 등을 포함할 수 있는 폴더 구조 그 자체입니다. 에이전트가 이 폴더 안을 탐색하고, 필요한 시점에 적절한 파일을 읽어 활용합니다. Claude Code에서는 동적 훅(hook) 등록을 포함한 다양한 설정 옵션도 지원됩니다.

이 구조 덕분에 Skills는 단순한 지침 문서를 넘어, 헬퍼 스크립트와 레퍼런스 코드, 설정 파일이 결합된 미니 에이전트 확장 시스템으로 기능합니다.

Anthropic이 분류한 9가지 Skills 유형

수백 개의 Skills를 운영하면서 팀이 발견한 것은, 가장 잘 동작하는 Skills는 뚜렷한 카테고리 안에 속한다는 점입니다. 경계가 모호한 Skills일수록 잘 작동하지 않았습니다.

라이브러리 & API 레퍼런스: 내부 라이브러리나 CLI를 올바르게 사용하는 방법을 담는 유형입니다. 레퍼런스 코드 스니펫 폴더와 흔히 빠지는 함정(Gotchas) 목록을 함께 포함하면 효과적입니다.

제품 검증(Product Verification): 코드가 제대로 작동하는지 테스트하는 유형입니다. Playwright, tmux 같은 외부 도구와 결합해 사용하며, 검증 스크립트를 Skills 안에 포함시킵니다. 엔지니어 한 명이 일주일을 투자해 검증 Skills를 정교하게 만드는 것이 충분히 가치 있다고 팀은 강조합니다.

데이터 조회 & 분석: 데이터 스택에 연결하는 유형으로, 자격증명, 대시보드 ID, 공통 쿼리 패턴 등을 담습니다. 실제 테이블 구조나 이벤트 조인 방식처럼 Claude가 스스로 알기 어려운 내부 맥락이 핵심 내용이 됩니다.

업무 프로세스 자동화: 반복적인 워크플로를 하나의 명령으로 압축하는 유형입니다. 스탠드업 포스팅, 티켓 생성, 주간 리뷰 정리 등이 대표 예시입니다. 이전 실행 결과를 로그 파일로 저장하면 모델이 일관성을 유지하는 데 도움이 됩니다.

코드 스캐폴딩 & 템플릿: 특정 기능의 보일러플레이트를 생성하는 유형입니다. 코드만으로는 표현하기 어려운 자연어 요구사항이 있을 때 특히 유용합니다.

이 외에도 코드 품질 & 리뷰(코드 스타일 강제, adversarial 서브에이전트 활용), CI/CD & 배포(PR 모니터링, 점진적 트래픽 롤아웃), 런북(증상 → 조사 → 리포트 자동화), 인프라 운영(고위험 작업에 가드레일 부여) 유형이 있습니다.

좋은 Skills를 만드는 원칙들

당연한 내용은 쓰지 마세요. Claude는 코딩에 대해 이미 많이 알고 있습니다. Skills의 가치는 Claude의 기본 방식에서 벗어나게 만드는 정보에 있습니다. 팀이 만든 frontend-design Skills는 Inter 폰트나 보라색 그라디언트 같은 AI가 습관적으로 선택하는 패턴을 피하도록 설계된 좋은 사례입니다.

Gotchas 섹션이 가장 중요합니다. Skills에서 신호 대 잡음비가 가장 높은 내용은 Claude가 실제로 실패했던 지점들입니다. 이 섹션은 운영하면서 지속적으로 업데이트해야 합니다.

파일 시스템을 맥락 엔지니어링으로 활용하세요. 상세 API 문서는 references/api.md로 분리하고, 결과물 템플릿은 assets/에 두는 식으로 점진적 공개(progressive disclosure) 구조를 만들면, Claude가 적절한 시점에 적절한 파일만 읽습니다.

Claude를 너무 꽉 조이지 마세요. Skills는 재사용성이 높은 만큼, 지침이 지나치게 구체적이면 오히려 특정 상황에서 Claude가 유연하게 대처하지 못합니다. 필요한 정보는 주되, 상황에 맞게 판단할 여지를 남겨두는 것이 중요합니다.

설정(Setup)을 미리 고민하세요. 사용자 컨텍스트가 필요한 Skills(예: 어느 Slack 채널에 포스팅할지)는 config.json을 Skills 디렉터리에 두고, 설정이 없을 때 에이전트가 사용자에게 묻도록 구성할 수 있습니다. 구조화된 선택지를 제시하려면 AskUserQuestion 툴을 활용하면 됩니다.

description 필드는 사람이 아닌 모델을 위한 것입니다. Claude Code가 세션을 시작할 때 모든 Skills의 설명을 한 번에 읽고 적합한 Skills를 선택합니다. 따라서 description은 “이 Skills가 무엇인가”가 아니라 “언제 이 Skills를 호출해야 하는가”를 담아야 합니다.

Skills에 메모리를 부여할 수 있습니다. 텍스트 로그나 JSON 파일로 이전 실행 결과를 저장하면, 다음 실행 시 Claude가 이전 맥락을 참조합니다. Skills 디렉터리 자체는 업그레이드 시 삭제될 수 있으므로, 안정적인 데이터 저장에는 ${CLAUDE_PLUGIN_DATA} 환경 변수가 가리키는 폴더를 사용하는 것이 권장됩니다.

스크립트를 심어두면 Claude가 구성에 집중합니다. Skills 안에 헬퍼 함수와 라이브러리를 포함해두면, Claude는 처음부터 코드를 작성하는 대신 이것들을 조합하는 데 집중할 수 있습니다. 데이터 분석 Skills에서 이벤트 소스를 불러오는 헬퍼 함수들을 제공하면, “지난 화요일에 무슨 일이 있었나요?”처럼 자연어로 복잡한 분석도 가능해집니다.

온디맨드 훅으로 선택적 제어를 구현하세요. Skills는 호출될 때만 활성화되고 세션 동안만 유지되는 훅을 포함할 수 있습니다. 프로덕션 작업 시에만 rm -rf나 DROP TABLE을 차단하는 /careful, 디버깅 중 의도치 않은 파일 수정을 막는 /freeze 등이 실제 활용 사례입니다. 항상 켜두면 불편하지만, 특정 상황에서는 꼭 필요한 훅이 바로 이 유형입니다.

Skills를 팀과 나누는 방법

Skills를 공유하는 방법은 두 가지입니다. 레포에 직접 체크인(./claude/skills)하거나, 내부 플러그인 마켓플레이스를 운영하는 방식입니다. 소규모 팀에는 레포 체크인이 간편하지만, Skills가 늘어날수록 모델의 컨텍스트에 부담이 됩니다. 규모가 커지면 팀원이 필요한 Skills만 선택적으로 설치하는 마켓플레이스 방식이 효율적입니다.

Anthropic 내부에서는 중앙 집중식 관리 대신 유기적으로 인기를 얻은 Skills가 마켓플레이스에 진입하는 방식을 씁니다. 부실하거나 중복된 Skills가 쉽게 만들어질 수 있는 만큼, 출시 전 큐레이션 과정은 필수라고 팀은 강조합니다.

Skills 간 의존성은 아직 네이티브로 지원되지 않지만, Skills 이름을 명시적으로 참조하는 방식으로 우회할 수 있습니다. Skills의 사용 현황은 PreToolUse 훅을 활용한 로깅으로 파악할 수 있으며, Anthropic은 이를 통해 어떤 Skills가 인기 있는지, 또는 예상보다 덜 호출되는지를 추적합니다.

원문에는 Skill Creator 툴 소개, Skills 설정 예제 코드, 헬퍼 스크립트 예제, description 필드 작성 예시 등 실행에 필요한 구체적인 코드와 스크린샷도 담겨 있습니다.

참고자료:

• Skill Creator 소개 블로그 – Anthropic
• Claude Code Skills 공식 문서