업데이트: Agent Skills를 크로스 플랫폼 이식성을 위한 개방형 표준으로 공개했습니다. (2025년 12월 18일)
모델의 역량이 발전하면서, 이제 본격적인 컴퓨팅 환경과 상호작용하는 범용 에이전트를 구축할 수 있게 되었습니다. 예를 들어 Claude Code는 로컬 코드 실행과 파일 시스템을 활용해 다양한 도메인에 걸친 복잡한 작업을 수행합니다. 하지만 이러한 에이전트가 강력해질수록, 도메인별 전문 지식을 더 조합 가능하고, 확장 가능하며, 이식 가능한 방식으로 에이전트에 부여할 필요가 있습니다.
이러한 필요에서 Agent Skills가 탄생했습니다. 스킬은 에이전트가 특정 작업을 더 잘 수행할 수 있도록 지침, 스크립트, 리소스를 체계적으로 정리한 폴더로, 에이전트가 필요에 따라 자동으로 탐색하고 불러올 수 있습니다. 스킬은 여러분의 전문 지식을 Claude가 활용할 수 있는 조합 가능한 리소스로 패키징하여, 범용 에이전트를 필요에 맞는 전문 에이전트로 전환해 줍니다.
에이전트를 위한 스킬을 만드는 것은 신입 사원을 위한 온보딩 가이드를 작성하는 것과 비슷합니다. 각 유스케이스마다 분절된 맞춤형 에이전트를 구축하는 대신, 이제 누구나 자신의 절차적 지식을 담아 조합 가능한 역량으로 에이전트를 전문화할 수 있습니다. 이 글에서는 스킬이 무엇인지 설명하고, 작동 원리를 보여주며, 직접 스킬을 만들 때의 모범 사례를 공유합니다.
스킬의 구조
스킬이 실제로 어떻게 작동하는지 알아보기 위해, 실제 사례를 살펴보겠습니다. Claude에 최근 추가된 문서 편집 기능을 구동하는 스킬 중 하나입니다. Claude는 PDF를 이해하는 데는 이미 뛰어나지만, PDF를 직접 조작하는 능력(예: 양식 작성)은 제한적입니다. 이 PDF 스킬을 통해 Claude에게 이러한 새로운 능력을 부여할 수 있습니다.
가장 기본적인 형태의 스킬은 SKILL.md file을 포함하는 디렉터리입니다. 이 파일은 필수 메타데이터인 name와 description를 담은 YAML 프론트매터로 시작해야 합니다. 에이전트는 시작 시 설치된 모든 스킬의 name와 description를 시스템 프롬프트에 미리 로드합니다.
이 메타데이터가 점진적 공개(Progressive Disclosure)의 첫 번째 수준입니다. 스킬 전체를 컨텍스트에 로드하지 않고도, Claude가 각 스킬을 언제 사용해야 하는지 판단할 수 있을 만큼의 정보만 제공합니다. 파일 본문은 두 번째 수준의 세부 정보에 해당합니다. Claude가 해당 스킬이 현재 작업과 관련이 있다고 판단하면, SKILL.md 전체를 컨텍스트에 읽어 들여 스킬을 로드합니다.
스킬이 복잡해지면 하나의 SKILL.md에 모든 컨텍스트를 담기 어렵거나, 특정 시나리오에서만 필요한 컨텍스트가 생길 수 있습니다. 이 경우 스킬 디렉터리 안에 추가 파일을 번들링하고, SKILL.md에서 파일명으로 참조할 수 있습니다. 이렇게 연결된 추가 파일이 세 번째 수준(및 그 이후)의 세부 정보이며, Claude는 필요할 때만 이를 탐색하고 확인합니다.
아래에 표시된 PDF 스킬에서 SKILL.md는 스킬 작성자가 핵심 SKILL.md와 함께 번들링한 두 개의 추가 파일(reference.md과 forms.md)을 참조합니다. 양식 작성 지침을 별도 파일(forms.md)로 분리함으로써, 스킬의 핵심 내용을 간결하게 유지하면서 Claude가 양식을 작성할 때만 forms.md를 읽도록 할 수 있습니다.
점진적 공개는 Agent Skills를 유연하고 확장 가능하게 만드는 핵심 설계 원칙입니다. 목차로 시작해 특정 챕터로, 그리고 상세한 부록으로 이어지는 잘 구성된 매뉴얼처럼, 스킬은 Claude가 필요한 정보만 단계적으로 로드할 수 있게 해줍니다:
파일 시스템과 코드 실행 도구를 갖춘 에이전트는 특정 작업 수행 시 스킬 전체를 컨텍스트 윈도우에 읽어 들일 필요가 없습니다. 덕분에 스킬에 담을 수 있는 컨텍스트의 양에는 사실상 제한이 없습니다.
스킬과 컨텍스트 윈도우
다음 다이어그램은 사용자의 메시지에 의해 스킬이 트리거될 때 컨텍스트 윈도우가 어떻게 변화하는지 보여줍니다.
작동 순서는 다음과 같습니다:
- 처음에 컨텍스트 윈도우에는 핵심 시스템 프롬프트와 설치된 각 스킬의 메타데이터, 그리고 사용자의 초기 메시지가 포함됩니다.
- Claude가 Bash 도구를 호출하여
pdf/SKILL.md의 내용을 읽어 PDF 스킬을 트리거합니다. - Claude가 스킬에 번들링된
forms.md파일을 읽기로 결정합니다. - 마지막으로, PDF 스킬에서 관련 지침을 로드한 뒤 사용자의 작업을 수행합니다.
스킬과 코드 실행
스킬에는 Claude가 판단에 따라 도구로 실행할 수 있는 코드도 포함할 수 있습니다.
대규모 언어 모델은 많은 작업에 뛰어나지만, 특정 연산은 전통적인 코드 실행이 훨씬 적합합니다. 예를 들어, 토큰 생성으로 리스트를 정렬하는 것보다 정렬 알고리즘을 실행하는 것이 훨씬 효율적입니다. 효율성 외에도, 코드만이 제공할 수 있는 결정론적 안정성이 필요한 애플리케이션도 많습니다.
이 예시에서 PDF 스킬에는 PDF를 읽고 모든 양식 필드를 추출하는 Python 스크립트가 미리 작성되어 있습니다. Claude는 스크립트나 PDF를 컨텍스트에 로드하지 않고도 이 스크립트를 실행할 수 있습니다. 또한 코드는 결정론적이므로, 이 워크플로는 일관되고 반복 가능합니다.
스킬 개발 및 평가
스킬을 작성하고 테스트할 때 참고할 만한 가이드라인을 소개합니다:
- 평가부터 시작하세요: 대표적인 작업에서 에이전트를 실행하고, 어디서 어려움을 겪거나 추가 컨텍스트가 필요한지 관찰하여 역량의 구체적인 빈틈을 파악하세요. 그런 다음 이러한 부족한 부분을 해결하기 위해 스킬을 점진적으로 구축합니다.
- 확장을 고려해 구조화하세요:
SKILL.md파일이 다루기 어려울 정도로 커지면, 내용을 별도 파일로 분리하고 참조하세요. 상호 배타적이거나 함께 사용되는 경우가 드문 컨텍스트는 경로를 분리하면 토큰 사용량을 줄일 수 있습니다. 마지막으로, 코드는 실행 가능한 도구이자 문서로서의 역할을 동시에 할 수 있습니다. Claude가 스크립트를 직접 실행해야 하는지, 아니면 참고 자료로 컨텍스트에 읽어 들여야 하는지 명확히 구분해야 합니다. - Claude의 관점에서 생각하세요: Claude가 실제 시나리오에서 스킬을 어떻게 활용하는지 모니터링하고, 관찰 결과를 바탕으로 반복 개선하세요. 예상치 못한 경로로 진행되거나 특정 컨텍스트에 과도하게 의존하는 경우를 주시하세요. 특히 스킬의
name와description에 각별히 신경 쓰세요. Claude는 현재 작업에 대해 스킬을 트리거할지 결정할 때 이 정보를 참고합니다. - Claude와 함께 반복 개선하세요: Claude와 작업하면서, 성공적인 접근 방식과 자주 발생하는 실수를 스킬 내 재사용 가능한 컨텍스트와 코드로 정리하도록 Claude에게 요청하세요. 스킬을 활용한 작업 중 Claude가 잘못된 방향으로 진행하면, 무엇이 잘못되었는지 자체 성찰하도록 요청하세요. 이 과정을 통해 미리 예측하려 하지 않아도 Claude에게 실제로 필요한 컨텍스트가 무엇인지 자연스럽게 파악할 수 있습니다.
스킬 사용 시 보안 고려 사항
스킬은 지침과 코드를 통해 Claude에게 새로운 역량을 제공합니다. 이것이 스킬의 강점이지만, 동시에 악의적인 스킬이 사용 환경에 취약점을 만들거나, Claude가 데이터를 유출하거나 의도하지 않은 행동을 하도록 유도할 수 있다는 의미이기도 합니다.
신뢰할 수 있는 출처의 스킬만 설치할 것을 권장합니다. 신뢰도가 낮은 출처의 스킬을 설치할 때는 사용 전에 철저히 감사하세요. 먼저 스킬에 번들링된 파일의 내용을 읽어 어떤 동작을 하는지 파악하고, 특히 코드 의존성과 이미지나 스크립트 같은 번들 리소스에 주의를 기울이세요. 마찬가지로, 스킬 내에서 Claude가 신뢰할 수 없는 외부 네트워크 소스에 연결하도록 지시하는 내용이나 코드가 있는지도 확인하세요.
스킬의 미래
Agent Skills는 현재 Claude.ai, Claude Code, Claude Agent SDK, Claude Developer Platform에서 지원됩니다.
앞으로 몇 주 안에 스킬의 생성, 편집, 탐색, 공유, 사용에 이르는 전체 라이프사이클을 지원하는 기능을 계속 추가할 예정입니다. 특히 조직과 개인이 자신만의 컨텍스트와 워크플로를 Claude와 공유할 수 있게 해주는 스킬의 가능성에 주목하고 있습니다. 또한 스킬이 Model Context Protocol(MCP) 서버와 어떻게 상호보완하여, 외부 도구 및 소프트웨어를 활용하는 더 복잡한 워크플로를 에이전트에게 학습시킬 수 있는지도 탐구할 것입니다.
더 나아가, 에이전트가 직접 스킬을 생성하고, 편집하고, 평가할 수 있도록 하여, 자신만의 행동 패턴을 재사용 가능한 역량으로 체계화할 수 있게 만들고자 합니다.
스킬은 단순한 개념이며, 그에 걸맞게 포맷도 간결합니다. 이 단순함 덕분에 조직, 개발자, 최종 사용자 모두 맞춤형 에이전트를 쉽게 구축하고 새로운 역량을 부여할 수 있습니다.
스킬로 어떤 것들이 만들어질지 기대됩니다. Skills 문서와 쿡북을 확인하고 지금 바로 시작해 보세요.
감사의 글
이 글은 폴더를 무척 좋아하는 Barry Zhang, Keith Lazuka, Mahesh Murag가 작성했습니다. Skills를 지지하고 지원하며 함께 만들어 준 Anthropic의 많은 동료들에게 감사드립니다.
