2026.06.05 / 동준상.넥스트플랫폼
(AWS SAA, AWS AIF, GCP GenAI Leader)
How Anthropic Engineers Used SKILLS.md to Develop Claude Code
AnthropicのエンジニアがClaudeCodeの開発で「SKILLS.md」を活用した方法
기술 블로그 원문 | Lessons from building Claude Code: How we use skills
https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills
이번 포스트에서는 Anthropic 엔지니어들이 수백 개의 스킬(Skills)을 구축하고 확장하며 얻은 통찰과 교훈을 소개합니다. 특히 Claude Code의 핵심 확장 포인트인 ‘스킬’의 정의부터 분류, 최적화 방법 및 관리 체계까지 상세히 알아봅니다.
1. 핵심 정리 (Executive Summary)
Claude Code에서 **스킬(Skills)**은 에이전트가 작업을 더 정확하고 효율적으로 수행할 수 있도록 돕는 지침, 스크립트 및 리소스의 집합체입니다. 단순한 텍스트 파일을 넘어, 에이전트가 탐색하고 조작할 수 있는 폴더 구조의 실체입니다.
핵심 요약:
- 유연성과 확장성: 기술은 만들기 쉽고 배포가 용이하여 Claude Code의 가장 많이 사용되는 확장 지점입니다.
- 분류체계 확립: 내부 분석 결과, 효과적인 기술은 라이브러리 참조부터 인프라 운영까지 9가지 카테고리로 명확히 구분됩니다.
- 최적화 전략: ‘당연한 소리’를 피하고, 실제 실패 사례를 기반으로 한 ‘주의사항(Gotchas)’ 섹션을 구축하며, 단계적 정보 공개(Progressive Disclosure)를 활용하는 것이 중요합니다.
- 운영 체계: 저장소 내 직접 관리 방식에서 시작하여, 규모가 커짐에 따라 플러그인 마켓플레이스 형태의 유기적 관리 모델로 진화해야 합니다.
2. 스킬(Skills)의 정의와 구조
스킬은 에이전트가 발견하고 사용할 수 있는 명령어, 스크립트 및 리소스가 포함된 폴더입니다.
- 오해의 교정: 스킬은 단순한 마크다운(.md) 파일이 아닙니다. 스크립트, 자산(Assets), 데이터 등을 포함할 수 있는 폴더 구조입니다.
- 기능적 특징: 동적 훅(Dynamic hooks) 등록을 포함한 광범위한 구성 옵션을 제공하며, 에이전트는 이 폴더 내의 파일들을 직접 탐색하고 조작할 수 있습니다.
- 학습 자원: 스킬의 기초는 Anthropic의 ‘Introduction to agent skills’ 교육 과정을 통해 습득할 수 있습니다.
3. 스킬의 9가지 주요 카테고리
Anthropic은 내부에서 사용되는 수백 개의 스킬을 분석하여 다음과 같은 9가지 범주로 분류했습니다.
| 카테고리 | 설명 | 주요 예시 |
| 1. 라이브러리 및 API 참조 | 내부/외부 라이브러리, CLI, SDK의 올바른 사용법 설명 | billing-lib, internal-platform-cli |
| 2. 제품 검증 | 코드 작동 여부 테스트 및 확인 방법 기술 | signup-flow-driver, checkout-verifier |
| 3. 데이터 호출 및 분석 | 데이터 및 모니터링 스택 연결 지침 | funnel-query, grafana, datadog |
| 4. 비즈니스 프로세스 자동화 | 반복적인 워크플로우를 단일 명령으로 자동화 | standup-post, weekly-recap |
| 5. 코드 스캐폴딩 및 템플릿 | 특정 기능을 위한 프레임워크 보일러플레이트 생성 | new-framework-workflow, create-app |
| 6. 코드 품질 및 리뷰 | 조직 내 코드 품질 강제 및 리뷰 지원 | adversarial-review, code-style |
| 7. CI/CD 및 배포 | 코드 가져오기, 푸시 및 배포 지원 | babysit-pr, deploy-service |
| 8. 런북(Runbooks) | 증상 기반 조사 수행 및 구조화된 보고서 생성 | service-debugging, oncall-runner |
| 9. 인프라 운영 | 일상적인 유지보수 및 운영 절차 수행 | resource-orphans, cost-investigation |
4. 효과적인 스킬 구축을 위한 베스트 프랙티스
4.1. 정보의 가치 극대화
- 당연한 내용 배제: Claude는 이미 코딩 능력이 있으며 코드베이스를 읽을 수 있습니다. 모델의 기본 사고방식을 뛰어넘는 특수한 정보(예: 특정 디자인 미학 등)에 집중해야 합니다.
- 주의사항(Gotchas) 섹션 구축: 가장 신호가 높은 콘텐츠입니다. Claude가 해당 스킬을 사용할 때 자주 겪는 실패 지점을 지속적으로 업데이트하여 기록하십시오.
4.2. 컨텍스트 엔지니어링
- 파일 시스템 및 단계적 공개:
SKILL.md파일에서 상황에 맞는 다른 파일(예:references/api.md)을 참조하도록 설계하십시오. 에이전트가 필요할 때만 상세 정보를 읽게 하여 컨텍스트 효율성을 높입니다. - 강제적인 경로 유도(Railroading) 방지: 너무 구체적인 지침으로 모델의 유연성을 제한하지 마십시오. 필요한 정보를 제공하되 상황에 적응할 여지를 주어야 합니다.
4.3. 설정 및 상호작용
- 구성 기반 설정:
config.json파일을 사용하여 설정 정보를 저장하고, 설정이 없는 경우AskUserQuestion도구를 통해 사용자에게 구조화된 질문을 던지도록 설계하십시오. - 모델 중심의 설명: 기술의 설명(Description) 필드는 인간을 위한 요약이 아니라, Claude가 해당 기술을 트리거할지 결정하는 기준이 됩니다. “babysit”과 같은 트리거 키워드를 포함하십시오.
4.4. 고급 기능 활용
- 기억(Memory) 기능: 기술 폴더 내에
.log파일이나 JSON, SQLite 등을 활용해 과거 실행 내역을 저장하면 에이전트가 이전 작업 맥락을 반영할 수 있습니다. (예:CLAUDE_PLUGIN_DATA환경 변수 활용) - 스크립트 제공: 보일러플레이트를 재구성하는 대신, 이미 완성된 스크립트 라이브러리를 제공하여 에이전트가 이를 조합(Composition)하는 데 집중하게 하십시오.
- 온디맨드 훅(On-demand Hooks): 특정 기술이 호출될 때만 활성화되는 훅을 사용하십시오. 예를 들어 위험한 명령(rm -rf 등)을 차단하는
careful훅이나 특정 디렉토리 외 수정을 제한하는freeze훅이 있습니다.
5. 배포 및 관리 체계
배포 방식
- 저장소 체크인: 소규모 팀의 경우
./.claude/skills경로에 기술을 직접 포함시켜 관리합니다. - 플러그인 마켓플레이스: 규모가 커지면 플러그인 형태로 배포하여 사용자가 필요한 기술만 선택적으로 설치하고 설정 흐름을 포함할 수 있게 합니다.
관리 및 측정
- 유기적 성장: 중앙 집중식 결정보다는 샌드박스 폴더에서 실험적으로 사용된 후, 효용성이 입증된 기술을 마켓플레이스로 이동(PR)시키는 방식을 권장합니다.
- 사용량 측정:
PreToolUse훅을 사용하여 사내 기술 사용 로그를 기록하고, 인기가 높거나 트리거가 제대로 되지 않는 기술을 파악하여 개선합니다.
6. 결론
스킬 구축의 베스트 프랙티스는 지금도 진화하고 있습니다. 대부분의 훌륭한 스킬은 몇 줄의 지침과 단 하나의 ‘주의사항’에서 시작되었습니다. Anthropic의 사례는 Claude가 새로운 에지 케이스에 부딪힐 때마다 이를 스킬에 추가하며 점진적으로 개선하는 과정이 가장 효과적임을 시사합니다.
FAQ on the SKILLS.md
앤스로픽(Anthropic) 엔지니어들이 클로드 코드(Claude Code)를 개발하며 활용한 ‘스킬(Skills)’에 대한 핵심 질문 5가지
Q1. 클로드 코드에서 ‘스킬(Skills)’이란 정확히 무엇인가요?
스킬은 에이전트가 작업을 더 정확하고 효율적으로 수행하기 위해 발견하고 사용할 수 있는 지침, 스크립트, 자산 및 데이터가 포함된 폴더입니다. 흔히 마크다운 파일 하나라고 생각하기 쉽지만, 실제로는 스크립트, 데이터, 동적 후크(hooks) 등 에이전트가 탐색하고 조작할 수 있는 다양한 리소스가 담긴 구조화된 디렉터리 형태를 띱니다.
Q2. 앤스로픽 내부에서는 스킬을 어떤 용도로 분류하여 사용하나요?
앤스로픽은 내부 스킬을 조사하여 9가지 주요 카테고리로 분류했습니다.
- 라이브러리/API 참조: 내부 라이브러리나 SDK 사용법 설명.
- 제품 검증: 코드 작동 여부 테스트 및 확인(가장 큰 품질 향상 효과).
- 데이터 분석: 모니터링 스택 및 데이터 소스 연결.
- 업무 자동화: 반복적인 워크플로(스탠드업 작성 등) 자동화.
- 코드 스캐폴딩: 프레임워크 보일러플레이트 생성.
- 코드 품질/리뷰: 코드 스타일 및 품질 강제.
- CI/CD 및 배포: 코드 푸시 및 배포 지원.
- 런북(Runbooks): 증상에 따른 조사 및 보고서 작성.
- 인프라 운영: 일상적인 유지보수 및 운영 절차 수행.
Q3. 효과적인 스킬 작성을 위한 가장 중요한 팁은 무엇인가요?
가장 높은 가치를 제공하는 콘텐츠는 ‘주의 사항(Gotchas)’ 섹션을 구축하는 것입니다. 클로드가 스킬을 사용할 때 자주 겪는 실패 지점을 기록하고 이를 지속적으로 업데이트하는 것이 좋습니다. 또한, 클로드가 이미 알고 있는 뻔한 코딩 지식을 나열하기보다는, 클로드의 기본 사고방식을 보완하거나 특정 조직만의 독특한 규칙을 알려주는 데 집중해야 합니다.
Q4. 스킬의 성능을 극대화하기 위한 구조적 전략이 있나요?
파일 시스템을 활용한 ‘점진적 공개(Progressive Disclosure)’ 전략을 권장합니다. 모든 정보를 하나의 파일에 넣지 않고, 상황에 따라 에이전트가 읽을 수 있도록 여러 파일(예: api.md, templates/)로 나누어 구성하는 방식입니다. 또한, 복잡한 로직은 직접 작성하게 하기보다 스크립트 형태로 제공하여 클로드가 이를 조합해 실행하게 하는 것이 훨씬 강력합니다.
Q5. 팀 내에서 스킬을 어떻게 공유하고 관리하는 것이 좋은가요?
규모가 작은 팀은 리포지토리 내의 ./.claude/skills 폴더에 직접 체크인하여 공유하는 것이 간편합니다. 하지만 규모가 커지면 내부 플러그인 마켓플레이스를 구축하여 사용자가 필요한 스킬만 선택해 설치할 수 있도록 하는 것이 컨텍스트 관리에 유리합니다. 앤스로픽은 중앙 집중식 결정 대신, 유용한 스킬이 유기적으로 마켓플레이스에 등록되도록 권장하며 PreToolUse 후크를 통해 실제 사용량을 측정합니다.
참고자료 및 다운로드
- 구글시트 | Claude Code 엔지니어들이 사용한 SKILL 및 활용 사례 (동준상.넥스트플랫폼 / 260604)
https://docs.google.com/spreadsheets/d/1-c3dJHFddK3p2Hy5ty26qQgmsJ9wPo5bOY32glY75ek/edit?usp=sharing - 다운로드 | Anthropic Skill Scaling Playbook (PDF)
https://drive.google.com/file/d/1pcflFl3LtHlnjNdN4h8mPUQXf18vJcW9/view?usp=sharing
