에이전트 스킬 만들기: 폴더 구조부터 테스트·공유까지

스킬이란 무엇이고 왜 필요한가

Anthropic 엔지니어링 글글은 문제를 이렇게 짚는다. 모델이 아무리 똑똑해도 실제 업무에는 '이 회사에서는 이 순서로 한다' 같은 절차 지식과 조직 맥락이 필요하다. 이를 채우려고 만든 것이 스킬(Agent Skills)이다. 스킬은 지시문·스크립트·자료를 정리해 둔 폴더로, 에이전트가 스스로 찾아 필요할 때 불러온다. 같은 글은 스킬 만들기를 신입 사원에게 줄 온보딩 안내서를 엮는 일에 빗댔다.

평소 쓰는 프롬프트와는 쓰임이 다르다. Claude 공식 문서글는 프롬프트를 한 번의 작업에 쓰는 대화 단위 지시로, 스킬을 필요할 때 불러오는 재사용 자원으로 구분한다. 스킬을 만들어 두면 대화마다 같은 안내를 반복해 붙여 넣지 않아도 된다. Anthropic은 PowerPoint·Excel·Word·PDF용 기본 스킬을 제공하고, 직접 만든 스킬은 Claude Code, API, claude.ai 설정에서 쓸 수 있다고 밝혔다글.

스킬은 특정 제품에만 묶인 형식도 아니다. Anthropic은 2025년 12월 Agent Skills를 여러 플랫폼에서 쓸 수 있는 공개 표준으로 내놓았고글, 공개 명세글가 폴더 구조와 필드 규칙을 정한다. Simon Willison의 글글도 스킬을 다른 모델에서 쓰지 못하게 막는 장치는 없다고 짚었다.

스킬 폴더의 구성 요소

Agent Skills 명세글에 따르면 스킬은 최소한 SKILL.md 파일 하나가 든 폴더다. 여기에 실행 코드를 담는 scripts/, 참고 문서를 담는 references/, 템플릿·이미지·데이터 파일 같은 정적 자원을 담는 assets/를 선택적으로 더한다. 셋 다 권장 관례일 뿐, 필요하면 다른 파일이나 폴더도 넣을 수 있다.

SKILL.md는 YAML 프런트매터(파일 맨 위의 설정 블록)로 시작해야 하고, 필수 필드는 name과 description 두 개다글글. 명세글는 선택 필드도 정해 두었다. 라이선스를 적는 license, 필요한 실행 환경을 500자 이내로 적는 compatibility, 임의의 키-값을 담는 metadata, 미리 허용할 도구를 적는 allowed-tools(실험적 기능)다. 명세는 대부분의 스킬에는 compatibility가 필요 없다고 덧붙인다.

프런트매터 아래 본문은 마크다운이며 형식 제한이 없다. 명세글는 단계별 지시, 입력·출력 예시, 자주 생기는 경계 사례를 넣으라고 권한다. scripts/의 코드는 그 자체로 돌아가거나 필요한 라이브러리를 분명히 밝히고, 이해하기 쉬운 오류 메시지를 내야 한다. references/의 파일은 주제 하나에 집중해 작게 유지한다. 에이전트가 이 파일들을 필요할 때마다 읽기 때문이다.

점진적 공개: 세 단계로 나눠 읽기

스킬 설계의 중심은 점진적 공개(progressive disclosure)다. 1단계는 메타데이터다. 에이전트는 시작할 때 설치된 모든 스킬의 이름과 설명을 시스템 프롬프트에 미리 넣어 두고글, 이 분량은 스킬 하나에 약 100토큰이다글글. Simon Willison글은 스킬 하나가 몇십 토큰만 더 차지한다고 표현했다. 2단계는 SKILL.md 본문이다. 사용자 요청이 설명과 맞으면 그때 읽으며, 공식 문서는 5천 토큰 미만을 권한다글글.

3단계는 폴더 안의 참고 파일과 스크립트다. Anthropic 엔지니어링 글글의 PDF 스킬 예시에서 SKILL.md는 reference.md와 forms.md를 이름으로 가리키기만 한다. 양식 작성법을 forms.md로 따로 빼 두었기 때문에 Claude는 양식을 채울 때만 그 파일을 읽는다. 스크립트는 더 가볍다. Claude 공식 문서글에 따르면 스크립트는 bash로 실행되고 코드 자체는 컨텍스트에 들어오지 않으며, 그 출력만 들어온다.

그래서 스킬을 많이 설치해도 실제로 쓰이기 전까지는 이름과 설명만 컨텍스트 윈도를 차지한다글. 엔지니어링 글글은 이 때문에 스킬에 묶을 수 있는 자료의 양이 사실상 제한 없다고 설명한다. 다만 이 방식은 에이전트가 파일 시스템을 읽고 명령을 실행할 수 있는 환경이 있어야 돌아간다글글.

설계 원칙: 이름·설명·분량·자유도

이름부터 정한다. 명세글상 name은 64자 이하이고 소문자·숫자·하이픈만 쓸 수 있다. 하이픈으로 시작하거나 끝나면 안 되고, 하이픈을 연달아 쓸 수 없으며, 폴더 이름과 같아야 한다. Claude 작성 가이드글는 여기에 더해 'anthropic', 'claude' 같은 예약어를 금지한다. 이름은 processing-pdfs처럼 동사-ing 형태를 권하고, helper·utils·data처럼 뭉뚱그린 이름은 피하라고 권한다.

설명(description)은 스킬이 실제로 쓰이느냐를 가른다. 작성 가이드글는 Claude가 100개가 넘을 수도 있는 스킬 가운데 이 설명을 보고 하나를 고른다고 밝혔다. 그래서 무엇을 하는지와 언제 쓰는지를 함께 담고, 사용자가 꺼낼 만한 핵심 단어를 넣으라고 권한다. 설명은 시스템 프롬프트에 그대로 들어가므로 'I can help you…' 같은 1인칭이 아닌 3인칭으로 써야 한다. 명세글는 'Helps with PDFs.'를 나쁜 예로, PDF 텍스트·표 추출과 양식 작성을 적고 '사용자가 PDF나 양식을 언급할 때 사용'까지 밝힌 문장을 좋은 예로 든다.

분량은 짧을수록 좋다. 작성 가이드글는 컨텍스트 윈도를 시스템 프롬프트, 대화 기록, 다른 스킬과 함께 쓰는 공용 자원이라고 부르고, 'Claude는 이미 똑똑하다'를 기본 전제로 삼으라고 한다. PDF가 무엇인지까지 설명한 약 150토큰짜리 예시보다 라이브러리 이름과 코드만 남긴 약 50토큰짜리 예시가 낫다고 본다. 명세글는 SKILL.md를 500줄 아래로 유지하라고 권한다. 자세한 내용은 별도 파일로 옮기고 SKILL.md에서 한 단계만 걸쳐 참조하라고 한다. 엔지니어링 글글은 서로 함께 쓰이지 않는 내용을 다른 파일로 나눠 두면 토큰을 아낄 수 있다고 덧붙인다.

지시를 얼마나 구체적으로 쓸지는 작업이 얼마나 쉽게 틀어지는지에 맞춘다. 작성 가이드글는 자유도를 세 단계로 나눈다. 코드 리뷰처럼 여러 방법이 다 맞을 수 있으면 글로 된 큰 방향만 준다. 선호하는 패턴이 있으면 의사코드나 매개변수가 있는 스크립트를 준다. 데이터베이스 마이그레이션처럼 순서를 꼭 지켜야 하면 '이 명령을 그대로 실행하라'는 수준으로 준다. 같은 문서는 이를 양옆이 낭떠러지인 좁은 다리와 탁 트인 들판에 빗댄다. 스크립트를 넣는 기준도 비슷하다. 엔지니어링 글글은 목록 정렬처럼 토큰을 생성해서 하면 비싼 일, 늘 같은 결과가 나와야 하는 일은 코드가 낫다고 설명한다. 또 Claude가 스크립트를 바로 실행해야 하는지, 참고용으로 읽어야 하는지를 분명히 적으라고 권한다. Simon Willison글도 스크립트는 더 믿을 만하거나 효율적일 때만 더한다고 썼다.

처음 만들 때의 단계

첫째, 평가에서 시작한다. 엔지니어링 글글은 대표적인 작업으로 에이전트를 돌려 보고, 어디서 막히거나 맥락이 더 필요한지 확인한 다음 그 빈틈을 메우는 스킬을 조금씩 만들라고 권한다. 막연히 '있으면 좋을 것 같은' 스킬부터 만들지 않는다.

둘째, name과 description을 먼저 쓴다. 이 두 줄이 스킬이 쓰일지를 정한다. 셋째, 본문에는 모델이 모르는 회사 고유의 절차, 정해진 명령, 자주 하는 실수만 짧게 적는다. 넷째, 본문이 길어지거나 특정 상황에만 필요한 내용이 생기면 references/로 옮긴다. 정해진 대로 실행해야 하는 작업은 scripts/에 넣는다. 다섯째, 명세글가 안내하는 skills-ref validate 명령으로 프런트매터 형식과 이름 규칙을 검사한다.

여섯째, 쓸 모델에서 모두 시험한다. 작성 가이드글는 스킬의 효과가 바탕 모델에 따라 달라진다고 말한다. Haiku에는 안내가 충분한지, Opus에는 설명이 지나치지 않은지 확인하라고 권한다. 일곱째, 실제로 쓰는 모습을 관찰한다. 엔지니어링 글글은 예상과 다른 Trajectory(에이전트가 밟은 작업 경로)나 특정 파일에 지나치게 기대는 모습을 살피라고 한다. 그리고 Claude에게 성공한 방법과 흔한 실수를 스킬에 정리하게 하고, 작업이 빗나가면 무엇이 잘못됐는지 되돌아보게 하라고 권한다. 이렇게 하면 필요한 맥락을 미리 짐작하는 대신 실제로 찾아낼 수 있다.

점검 목록

형식부터 확인한다. SKILL.md가 YAML 프런트매터로 시작하는가? name이 폴더 이름과 같고 소문자·숫자·하이픈만 쓰는가글? description이 비어 있지 않고 1,024자 이하이며, 무엇을 하는지와 언제 쓰는지를 3인칭으로 담았는가글글?

분량과 구조를 확인한다. 본문이 500줄 아래인가글? 모델이 이미 아는 일반 설명을 빼고 '이 문단이 토큰 값을 하는가'를 따져 봤는가글? 참고 파일을 SKILL.md에서 한 단계로, 상대 경로로 가리키는가글? 함께 쓰이지 않는 내용이 다른 파일로 나뉘어 있는가글?

스크립트와 동작을 확인한다. 스크립트마다 실행용인지 참고용인지 적혀 있는가글? 필요한 라이브러리와 오류 메시지가 분명한가글? 실제로 쓸 모델들에서 시험했는가글? 설치 전에 낯선 출처의 스킬이라면 파일 내용, 코드 의존성, 외부 네트워크에 접속하라는 지시가 있는지 살펴봤는가글?

흔한 실수, 보안, MCP·서브에이전트와의 차이

흔한 실수는 몇 가지로 모인다. 설명이 'Helps with documents'처럼 막연해 스킬이 호출되지 않는다글글. 설명을 1인칭이나 2인칭으로 써서 스킬을 찾는 데 혼선이 생긴다글. 모델이 이미 아는 내용을 길게 풀어 써서 토큰을 낭비한다글. 참고 파일이 다른 파일을 다시 가리키는 깊은 사슬을 만든다글. 한 모델에서만 시험한다글.

보안은 따로 챙겨야 한다. 엔지니어링 글글은 악의적인 스킬이 환경에 취약점을 들여오거나, 데이터를 빼내거나, 의도하지 않은 행동을 하도록 Claude를 이끌 수 있다고 경고한다. 그래서 믿을 수 있는 출처의 스킬만 설치하고, 그렇지 않은 스킬은 파일 내용을 꼼꼼히 감사한 뒤 쓰라고 권한다. Simon Willison글은 스킬이 코드를 실행하는 환경에 기대므로 프롬프트 인젝션 같은 공격의 피해를 줄일 샌드박스가 중요하다고 짚었다. 팀에서 스킬을 공유할 때도 이 감사 절차를 공통 규칙으로 두는 편이 안전하다.

MCP와는 하는 일이 다르다. MCP는 외부 도구와 데이터를 연결하는 프로토콜이다. 엔지니어링 글글은 스킬이 외부 도구를 쓰는 복잡한 작업 절차를 가르쳐 MCP 서버를 보완하는 방향을 탐색하겠다고 밝혔다. Simon Willison글은 스킬이 파일 시스템과 명령 실행 환경에 기댄다는 점이 MCP와의 가장 큰 차이라고 봤다. 또 GitHub 공식 MCP 하나가 수만 토큰의 컨텍스트를 차지하는 사례를 들며, 스킬은 필요할 때만 자세한 내용을 읽어 이 부담이 작다고 평가했다. 이는 그의 개인 견해다.

서브에이전트는 이번 입력 자료가 직접 다루지 않으므로 일반적인 구분만 적는다. 서브에이전트는 주 에이전트가 일을 맡기는 별도 에이전트로, 자기 컨텍스트에서 작업한 뒤 결과를 돌려준다. 스킬은 에이전트를 새로 만들지 않고, 지금 일하는 에이전트가 필요할 때 읽는 지식과 도구의 묶음이다. 그래서 '누가 일하느냐'를 나누려면 서브에이전트를, '어떻게 일하느냐'를 가르치려면 스킬을 떠올리면 된다.

더 공부하려면

먼저 Anthropic 엔지니어링 글글을 읽으면 스킬이 왜 나왔는지, 점진적 공개가 어떻게 작동하는지, 만들고 평가하는 요령이 한 번에 정리된다. 다음으로 Claude 공식 개요 문서글의 단계별 로딩 표와 PDF 스킬 로딩 예시를 보면 컨텍스트에 실제로 무엇이 들어가는지 감이 잡힌다.

직접 만들 때는 Claude 스킬 작성 가이드글와 Agent Skills 명세글를 옆에 두고 본다. 작성 가이드는 간결성, 자유도, 이름·설명 쓰기 같은 판단 기준을 준다. 명세는 필드 규칙, 폴더 관례, 검증 도구를 준다. 마지막으로 Simon Willison의 글글은 스킬이 MCP와 어떻게 다른지, 실제 스킬이 어떻게 생겼는지를 개발자 시각에서 보여 준다.