요약: Anthropic이 Agent Skills를 소개합니다. Agent Skills는 에이전트가 동적으로 발견하고 로드할 수 있는 지침, 스크립트, 리소스로 구성된 정리된 폴더입니다. 이를 통해 일반적인 에이전트를 전문화된 에이전트로 변환할 수 있습니다. 점진적 공개(progressive disclosure) 원칙을 통해 필요할 때만 정보를 로드하여 효율성을 높입니다.
업데이트: Agent Skills를 크로스 플랫폼 호환성을 위한 개방형 표준으로 공개했습니다. (2025년 12월 18일)
모델의 기능이 향상됨에 따라 이제 완전한 컴퓨팅 환경과 상호작용하는 범용 에이전트를 구축할 수 있습니다. 예를 들어 Claude Code는 로컬 코드 실행과 파일 시스템을 사용하여 도메인 간 복잡한 작업을 수행할 수 있습니다. 하지만 이러한 에이전트가 더 강력해짐에 따라, 도메인별 전문 지식을 제공하는 방식에서 더 구성 가능하고 확장 가능하며 이식성 있는 방식이 필요합니다.
이것이 우리가 Agent Skills를 만든 이유입니다. Agent Skills는 에이전트가 동적으로 발견하고 로드하여 특정 작업을 더 잘 수행할 수 있는 지침, 스크립트, 리소스로 구성된 정리된 폴더입니다. Skills는 전문 지식을 Claude가 사용할 수 있는 구성 가능한 리소스로 패키징하여 Claude의 기능을 확장하고, 범용 에이전트를 사용자의 요구에 맞는 전문화된 에이전트로 변환합니다.
에이전트를 위한 스킬을 구축하는 것은 신규 직원을 위한 온보딩 가이드를 작성하는 것과 같습니다. 각 사용 사례마다 조각화되고 맞춤 설계된 에이전트를 구축하는 대신, 절차적 지식을 포착하고 공유하여 누구나 구성 가능한 기능으로 에이전트를 전문화할 수 있습니다. 이 기사에서는 Skills가 무엇인지, 어떻게 작동하는지 설명하고 직접 구축하기 위한 모범 사례를 공유합니다.
!스킬을 활성화하려면 에이전트에 대한 사용자 정의 지침으로 SKILL.md 파일을 작성하기만 하면 됩니다.
스킬은 에이전트에게 추가 기능을 제공하는 지침, 스크립트, 리소스의 정리된 폴더를 포함하는 SKILL.md 파일이 있는 디렉토리입니다.
스킬의 구조
실제로 Skills가 작동하는 것을 보려면 실제 예제를 살펴보겠습니다. Claude의 최근 출시된 문서 편집 기능을 가능하게 하는 스킬 중 하나입니다. Claude는 이미 PDF 이해에 대해 많이 알고 있지만 직접 조작하는 능력은 제한적입니다(예: 양식 작성). 이 PDF 스킬을 통해 Claude에게 이러한 새로운 기능을 제공할 수 있습니다.
가장 단순하게는 스킬은 SKILL.md 파일이 포함된 디렉토리입니다. 이 파일은 name과 description이라는 필수 메타데이터가 포함된 YAML 프론트매터로 시작해야 합니다. 시작 시 에이전트는 설치된 모든 스킬의 name과 description을 시스템 프롬프트에 미리 로드합니다.
이 메타데이터는 점진적 공개(progressive disclosure)의 첫 번째 수준입니다. 전체를 컨텍스트에 로드하지 않고도 각 스킬을 사용해야 할 때를 아는 데 필요한 충분한 정보만 제공합니다. 이 파일의 실제 본문은 두 번째 수준의 세부 정보입니다. Claude가 스킬이 현재 작업과 관련이 있다고 생각하면 전체 SKILL.md를 컨텍스트에 읽어들여 스킬을 로드합니다.
!스킬이 취해야 할 특정 작업과 관련된 이름, 설명 및 컨텍스트를 포함하여 SKILL.md 파일의 구조
SKILL.md 파일은 시작 시 시스템 프롬프트에 로드되는 파일 이름과 설명이 포함된 YAML 프론트매터로 시작해야 합니다.
스킬이 복잡해짐에 따라 단일 SKILL.md에 맞지 않을 정도로 많은 컨텍스트가 포함되거나 특정 시나리오에서만 관련된 컨텍스트가 포함될 수 있습니다. 이러한 경우 스킬은 스킬 디렉토리 내에 추가 파일을 번들로 묶고 SKILL.md에서 이름으로 참조할 수 있습니다. 이러한 추가 연결된 파일들은 Claude가 필요할 때만 선택적으로 탐색하고 발견할 수 있는 세 번째 수준(그 이상)의 세부 정보입니다.
아래에 표시된 PDF 스킬에서 SKILL.md는 스킬 작성자가 핵심 SKILL.md와 함께 번들로 묶기로 선택한 두 개의 추가 파일(reference.md와 forms.md)을 참조합니다. 양식 작성 지침을 별도 파일(forms.md)로 이동함으로써, 스킬 작성자는 스킬의 핵심을 깔끔하게 유지할 수 있으며, Claude가 양식을 작성할 때만 forms.md를 읽을 것이라는 신뢰를 가질 수 있습니다.
!SKILL.md 파일에 추가 컨텐츠를 번들로 묶는 방법
스킬에 추가 컨텍스트(추가 파일 통해)를 통합할 수 있으며, 이는 시스템 프롬프트를 기반으로 Claude가 트리거할 수 있습니다.
점진적 공개는 Agent Skills를 유연하고 확장 가능하게 만드는 핵심 설계 원칙입니다. 목차로 시작한 다음 특정 장, 마지막으로 상세한 부록이 있는 잘 정리된 매뉴얼처럼, 스킬은 Claude가 필요할 때만 정보를 로드할 수 있게 합니다.
!이 이미지는 Skills에서 컨텍스트의 점진적 공개가 어떻게 작동하는지 보여줍니다.
파일 시스템과 코드 실행 도구가 있는 에이전트는 특정 작업을 수행할 때 스킬 전체를 컨텍스트 윈도우에 읽어들일 필요가 없습니다. 이것은 스킬에 번들로 묶을 수 있는 컨텍스트의 양이 사실상 무제한이라는 것을 의미합니다.
Skills와 컨텍스트 윈도우
다음 다이어그램은 사용자 메시지로 인해 스킬이 트리거될 때 컨텍스트 윈도우가 어떻게 변하는지 보여줍니다.
!이 이미지는 컨텍스트 윈도우에서 스킬이 트리거되는 방식을 보여줍니다.
스킬은 시스템 프롬프트를 통해 컨텍스트 윈도우에서 트리거됩니다.
표시된 작업 순서:
- 시작하면 컨텍스트 윈도우에 핵심 시스템 프롬프트와 설치된 각 스킬의 메타데이터, 그리고 사용자의 초기 메시지가 있습니다.
- Claude는 Bash 도구를 호출하여
pdf/SKILL.md의 내용을 읽어 PDF 스킬을 트리거합니다. - Claude는 스킬과 함께 번들된
forms.md파일을 읽기로 선택합니다. -
마지막으로, Claude는 PDF 스킬에서 관련 지침을 로드했으므로 사용자의 작업을 진행합니다.
Skills와 코드 실행
스킬은 Claude가 재량에 따라 도구로 실행할 수 있는 코드도 포함할 수 있습니다.
대규모 언어 모델은 많은 작업에 탁월하지만, 특정 작업은 전통적인 코드 실행에 더 적합합니다. 예를 들어, 토큰 생성을 통한 리스트 정렬은 단순히 정렬 알고리즘을 실행하는 것보다 훨씬 비용이 많이 듭니다. 효율성 외에도 많은 응용 프로그램은 코드만 제공할 수 있는 결정론적 신뢰성을 요구합니다.
우리의 예제에서 PDF 스킬은 PDF를 읽고 모든 양식 필드를 추출하는 미리 작성된 Python 스크립트를 포함합니다. Claude는 스크립트나 PDF를 컨텍스트에 로드하지 않고도 이 스크립트를 실행할 수 있습니다. 그리고 코드는 결정론적이기 때문에 이 워크플로우는 일관되고 반복 가능합니다.
!이 이미지는 코드가 Skills를 통해 실행되는 방식을 보여줍니다.
스킬은 Claude가 작업의 성격에 따라 재량에 따라 도구로 실행할 수 있는 코드도 포함할 수 있습니다.
Skills 개발 및 평가
스킬을 작성하고 테스트하기 시작하는 데 도움이 되는 몇 가지 지침:
- 평가부터 시작하세요: 대표적인 작업에서 에이전트를 실행하고 어디서 어려움을 겪는지 또는 추가 컨텍스트가 필요한지 관찰하여 에이전트 기능의 구체적인 격차를 식별합니다. 그런 다음 이러한 단점을 해결하기 위해 스킬을 점진적으로 구축합니다.
- 확장 가능한 구조:
SKILL.md파일이 다루기 힘들게 되면 내용을 별도 파일로 분할하고 참조합니다. 특정 컨텍스트가 상호 배타적이거나 함께 거의 사용되지 않는 경우 경로를 분리하면 토큰 사용량이 줄어듭니다. 마지막으로 코드는 실행 가능한 도구와 문서로 모두 사용될 수 있습니다. Claude가 스크립트를 직접 실행해야 하는지 또는 참조로 컨텍스트에 읽어들여야 하는지 명확해야 합니다. - Claude의 관점에서 생각하세요: 실제 시나리오에서 Claude가 스킬을 사용하는 방식을 모니터링하고 관찰을 기반으로 반복합니다. 예기치 않은 궤적이나 특정 컨텍스트에 대한 과도한 의존을 주시하세요. 스킬의
name과description에 특별히 주의를 기울이세요. Claude는 현재 작업에 대한 응답으로 스킬을 트리거할지 여부를 결정할 때 이를 사용합니다. - Claude와 반복하세요: Claude와 함께 작업하는 동안, Claude에게 성공적인 접근 방식과 일반적인 실수를 스킬 내의 재사용 가능한 컨텍스트와 코드로 포착하도록 요청하세요. 스킬을 사용하여 작업을 완료할 때 잘못된 방향으로 간다면, 무엇이 잘못되었는지 자성을 요청하세요. 이 과정은 미리 예상하려는 대신 Claude가 실제로 필요로 하는 컨텍스트를 발견하는 데 도움이 됩니다.
Skills 사용 시 보안 고려사항
스킬은 지침과 코드를 통해 Claude에게 새로운 기능을 제공합니다. 이것은 강력하게 만들지만, 악의적인 스킬이 사용되는 환경에 취약점을 도입하거나 Claude가 데이터를 유출하고 의도하지 않은 작업을 수행하도록 지시할 수도 있다는 것을 의미합니다.
신뢰할 수 있는 출처에서만 스킬을 설치하는 것을 권장합니다. 신뢰할 수 없는 출처에서 스킬을 설치할 때는 사용 전에 철저히 감사합니다. 스킬에 번들된 파일의 내용을 읽어 무엇을 하는지 이해하는 것부터 시작하며, 코드 종속성과 이미지나 스크립트 같은 번들 리소스에 특별히 주의를 기울이세요. 마찬가지로 Claude가 잠재적으로 신뢰할 수 없는 외부 네트워크 소스에 연결하도록 지시하는 스킬 내의 지침이나 코드에 주의하세요.
Skills의 미래
Agent Skills는 현재 Claude.ai, Claude Code, Claude Agent SDK, Claude Developer Platform에서 지원됩니다.
향후 몇 주 동안 스킬 생성, 편집, 발견, 공유 및 사용의 전체 수명주기를 지원하는 기능을 계속 추가할 것입니다. 특히 스킬이 조직과 개인이 Claude와 자신의 컨텍스트와 워크플로우를 공유할 수 있는 기회에 대해 기대하고 있습니다. 또한 외부 도구와 소프트웨어가 포함된 더 복잡한 워크플로우를 에이전트에게 가르침으로써 스킬이 Model Context Protocol (MCP) 서버를 보완할 수 있는 방법도 탐색할 것입니다.
더 먼 미래를 내다보면, 에이전트가 스스로 스킬을 생성, 편집 및 평가할 수 있도록 하여 자신의 동작 패턴을 재사용 가능한 기능으로 공식화할 수 있게 하기를 희망합니다.
스킬은 단순한 개념이며 그에 따라 단순한 형식을 가집니다. 이러한 단순성은 조직, 개발자, 최종 사용자가 맞춤형 에이전트를 더 쉽게 구축하고 새로운 기능을 부여할 수 있게 합니다.
사람들이 스킬로 무엇을 구축할지 보게 되어 기쁩니다. Skills 문서와 쿡북을 확인하여 오늘 시작하세요.
감사의 말씀
Barry Zhang, Keith Lazuka, Mahesh Murag가 작성했습니다. 이 세 명은 모두 폴더를 정말 좋아합니다. 스킬을 옹호하고 지원하고 구축한 Anthropic의 다른 많은 분들에게도 특별히 감사드립니다.
핵심 포인트
- Agent Skills는 지침, 스크립트, 리소스로 구성된 폴더로 에이전트의 도메인별 전문 지식을 확장합니다
- 점진적 공(progressive disclosure) 개 원칙을 통해 필요할 때만 정보를 로드하여 효율성을 극대화합니다
- 스킬 개발 시 평가부터 시작하고 Claude와 반복적인 개선 과정을 거치는 것이 중요합니다
출처: Equipping agents for the real world with Agent Skills \ Anthropic
