앤트로픽 공식 강의 'Introduction to agent skills' 한국어 튜토리얼 공개

Claude Code를 팀에 도입한 조직에서 자주 보는 장면이 있습니다. 한 팀원은 PR(Pull Request) 리뷰를 요청하면 팀 컨벤션에 맞는 결과가 바로 나옵니다. 옆자리 팀원은 Claude Code라는 같은 도구를 쓰면서도 매번 원하는 형식을 처음부터 설명합니다. 두 사람의 차이는 실력이 아닙니다. 도구를 한 번 '가르쳐 둔' 사람과 매번 '다시 설명하는' 사람의 차이입니다.

스킬(Skills)은 이 반복을 없애는 Claude Code의 기능입니다.¹ 자주 반복하는 지시를 SKILL.md 파일로 한 번 저장해 두면 Claude가 관련 요청을 인식할 때마다 자동으로 적용합니다. 문제는 배울 자료입니다. 검색하면 나오는 스킬 강의 상당수가 블로그 요약이나 영상 정리입니다. 그렇기 때문에 단편적인 지식은 얻어도 팀에 적용할 체계까지 얻기는 어렵습니다.

모던웹연구소가 앤트로픽 공식 강의 'Introduction to agent skills'²를 한국어 튜토리얼로 옮겨 공개했습니다. 번역에서 멈추지 않았습니다. 원본 강의 공개 이후 Claude Code에 추가된 규칙 파일(rules) 기능처럼 원본이 다루지 못한 내용을 보강해 함께 다룹니다. 이 글에서는 튜토리얼의 구성과 함께, 일반 스킬 강의 대신 공식 커리큘럼으로 배울 때 조직이 무엇을 얻는지 정리합니다.

여섯 챕터, 두 시간이 걸리지 않는 공식 커리큘럼

튜토리얼은 여섯 챕터로 구성됩니다. 챕터당 예상 학습 시간은 15~20분, 전체를 합쳐도 두 시간이 걸리지 않습니다. 1~2챕터는 누구나 볼 수 있고 3~6챕터는 모던웹연구소 고객 전용입니다.

각 챕터에는 원본 강의 영상이 그대로 들어 있고, 영상을 보지 않아도 따라갈 수 있도록 한국어 핵심 요약이 함께 붙습니다. 카페 단골 주문, 회의록 템플릿처럼 개발자가 아닌 구성원도 스킬에 대한 개념을 잡을 수 있도록 눈높이 예시를 달아 두었습니다. 시리즈 페이지에는 '스킬과 CLAUDE.md는 어떻게 다른가', '스킬이 트리거되지 않을 때는 어떻게 하나' 같은 여덟 가지 질문을 FAQ로 정리해 두었습니다.

기업 관점에서 공식 커리큘럼이 다른 점

스킬을 다루는 콘텐츠는 이미 많습니다. 하지만 상당수는 개인 생산성 관점에서 끝납니다. SKILL.md를 만들고, 트리거를 확인하고, 내 작업 속도를 올리는 데까지입니다. 팀 도입을 검토하는 조직이 정작 궁금해하는 질문에는 답하지 않습니다. 누가 어떤 스킬을 만들어야 하고, 이름이 충돌하면 어느 쪽이 이기고, 조직 전체에는 어떻게 배포하고 통제하는가 하는 질문입니다.

엑셀을 잘 다루는 직원이 있다고 회사 보고서 서식이 통일되지는 않죠. 개인이 도구를 잘 쓰는 것과 조직이 해당 도구를 표준으로 쓰는 것은 다른 문제입니다. 앤트로픽 공식 커리큘럼의 가치는 이 '조직' 축을 처음부터 설계에 포함했다는 점입니다. 조직 관점에서 눈여겨볼 지점은 다섯 가지입니다.

• 우선순위 체계(2챕터): 이름이 같은 스킬이 여러 위치에 있으면 Enterprise → Personal → Project → Plugins 순서로 우선순위가 정해집니다. 조직 표준이 개인 설정보다 앞서도록 설계된 계층입니다.

• 세 가지 배포 경로(5챕터): 저장소에 커밋해 팀과 공유하는 방법부터 플러그인·마켓플레이스 배포, 엔터프라이즈 관리 설정(managed settings)을 통한 조직 전체 배포까지 규모별로 다룹니다.

• 도구 접근 제한(3챕터): allowed-tools로 스킬이 활성화됐을 때 Claude가 쓸 수 있는 도구를 제한합니다. 읽기 전용 작업이나 보안이 민감한 워크플로에 필요한 통제 장치입니다.

• 컨텍스트 비용 관리(3챕터): 점진적 공개(progressive disclosure)로 SKILL.md를 가볍게 유지하고 상세 자료는 필요할 때만 읽게 합니다. 토큰 비용과 응답 품질에 직결되는 운영 지식입니다.

• 트러블슈팅 체계(6챕터): 트리거가 안 되는 경우부터 로드 실패, 우선순위 충돌, 런타임 오류까지 진단 순서를 제공합니다. 스킬 검증기(skills validator)와 claude --debug 사용법도 함께 다룹니다.

Claude Code 도입을 검토하고 있고 팀 공식 스킬을 만들고 있다면 이 다섯 가지가 곧 점검 목록입니다. 지금 참고하는 강의가 우선순위와 배포·통제를 다루는지 확인해 보세요. 다루지 않는다면 그 자료는 개인 생산성 강의이지 팀 도입 가이드는 아닙니다.

모던웹연구소가 보강한 것

공식 강의에도 공백이 있습니다. 촬영 이후 Claude Code에 추가된 기능은 다루지 못한다는 점입니다. 대표적인 것이 규칙 파일(rules)입니다(공식 문서). CLAUDE.md를 여러 파일로 나눠 관리하는 기능인데, paths 프론트매터를 지정하면 해당 경로의 파일을 다룰 때만 규칙 파일에 있는 지침이 로드됩니다. '필요할 때만 로드된다'는 성질 때문에 스킬과 헷갈리기 쉽습니다.

그래서 4챕터에 두 기능의 비교를 보강했습니다. 판단 기준은 트리거입니다. 스킬은 사용자의 '요청'을 보고 매칭되고, 경로 지정 규칙 파일은 Claude가 다루는 '파일'을 보고 매칭됩니다. "PR 설명 써줘"라는 요청에 반응해야 한다면 스킬이 맞습니다. src/api/ 아래 파일을 수정할 때마다 검증 규칙이 따라붙어야 한다면 규칙 파일이 맞습니다.

하위 디렉터리 CLAUDE.md의 로드 시점도 추가했습니다. 작업 디렉터리와 그 위 계층의 CLAUDE.md는 세션 시작 시 로드되지만, 하위 디렉터리의 CLAUDE.md는 Claude가 그 디렉터리의 파일을 읽을 때에야 로드됩니다. 특정 모듈에만 해당하는 지침을 분리하면 경로 지정 규칙 파일과 비슷한 컨텍스트 절약 효과를 얻는다는 뜻입니다. 모노레포에서 루트 CLAUDE.md와 규칙 파일, 하위 디렉터리 CLAUDE.md가 각각 언제 로드되는지는 다이어그램 한 장으로 정리했습니다. 5챕터에는 플러그인으로 스킬을 배포할 때의 디렉터리 구조 도표를 더했습니다.

보강한 내용은 전부 본문에 '모던웹연구소 추가 팁'으로 표시해 원본과 구분했습니다. 어디까지가 앤트로픽의 공식 커리큘럼이고 어디부터가 모던웹연구소의 보강인지 독자가 구분할 수 있어야 두 정보를 모두 신뢰할 수 있기 때문입니다.

어디서 시작하면 되나

1챕터 '스킬이란 무엇인가'와 2챕터 '첫 스킬 만들기'는 지금 바로 볼 수 있습니다. 스킬을 처음 접한다면 1챕터의 예시부터, 개념을 이미 안다면 2챕터에서 SKILL.md를 직접 만들어 보세요.

Claude Code를 팀에 배포하고 통제하는 3~6챕터는 모던웹연구소와 컨설팅·교육을 진행한 고객에게 열려 있습니다. 팀 상황에 맞는 스킬 설계와 거버넌스가 필요하다면 컨설팅 안내를 참고하세요. 프리미엄 챕터가 대중에 공개될 때의 소식은 뉴스레터로 가장 먼저 전합니다.

1. Claude Code 공식 문서, Agent Skills. 스킬의 구조와 설정 옵션을 정리한 1차 출처입니다.

   ↩

2. Anthropic, Introduction to agent skills(Skilljar). 한국어 튜토리얼의 원본 강의입니다.

   ↩