Skill의 올바른 사용법: Anthropic이 내부 방법론을 공개한 후 5가지 성찰
저자: AI 제품 전문가 아잉
Anthropic 팀이 작성한 블로그 글 <클로드 코드 개발 과정에서 얻은 교훈: 우리가 Skill을 사용하는 방식>을 읽었습니다. 지금까지 제가 접한 Skill 관련 실무 정리 자료 중 가장 심층적인 글이라고 생각합니다.
Skill이라는 개념 자체는 복잡하지 않지만, 실제로 Skill을 제대로 구현하려면 결코 쉽지 않습니다.
Skill이 처음 주목받기 시작했을 때, 사람들은 다양한 문체 Skill이나 작문 Skill 등을 만드는 데 열광했습니다. 마치 자신의 글쓰기 스타일만 모델에 입력하면, 모델이 그 스타일을 안정적으로 재현해 낼 수 있을 것처럼 여겼습니다.
그러나 저 스스로 여러 번 시도해 본 결과, 이런 접근법은 대부분 실패한다는 것을 알게 되었습니다.
문체 Skill 하나에 수천 자에서 수만 자에 이르는 내용을 담아 넣는 경우가 많기 때문입니다. Skill이 로드되면 컨텍스트 공간의 상당 부분이 차지되어 버리고, 컨텍스트가 너무 무거워지면 오히려 모델의 사고 능력이 약화됩니다.
결국 자주 발생하는 현상은 다음과 같습니다: 문체는 비록 잘 학습되었지만, 내용의 깊이는 얕아지고 분석 능력도 떨어집니다.
또 다른 흔한 사례도 있습니다.
많은 사람들이 Skill을 작성할 때 단계별 작업 지침을 빡빡하게 채워 넣는 경향이 있습니다. 예를 들어 ‘첫 번째 단계는 이것을 하고, 두 번째 단계는 저것을 하고, 세 번째 단계는 또 이것을 하라’는 식입니다. 그런데 실제로 실행해 보면 모델의 수행 결과가 불안정하기 일쑤입니다.
나중에야 저는 점차 깨달았습니다. 이런 반복적인 작업은 긴 Instructions보다는 오히려 Script 형태로 정형화하는 것이 훨씬 적합하다는 사실을 말입니다.
Anthropic의 이 글을 읽고 난 후, 제가 가장 크게 느낀 점은 바로 많은 사람들이 실제로 Skill을 사용하고 있긴 하지만, 그것이 무엇인지 진정으로 이해하고 있는지는 의문이라는 점입니다.
Skill의 본질은 바로 Context Engineering입니다. 어떤 지식은 Skill에 포함시키는 것이 적절하고, 어떤 것은 References로 분리해야 하며, 어떤 것은 Script로 작성해야 하며, 또 어떤 경우에는 Gotchas를 통해 모델의 행동을 제약해야 하는지—이 모든 결정에는 풍부한 실무 경험과 노하우가 담겨 있습니다.
Skill의 작동 원리를 제대로 이해한 후, 우수한 Skill들을 다시 살펴보면, 그것들이 해결하려는 것이 단순히 프롬프트의 문제라기보다는, 컨텍스트 관리, 경험 축적 및 역량 재사용이라는 더 근본적인 문제임을 알 수 있습니다.
만약 여러분이 Skill을 심도 있게 연구하고 싶으시다면, 다음 두 편의 글을 특히 강력히 추천합니다:
https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills
#01 불필요한 말은 하지 마세요
Skill은 본질적으로 조직 내 ‘묵시적 지식’을 축적하는 작업입니다. 따라서 Skill에는 이미 모델이 알고 있는 상식을 반복해서 기재할 필요가 없습니다. 진정으로 가치 있는 정보란, 모델이 전혀 모르는 그런 내용입니다.
Anthropic 내부에서는 항상 강조합니다. Skill에 진짜 써야 할 내용은 바로 ‘Gotchas’, 즉 자주 실수하는 함정들이라는 점을 말입니다.
예를 들면 다음과 같습니다:
1. 이 테이블은 created_at 기준으로 정렬해서는 안 됩니다.
2. staging 환경에서 200 응답을 받았다고 해서 반드시 성공한 것은 아닙니다.
3. request_id와 trace_id는 동일한 값입니다.
이런 정보들은 보통 구성원들의 실무 경험 속에 존재합니다. 그러므로 Skill의 본질이 무엇인지 꼭 기억하세요.
Skill = 숙련된 베테랑의 경험을 문서화하는 것.
Skill을 통해, 원래 서로 다른 사람들의 머릿속에 흩어져 있던 경험을 체계적으로 축적하는 것입니다.
#02 Skill은 사실상 Context Engineering입니다
이것은 Anthropic가 제시한 가장 심오한 통찰 중 하나일 수 있습니다.
Skill은 단순한 Markdown 파일이 아니라, 하나의 폴더입니다. Skill을 실제로 사용해 본 사람들에게는 이 말이 뻔한 진실처럼 들릴 수도 있습니다.
그러나 저는 최근 며칠간 이 말을 반복해서 곱씹으며 서서히 깨닫게 되었습니다. 그들이 폴더라는 형식을 의도적으로 선택한 이유는 바로 Context Engineering의 철학을 표현하기 위해서라는 사실을 말입니다.
다시 한 번 전형적인 Skill 구조를 살펴보겠습니다:
skill/ ├── SKILL.md ├── references/ : 상세 설명, API 참조, 경계 조건 등 저장 ├── scripts/ : 실행 가능한 스크립트 저장 ├── examples/ : 실제 활용 사례 저장 ├── assets/ : 템플릿, 이미지, 고정 자료 등 저장
어떤 Skill을 호출할 때, 모델은 우선 SKILL.md 파일을 읽습니다. 만약 모든 정보를 이 파일에 몰아넣는다면, 순식간에 컨텍스트가 폭발해 버립니다.
예를 들어, 이 Skill이 결제 장애 진단용이라면, Stripe 오류 코드 설명, 과거 장애 사례, 진단 스크립트, 최종 보고서 템플릿 등이 모두 포함될 수 있습니다.
만약 이 모든 내용을 SKILL.md에 집어넣는다면, 매번 Skill을 호출할 때마다 클로드는 전부 다시 읽어야 합니다.
사용자가 단지 특정 오류 코드의 의미를 확인하거나, 특정 결제 상태가 갱신되지 않은 이유를 확인하려는 경우조차, 전혀 필요하지 않은 방대한 정보가 모두 컨텍스트에 포함되어 버립니다.
반면 Anthropic의 접근 방식은 완전히 다릅니다.
SKILL.md는 단순한 안내 페이지와 같습니다. 이 파일의 임무는 모델에게 ‘Stripe 오류가 발생했을 때는 references 폴더에서 해당 설명을 찾아라’고 알려주는 것입니다.
과거 사례를 참고해야 할 때는 examples 폴더에서 유사한 문제를 검색하고, 실제 진단 작업을 수행해야 할 때는 scripts 폴더 내 스크립트를 실행하며, 최종 진단 보고서를 생성할 때는 assets 폴더의 템플릿을 활용합니다.
즉, 전체 과정은 점진적으로 필요한 정보를 노출시키는 방식입니다.
아래 그림은 꼭 저장해 두시길 강력히 권장합니다.
#03 가능한 한 스크립트를 활용하세요
모델의 제한된 컨텍스트 용량과 추론 능력을 반복적인 작업에 낭비하지 마세요. 그런 일은 스크립트에 맡기세요.
예를 들어, 많은 사람들이 Skill을 작성할 때 이렇게 씁니다:
1. 회원 가입 데이터 조회; 2. 결제 데이터 조회; 3. 전환율 계산; 4. 이상 원인 분석.
이 방식은 물론 가능합니다. 모델도 이를 수행할 수 있습니다. 그러나 매번 실행할 때마다, 분석 프로세스 전체를 처음부터 다시 거쳐야 합니다.
데이터 조회, 데이터 정리, 다양한 경계 조건 처리 등은 사실 반복적인 작업입니다.
이러한 기능은 이미 수차례 검증된 바 있습니다. 굳이 매번 모델이 새롭게 발명할 필요가 있을까요? 구체적인 스크립트를 직접 제공하는 편이 훨씬 낫습니다.
게다가 스크립트 방식을 쓰면 Skill의 실행 정확도도 높아지고, 토큰 사용량도 줄어듭니다.
이 관점에서 보면, Skill 내 Scripts는 조직의 역량을 축적하는 도구입니다. 각 스크립트 뒤에는 팀이 수없이 많은 함정을 밟고 나서야 도달한 최선의 실행 방법(Best Practice)이 녹아 있습니다.
이러한 역량을 고정화함으로써, 클로드는 매번 이 경험 위에서 작업할 수 있게 되고, 매번 처음부터 시작할 필요가 없어집니다.
그래서 저는 점점 더 명확하게 느끼게 됩니다. Skill 내 Instructions와 Scripts는 서로 다른 차원의 문제를 해결한다는 사실을 말입니다.
Instructions는 경험과 판단을 제공하고, Scripts는 역량과 실행을 제공합니다.
예를 들어, 결제 장애 진단 Skill에 다음과 같은 문장이 있을 수 있습니다:
‘Stripe가 200 응답을 반환한다고 해서 결제가 성공했다고 바로 간주하지 마세요. payment_events 테이블을 추가로 확인해야 합니다.’
이것은 Instructions입니다. 왜냐하면 이것은 경험에 기반한 판단이기 때문입니다. 반면 check_payment_events()는 Script입니다. 왜냐하면 이것은 실행 능력이기 때문입니다.
Script만 있다면, 모델은 어떻게 조회해야 하는지는 알지만, 왜 조회해야 하는지는 모를 수 있습니다.
Instructions만 있다면, 모델은 조회해야 한다는 사실은 알지만, 매번 새로 구현해야 합니다. 두 가지는 반드시 함께 있어야 합니다.
#04 Description은 사실상 라우팅 규칙과 같습니다
많은 사람들이 Skill Description을 작성하는 방식 자체가 원천적으로 잘못되어 있습니다.
왜냐하면 사람들은 보통 기능 소개 형식으로 작성하는 데 quen, 예를 들어: ‘PR 관리 Skill은 PR 상태 모니터링, CI 문제 처리, 자동 병합 완료 등을 지원합니다.’라고 씁니다.
문제는, 모델이 Skill을 찾을 때 기능 설명을 기준으로 하지 않는다는 점입니다. 클로드 코드가 시작되면, 먼저 모든 Skill의 이름과 Description을 스캔한 후, 사용자의 현재 질문에 따라 어느 Skill을 로드해야 할지를 판단합니다.
따라서 Description에서 가장 중요한 정보는 ‘이 Skill이 무엇을 할 수 있는가’가 아니라, ‘어떤 상황에서 이 Skill을 로드해야 하는가’입니다.
즉, Description은 Skill 전체의 라우팅을 담당하는 역할을 합니다.
실제 세상에서는 누군가 “PR 관리 도구를 실행해 주세요”라고 말하지 않습니다. 대신 “이 PR 좀 지켜봐 주세요”, “CI 또 망쳤어요” 같은 식으로 말합니다.
따라서 좋은 Description은 기능을 나열하기보다는, 사용자의 의도를 최대한 정확하게 묘사해야 합니다.
저는 심지어 아주 간단한 검토 방법을 제안하고 싶습니다.
Description을 작성한 후, Skill 전체를 삭제하고 오직 이 한 줄의 Description만 남깁니다. 그리고 스스로 물어보세요: ‘모델이 사용자의 질문을 보고 이 Skill을 언제 로드해야 할지 알 수 있을까?’
그렇지 않다면, 아마도 계속 수정해야 할 것입니다.
#05 Skill의 관리 및 배포
마지막으로 Skill의 관리 문제에 대해 언급하겠습니다.
개인 단위에서 Skill을 사용할 때는 사실 매우 간단합니다. 자신만을 위해 몇 개의 Skill을 만들고, 스스로 유지·업그레이드하면 됩니다. 그러나 대부분의 팀은 결국 동일한 문제에 직면하게 될 것입니다.
Skill의 수가 몇 개에서 수십 개, 심지어 수백 개로 늘어날 때, 이 Skill들을 어떻게 관리하고, 어떻게 업그레이드하며, 어떻게 팀원들에게 배포해야 할까요?
이 분야에서 Anthropic이 쌓은 경험은 매우 참고 가치가 있다고 생각합니다.
팀 규모가 작을 때는 Skill을 직접 코드 저장소와 함께 관리하면 됩니다. 프로젝트 내 .claude/skills 디렉토리에 두면, 팀원 모두 동일한 Skill 세트와 작업 방식을 공유할 수 있습니다.
그러나 Skill 수가 점차 많아지면서 새로운 문제가 나타납니다.
클로드 코드가 시작될 때, 모든 Skill의 이름과 Description을 스캔하여 현재 작업에 맞는 Skill을 판단합니다. Skill 수가 많아질수록 라우팅 비용도 증가합니다.
이 때문에 Anthropic은 나중에 Marketplace를 도입하게 되었습니다. 그런데 더욱 흥미로운 건, 그들이 Marketplace를 관리하는 방식입니다.
많은 기업이 이런 문제에 직면하면, 보통 첫 번째 반응은 승인 프로세스를 도입하는 것입니다. 즉, 누군가 Skill을 만들면 먼저 신청서를 제출하고, 심사를 거친 후에야 공식 Skill 저장소에 등록되도록 하는 방식입니다. 우리 내부에서도 이 방식을 시도해 본 적이 있지만, 절차가 너무 중대하고, 관리를 위한 관리에 불과했습니다.
그러나 Anthropic의 조직 운영 방식은 훨씬 가볍고 유연합니다.
새로운 Skill은 먼저 소규모로 퍼뜨리고, 동료들이 직접 설치하고 시험해 보도록 합니다.
점점 더 많은 사람이 사용하기 시작한다면, 이 Skill이 실제로 어떤 실질적인 문제를 해결하고 있다는 뜻입니다. 그런 단계가 되면, 작성자가 정식 Marketplace에 제출하면 됩니다.
즉, 먼저 ‘이 Skill이 가치가 있는가’를 토론하기보다는, 먼저 실제 사용 환경에서 검증을 받게 하고, 사용자가 많아지면 자연스럽게 공식 체계로 편입되는 방식입니다. 이렇게 남아 있는 Skill들은 거의 대부분 팀이 진정으로 필요로 하는 것들입니다.
TechFlow 공식 커뮤니티에 오신 것을 환영합니다
Telegram 구독 그룹:https://t.me/TechFlowDaily
트위터 공식 계정:https://x.com/TechFlowPost
트위터 영어 계정:https://x.com/BlockFlow_News
