Agent Skills로 에이전트를 현실 세계에 맞춰 똑똑하게! 🚀

개발자 뉴스레터를 받아보세요

제품 업데이트, 사용 방법, 커뮤니티 소식 등을 매월 받은 편지함으로 보내드려요.

업데이트: Agent Skills를 플랫폼 간 이식성을 위한 개방형 표준으로 공개했어요. (2025년 12월 18일)

모델 성능이 점점 좋아지면서, 이제는 완전한 컴퓨팅 환경과 상호작용하는 범용 에이전트를 만들 수 있게 되었죠. 예를 들어, 클로드 코드(Claude Code)는 로컬 코드 실행과 파일 시스템을 활용해서 여러 분야에 걸쳐 복잡한 작업을 수행할 수 있어요. 하지만 이런 에이전트들이 점점 강력해질수록, 특정 도메인 전문 지식을 에이전트에게 부여할 때 더 조합 가능하고, 확장 가능하며, 이식성 있는 방법이 필요하더라구요.

그래서 저희는 Agent Skills를 만들게 되었어요. Agent Skills는 에이전트가 특정 작업을 더 잘 수행하기 위해 동적으로 찾아서 로드할 수 있는 지침, 스크립트, 리소스가 담긴 잘 정리된 폴더라고 할 수 있죠. 스킬(Skills)은 여러분의 전문 지식을 클로드(Claude)가 활용할 수 있는 조합 가능한 리소스 형태로 패키징해서 클로드의 능력을 확장시켜준답니다. 덕분에 범용 에이전트를 여러분의 필요에 맞는 전문 에이전트로 탈바꿈시킬 수 있어요.

에이전트를 위한 스킬을 만드는 건 마치 신입 직원 온보딩 가이드를 만드는 것과 비슷해요. 각 사용 사례별로 파편화되고 맞춤형으로 설계된 에이전트를 일일이 만들 필요 없이, 이제는 누구든지 자신의 절차적 지식(procedural knowledge)을 캡처하고 공유함으로써 조합 가능한 능력들을 이용해 에이전트를 전문화할 수 있게 된 거죠. 이번 글에서는 스킬이 무엇인지, 어떻게 작동하는지, 그리고 여러분만의 스킬을 만드는 데 도움이 될 모범 사례들을 공유해볼게요.

스킬이 실제로 어떻게 작동하는지 보려면, 실제 예시를 하나 살펴볼까요? 클로드의 최근 출시된 문서 편집 기능에 힘을 실어주는 스킬 중 하나를요. 클로드는 PDF를 이해하는 데는 이미 많은 것을 알고 있지만, PDF를 직접 조작하는 능력(예: 양식 채우기)에는 한계가 있었어요. 이 PDF 스킬 덕분에 클로드에게 이런 새로운 능력을 줄 수 있게 된 거죠.

가장 간단하게 말하면, 스킬은 SKILL.md 파일을 포함하는 디렉토리예요. 이 파일은 name과 description이라는 필수 메타데이터를 포함하는 YAML 프론트매터로 시작해야 해요. 시작할 때, 에이전트는 설치된 모든 스킬의 name과 description을 시스템 프롬프트에 미리 로드한답니다.

이 메타데이터가 바로 **점진적 공개(progressive disclosure)**의 첫 번째 단계예요. 클로드가 모든 스킬을 컨텍스트에 로드하지 않고도, 각 스킬을 언제 사용해야 할지 알기에 충분한 정보만 제공하는 거죠. 이 파일의 실제 본문은 디테일의 두 번째 단계예요. 클로드가 현재 작업과 관련이 있다고 판단하면, 전체 SKILL.md를 읽어서 스킬을 컨텍스트에 로드한답니다.

스킬이 복잡해질수록, 하나의 SKILL.md에 담기에는 너무 많은 컨텍스트를 포함하거나, 특정 시나리오에서만 관련 있는 컨텍스트를 포함할 수도 있어요. 이런 경우, 스킬은 스킬 디렉토리 안에 추가 파일들을 묶어 넣고 SKILL.md에서 이름으로 참조할 수 있어요. 이렇게 연결된 추가 파일들은 세 번째 단계(그리고 그 이상)의 디테일인데, 클로드가 필요할 때만 탐색하고 발견하도록 선택할 수 있죠.

아래에 보이는 PDF 스킬에서는 SKILL.md가 두 개의 추가 파일(reference.md와 forms.md)을 참조하고 있는데, 스킬 작성자가 핵심 SKILL.md와 함께 묶어 넣기로 선택한 파일들이에요. 양식 작성 지침을 별도의 파일(forms.md)로 옮김으로써, 스킬 작성자는 스킬의 핵심 부분을 가볍게 유지하면서 클로드가 양식을 채울 때만 forms.md를 읽을 것이라고 신뢰할 수 있게 되죠.

점진적 공개(progressive disclosure)는 Agent Skills를 유연하고 확장 가능하게 만드는 핵심 설계 원칙이에요. 마치 목차로 시작해서 특정 장, 그리고 마지막에는 상세 부록으로 이어지는 잘 정리된 매뉴얼처럼, 스킬은 클로드가 필요할 때만 정보를 로드할 수 있게 해준답니다.

파일 시스템과 코드 실행 도구를 갖춘 에이전트들은 특정 작업을 수행할 때 스킬의 모든 내용을 컨텍스트 윈도우에 읽어 들일 필요가 없어요. 이건 스킬에 묶일 수 있는 컨텍스트의 양이 사실상 무한하다는 것을 의미하죠.

다음 다이어그램은 사용자의 메시지에 의해 스킬이 트리거될 때 컨텍스트 윈도우가 어떻게 변하는지 보여줘요.

표시된 작업 순서는 다음과 같아요.

pdf/SKILL.md

;forms.md 파일은 스킬에 번들되어 있어요.

스킬은 클로드가 재량에 따라 도구로 실행할 수 있는 코드도 포함할 수 있어요.

대규모 언어 모델(LLM)은 많은 작업에서 뛰어나지만, 특정 연산은 전통적인 코드 실행에 더 적합해요. 예를 들어, 토큰 생성을 통해 목록을 정렬하는 것은 단순히 정렬 알고리즘을 실행하는 것보다 훨씬 비용이 많이 들죠. 효율성 문제 외에도, 많은 애플리케이션은 코드만이 제공할 수 있는 확정적인 신뢰성을 요구해요.

저희 예시에서, PDF 스킬은 PDF를 읽고 모든 양식 필드를 추출하는 미리 작성된 Python 스크립트를 포함하고 있어요. 클로드는 이 스크립트나 PDF를 컨텍스트에 로드하지 않고도 스크립트를 실행할 수 있죠. 그리고 코드는 결정론적이기 때문에, 이 워크플로우는 일관되고 반복 가능하답니다.

스킬을 작성하고 테스트하는 데 도움이 될 몇 가지 유용한 가이드라인이 여기 있어요.

SKILL.md 파일이 다루기 어려워지면, 내용을 별도의 파일로 분리하고 참조하세요. 특정 컨텍스트들이 상호 배타적이거나 거의 함께 사용되지 않는다면, 경로를 분리하면 토큰 사용량을 줄일 수 있을 거예요. 마지막으로, 코드는 실행 가능한 도구이자 문서 역할을 할 수 있어요. 클로드가 스크립트를 직접 실행해야 하는지, 아니면 참조용으로 컨텍스트에 읽어 들여야 하는지 명확해야 한답니다.

스킬의 name과 description을 명확하고 간결하게 작성하세요. 클로드는 현재 작업에 대한 응답으로 스킬을 트리거할지 결정할 때 이것들을 사용할 거예요.

스킬은 지침과 코드를 통해 클로드에게 새로운 능력을 제공해요. 이게 스킬을 강력하게 만들지만, 동시에 악성 스킬은 사용되는 환경에 취약점을 도입하거나, 클로드가 데이터를 유출하고 의도치 않은 행동을 하도록 지시할 수도 있다는 의미도 돼요.

저희는 신뢰할 수 있는 출처에서만 스킬을 설치하도록 권장해요. 덜 신뢰할 수 있는 출처에서 스킬을 설치할 때는 사용하기 전에 철저히 감사(audit)해야 해요. 스킬에 번들된 파일들의 내용을 읽어서 어떤 일을 하는지 이해하는 것부터 시작하세요. 특히 코드 종속성과 이미지나 스크립트 같은 번들된 리소스에 주의를 기울이세요. 마찬가지로, 스킬 내에서 클로드에게 잠재적으로 신뢰할 수 없는 외부 네트워크 소스에 연결하도록 지시하는 지침이나 코드에도 주의를 기울여야 한답니다.

Agent Skills는 현재 Claude.ai, Claude Code, Claude Agent SDK, 그리고 Claude 개발자 플랫폼 전반에서 지원되고 있어요.

앞으로 몇 주 안에, 저희는 스킬 생성, 편집, 발견, 공유, 사용의 전체 수명 주기를 지원하는 기능들을 계속 추가할 예정이에요. 특히 스킬이 조직과 개인이 클로드와 자신의 컨텍스트와 워크플로우를 공유하는 데 도움이 될 기회에 대해 매우 기대하고 있답니다. 또한, 스킬이 외부 도구와 소프트웨어를 포함하는 더 복잡한 워크플로우를 에이전트에게 가르침으로써 Model Context Protocol (MCP) 서버를 어떻게 보완할 수 있을지도 탐색할 거예요.

더 나아가서는, 에이전트가 스스로 스킬을 생성, 편집, 평가할 수 있게 하여, 자신만의 행동 패턴을 재사용 가능한 능력으로 코드화할 수 있도록 돕기를 희망하고 있어요.

스킬은 단순한 개념이고 그에 상응하게 형식도 간단해요. 이런 단순함 덕분에 조직, 개발자, 최종 사용자들이 맞춤형 에이전트를 만들고 새로운 능력을 부여하기가 더 쉬워진답니다.

사람들이 스킬로 무엇을 만들어낼지 정말 기대돼요. 오늘 바로 저희 스킬 문서와 쿡북을 확인하고 시작해보세요!

작성자: Barry Zhang, Keith Lazuka, Mahesh Murag (모두 폴더를 정말 좋아하는 분들이네요). 스킬을 지지하고, 지원하고, 구축하는 데 힘써주신 Anthropic의 다른 많은 분들께 특별히 감사드립니다.

제품 업데이트, 사용 방법, 커뮤니티 소식 등을 매월 받은 편지함으로 보내드려요.