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