반복하는 업무 절차를 한 번 정리해 두면 AI가 알아서 꺼내 쓰기를 기대합니다. 발표 자료를 만드는 순서, 보고서 양식, 검토할 항목 같은 것들입니다. 그래서 절차를 파일로 묶어 Claude에게 쥐여 주는데, 막상 “덱 만들어 줘”라고 해도 그 절차가 열리지 않는 일이 생깁니다. 저도 그랬습니다. 공들여 만든 절차일수록 안 불리면 더 답답합니다.
Claude에서는 이런 절차 묶음을 스킬(Agent Skills)이라고 부릅니다. 지시문, 스크립트, 참고 자료를 폴더 하나에 담아 두면 Claude가 요청에 맞을 때 꺼내 쓰는 방식입니다. 스킬은 Claude Code, Claude API, claude.ai에서 쓸 수 있습니다.
이 글은 Claude의 Agent Skills 개요 문서와 Skill 작성 모범 사례 문서(2026년 10월 4일 기준)를 바탕으로 정리했습니다. 스킬이 언제 어떻게 읽히는지 보면, 왜 안 불리는지와 무엇부터 고쳐야 하는지가 드러납니다.
스킬은 한 번에 읽히지 않고 세 번에 나누어 읽힙니다
스킬은 처음부터 통째로 Claude의 컨텍스트(대화가 기억하는 범위)에 들어가지 않습니다. 필요한 만큼씩 단계적으로 읽히고, 이 방식을 점진적 공개(progressive disclosure)라고 부릅니다.
첫 단계는 이름과 설명입니다. Claude는 시작할 때 설치된 모든 스킬의 이름과 설명을 읽어 둡니다. 스킬 하나에 약 100토큰(토큰은 AI가 글을 세는 단위로, 한두 문장 분량)이라 스킬을 여러 개 설치해도 부담이 작습니다. 둘째 단계는 스킬 본문입니다. 요청이 설명과 맞을 때에야 본문 파일(SKILL.md)을 읽고, 문서 표에는 이 단계가 5천 토큰 미만으로 적혀 있습니다. 셋째 단계는 딸린 파일과 스크립트입니다. 참고 파일은 본문이 가리킬 때만 읽고, 스크립트는 코드를 읽지 않고 실행해 결과만 받습니다.
이 구조 덕분에 스킬 안에 긴 자료를 넣어도 쓰지 않는 동안에는 자리를 차지하지 않습니다. 반대로 말하면 Claude가 스킬을 고르는 순간 손에 쥔 정보는 이름과 설명뿐입니다. 본문을 아무리 잘 써도 첫 단계를 통과하지 못하면 읽히지 않습니다.
Claude는 설명 한 줄을 요청과 맞대 보고 스킬을 고릅니다
스킬을 쓸지 정할 때 Claude가 요청과 맞대 보는 대상은 설명(description)입니다. 그래서 문서는 설명에 스킬이 무엇을 하는지와 언제 써야 하는지를 둘 다 적으라고 합니다. 모범 사례 문서는 Claude가 100개가 넘는 스킬 가운데 하나를 고를 때도 설명을 쓴다고 밝힙니다. 설명은 최대 1,024자입니다. 설명은 Claude가 늘 먼저 읽는 기본 지시(시스템 프롬프트)에 그대로 끼워지므로, 말하는 주체가 섞이지 않게 “제가 도와드릴게요” 같은 1인칭이 아니라 “PDF를 처리합니다” 같은 3인칭으로 씁니다.
나쁜 예는 “문서를 도와줍니다”처럼 무엇을 하는지만 흐릿하게 적은 설명입니다. 요청에 어떤 말이 나올 때 열려야 하는지가 없어서, 비슷한 스킬이 여럿이면 고를 단서가 없습니다. 좋은 예는 “PDF에서 글자와 표를 뽑고 양식을 채웁니다. PDF, 양식, 문서 추출을 말할 때 씁니다”처럼 하는 일과 쓰는 때를 함께 적은 설명입니다. 뒤 문장에 사용자가 실제로 쓸 단어가 들어 있어야 요청과 맞아떨어집니다.
제 기록에서도 자주 불린 스킬은 설명에 요청 문장이 있었습니다
저는 Claude Code 프로젝트에 스킬을 여럿 만들어 두고 일합니다. 2026년 8월 14일부터 23일까지 열흘 동안의 작업 기록을 세어 보니, 만들어 둔 스킬 25개 중 한 번이라도 불린 것은 3개였습니다. 자주 불린 두 개는 각각 8번, 9번 불렸는데, 둘 다 설명에 제가 실제로 쓰는 한국어 요청 문장을 예시로 적어 둔 스킬이었고, 기능 설명만 적어 둔 덱 제작 스킬은 관련 있어 보이는 요청 49번 중 1번, 교육과정 설계 스킬은 70번 중 한 번도 불리지 않았습니다. 다만 이것은 한 사람의 열흘치 기록이고, ‘관련 있어 보이는 요청’은 단어로 골라 센 추정입니다. 요청 예시가 있었다는 것과 자주 불렸다는 것이 함께 나타났을 뿐, 예시 때문에 불렸다고 말할 수는 없습니다. 그 뒤 기능 설명만 있던 스킬들에 요청 문장을 넣었습니다. 덱 제작 스킬이라면 ‘모든 덱 작업의 단일 진입점’이던 설명 뒤에 “덱 만들어줘”, “ppt로 만들어줘”, “장표 추가해줘”처럼 제가 실제로 치는 말을 붙인 식입니다. 넣은 뒤 얼마나 달라졌는지는 아직 재지 못했습니다.
그래서 지금 할 수 있는 말은 문서가 권하는 확인 방법입니다. 모범 사례 문서는 스킬을 쓰기 전에 대표 과제로 평가(이 요청에는 이 결과가 나와야 한다는 시험 사례)를 세 개 이상 만들고, 스킬이 기대한 때에 열리는지 실제 요청으로 지켜보라고 합니다. 만든 것과 불리는 것은 따로 확인해야 하는 일입니다.
스킬은 어디에 두는지와 누가 만들었는지도 정해야 합니다
스킬이 불리도록 설명을 적었다면, 다음으로 챙길 것은 그 스킬이 어디서 불리고 누구의 것이냐입니다. 같은 스킬이라도 쓰는 곳마다 따로 관리해야 합니다. claude.ai, Claude API, Claude Code 사이에서 직접 만든 스킬은 자동으로 옮겨지지 않습니다. Claude Code에서 만든 스킬은 컴퓨터의 폴더에 있고, claude.ai에 올린 스킬은 그 사용자에게만 보이며, API로 올린 스킬은 워크스페이스(같은 API 계정을 쓰는 팀 공간) 전체가 함께 씁니다.
실행 환경도 다릅니다. API에서 스킬을 쓰려면 코드 실행 도구가 필요하고, 그 안에서는 인터넷에 접속할 수 없으며 새 패키지를 설치할 수도 없습니다. 외부 자료를 불러오는 스킬이라면 API에서는 그대로 돌지 않습니다.
마지막은 출처입니다. 스킬은 지시문과 코드로 Claude에게 일을 시키므로, 악의적인 스킬은 겉으로 밝힌 목적과 다른 도구 호출이나 코드 실행을 지시할 수 있습니다. 문서는 직접 만들었거나 Anthropic이 낸 스킬만 쓰고, 출처를 모르는 스킬은 딸린 파일까지 모두 검토하라고 경고합니다. 스킬을 들이는 일은 프로그램을 설치하는 일과 같은 무게로 다뤄야 합니다.
본문보다 설명 한 줄을 먼저 봅니다
스킬이 안 불릴 때 살필 곳은 ‘기능을 잘 만들었나’가 아니라 ‘설명이 불릴 말을 담았나’입니다. Claude가 고르는 순간 보는 것은 이름과 설명뿐이고, 본문은 그 뒤에야 읽힙니다.
만들어 둔 스킬이 있다면 오늘 설명 한 줄을 다시 읽어 보시길 권합니다. 무엇을 하는지 뒤에 ‘언제 쓰는지’ 문장이 있는지, 그 문장에 내가 실제로 치는 요청의 단어가 들어 있는지 봅니다. 그다음 평소처럼 요청을 세 번 던져, 작업 화면이나 기록에 그 스킬을 썼다는 표시가 남는지 확인합니다.
이 글은 AI의 도움을 받아 작성했습니다.
참고 자료
이 글의 기능 설명은 2026년 10월 4일 공식 문서 기준입니다.
- Claude Agent Skills 개요: https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/overview
- Claude Skill 작성 모범 사례: https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/best-practices