Claude Skills 설명: 점진적 공개(Progressive Disclosure)의 세 가지 수준

Claude Skill은 물리적으로 하나의 폴더입니다. 호스팅된 서비스도, 바이너리도, 대화 맨 위에 붙여 넣는 텍스트 덩어리도 아닙니다. SKILL.md 파일과 그 작업에 필요한 나머지 모든 것을 담은 디렉터리입니다. Skills에 관한 거의 모든 흥미로운 점은 이 한 가지 결정에서 비롯됩니다. 폴더는 에이전트가 선택적으로 열 수 있는 것이기 때문입니다. 프롬프트는 선택적으로 열 수 없습니다. 프롬프트는 대화 안에 있거나, 아예 없거나 둘 중 하나입니다.

Anthropic의 문서는 이 구성을 새 팀원을 위해 만들 법한 온보딩 가이드처럼 정리된 것이라고 설명하며, 그 비유는 처음 보이는 것보다 더 멀리까지 유효하다. 아무도 업무를 시작하기 전에 온보딩 가이드를 처음부터 끝까지 읽지 않는다. 사람들은 눈앞의 질문에 맞는 페이지를 읽고, 나머지는 필요할 때 여전히 거기에 있을 것이라고 믿는다. 스킬은 같은 전제 위에 세워진다. 즉, 절차의 대부분은 대부분의 시간 동안 디스크에 남아 있을 수 있다는 것이다.

파일 시스템 우선, 기능은 그다음

Claude는 파일 시스템에 접근할 수 있는 가상 머신에서 작동합니다. 이것이 스킬이 구성 항목이 아니라 디렉터리로 존재하기 위한 전제 조건인데, 에이전트가 사람이 사용하는 것과 동일한 작업을 통해 폴더를 나열하고, 파일을 읽고, 다른 파일에 대한 참조를 따라갈 수 있게 해 주기 때문입니다. 그 안에서 스킬은 지침, 메타데이터, 그리고 스크립트나 템플릿 같은 선택적 리소스를 패키징합니다.

그 결과물은 폴더 안의 어떤 단일 파일보다도 큰 하나의 역량입니다. 지침은 작업을 어떻게 수행하는지 알려 줍니다. 번들로 제공되는 스크립트는 산문으로 설명되지 않은 채 그 일부를 수행할 수 있습니다. 참조 문서는 기억하는 대신 조회하게 되는 자료를 담을 수 있습니다. 이 세 가지를 쌓아 둔 더미가 아니라 하나의 시스템으로 만드는 것은 그것들이 보이게 되는 순서이며, 이것이 바로 Anthropic이 점진적 공개(progressive disclosure)라고 부르는 부분입니다. 즉, 컨텍스트를 미리 소비하는 대신 필요할 때 단계적으로 정보를 불러오는 것입니다.

레벨 1: 항상 로드되는 두 개의 필드

모든 스킬은 이름과 설명을 담은 YAML 프런트매터로 시작합니다. Claude는 시작 시 해당 메타데이터를 로드하여 시스템 프롬프트에 포함합니다. 이는 누군가 무언가를 요청하기 전에 스킬에서 존재하는 유일한 부분이며, 스킬이 트리거되기 전까지는 이름과 설명만이 컨텍스트를 차지합니다.

설명은 동시에 세 가지 역할을 하는데, 이들을 분리해 보면 왜 그렇게 많은 스킬이 조용히 무시되는지 알 수 있습니다. 그것은 그 대상이 무엇이라고 불리는지를 말하는 레이블입니다. 그것은 색인 항목, 즉 Claude가 해당 스킬이 관련이 있는지 판단할 때 요청이 대조되는 텍스트입니다. 그리고 그것은 범위에 대한 진술이며, 그래서 Anthropic의 지침은 스킬이 무엇을 하는지와 언제 사용해야 하는지를 모두 말해야 한다고 안내합니다. 첫 번째 역할만 수행하는 설명은 매처에게 대조할 것을 아무것도 주지 않습니다.

같은 스킬의 두 가지 버전을 살펴보자. 하나는 PDF 양식을 작성하고 검증하는 것으로 설명되며, 요청이 PDF 양식 작성 또는 확인을 포함할 때 사용하도록 되어 있다. 다른 하나는 문서 작업을 돕는 것으로 설명된다. 첫 번째는 행동과 상황을 명시하지만, 두 번째는 둘 다 명시하지 않는다. 설명에서 둘 다 명시하지 않는 스킬은 에이전트가 그 작업을 멀리 돌아서 처리하는 동안 디스크에서 읽히지 않은 채 방치될 것이다 — 스킬이 실패해서가 아니라, 애초에 발견되지 않았기 때문이다.

레벨 2: 설명이 일치할 때 읽는 본문

요청이 설명과 일치하면 두 번째 레벨이 열립니다: {{1}}SKILL.md{{/1}}의 본문입니다. 이것은 절차, 즉 워크플로, 모범 사례, 지침이며, 이 스킬이 해당 작업에 적합한 도구라고 이미 판단한 에이전트를 위해 작성됩니다. 팀이 모든 대화에서 반복할 단계를 적어 두는 곳이며, 더 깊은 자료로 가는 포인터가 있는 곳입니다.

여기서도 순서는 레벨 1에서만큼이나 중요합니다. 본문은 시작 시 로드되지 않으며, 만일을 대비해 로드되지도 않습니다. 본문은 결정이 내려진 뒤에 도착하므로, 그 결정은 레벨 1만으로 내릴 수 있어야 합니다. 설명이 모호한 스킬은 레벨 2에서 만회할 방법이 없습니다. 레벨 2는 결코 읽히지 않기 때문입니다.

레벨 3: 무언가가 그것들을 가리켰기 때문에 열리는 파일들

세 번째 수준은 폴더의 나머지 부분입니다. 즉, SKILL.md에서 참조되는 추가 파일들입니다. Anthropic의 예시는 양식 작성에 관한 고급 지침을 담은 FORMS.md로, 이는 기본 지침을 짧게 유지하고 작업에 필요할 때만 세부 내용을 사용할 수 있도록 기본 지침과 분리해 둔 것입니다. 스크립트와 템플릿도 이 수준에 속합니다.

구조적 효과는 스킬이 방대한 자료를 한꺼번에 지니지 않고도 담아낼 수 있다는 점입니다. 하나의 폴더에 기본 지침 파일, 상세 참고 자료, 일련의 템플릿과 스크립트가 들어 있을 수 있고, 주어진 작업은 그중 하나만 건드릴 수도 있습니다. 아무것도 가리키지 않는 것은 디스크에 그대로 남아 있고, 에이전트에서 부족한 자원은 디스크가 아니라 컨텍스트입니다.

바로 이 지점에서 이 형식은 프롬프트가 부딪히는 상한을 끌어올립니다. 프롬프트는 붙여넣을 가치가 있을 만큼 짧아야 합니다. 스킬에 함께 제공되는 자료는 디렉터리가 담을 수 있는 양으로 제한됩니다. 작업이 실제로 건드린 부분만 모델에 도달하기 때문입니다.

왜 순서가 세부 사항이 아니라 디자인인가

세 가지 결과가 뒤따르며, 이 셋이 함께 이것이 단순히 아는 것을 넘어 이해할 가치가 있는 이유다.

• 컨텍스트는 예산이며, 항상 로드되는 콘텐츠는 고정 비용입니다. 시스템 프롬프트의 모든 내용은 해당 스킬과 아무 관련이 없는 요청을 포함해 모든 요청마다 비용이 발생합니다. 점진적 공개는 고정 비용을 조건부 비용으로 바꿉니다. 설명은 항상, 지침은 관련이 있을 때, 참조는 참조될 때 제공합니다.

• 설명은 인터페이스입니다. 이는 스킬에서 반드시 보게 되는 유일한 부분이므로, 작성자는 내용뿐 아니라 트리거링도 고려해야 하는 곳입니다.

• 스킬에는 세 가지 유지보수 속도가 있습니다. 메타데이터는 스킬이 다르게 발동해야 할 때 변경되고, 본문은 워크플로가 변경될 때 변경되며, 참조는 기반 자료가 변경될 때 변경됩니다. 이를 분리해 두면 참조 업데이트가 지침의 재작성으로 이어지는 일을 막을 수 있습니다.

비용은 이점의 거울상이다. 모든 레벨 경계는 모델이 올바른 결정을 내려야 하는 지점이다. 설명이 너무 좁으면 해당 스킬은 절대 발동되지 않고 폴더는 쓸모없는 짐이 된다. 너무 넓으면 원래 만들어진 용도가 아닌 작업에서 발동되며, 그 지침은 무관한 작업에 부담이 된다. 점진적 공개는 항상 존재하는 긴 프롬프트가 결코 할 수 없는 방식으로 설명에 결정적인 역할을 부여한다.

Anthropic이 이미 제공하는 것, 그리고 여러분 자신의 기술은 어디에서 비롯되는지

Anthropic은 PowerPoint, Excel, Word, PDF용 사전 구축된 Skills를 제공합니다. 즉, 프레젠테이션, 스프레드시트, 문서, 서식 지정된 PDF 출력을 위한 것입니다. 이는 claude.ai, Claude API, AWS의 Claude Platform, Microsoft Foundry에서 사용할 수 있지만, Foundry에서는 Hosted on Anthropic 배포가 필요하다는 유의 사항이 있습니다.

그것들은 메커니즘을 읽어서 아는 것보다 가장 빠르게 확인하는 방법입니다. 로딩 순서는 직접 작성한 모든 것과 동일합니다. 미리 제작된 스킬과 사용자 지정 스킬의 차이는 폴더를 누가 작성했는지이지, 모델에 도달하는 방식이 아닙니다.

{{1}}Claude Code{{/1}}에서 사용자 지정 스킬을 만들거나, {{2}}Claude API{{/2}}를 통해 업로드하거나, {{3}}claude.ai 설정{{/3}}에서 추가할 수 있습니다. Anthropic이 제시한 이 기능의 이점은 재사용 가능한 모든 것에서 기대할 수 있는 것과 같습니다. 즉, 도메인 작업에 맞게 Claude를 특화하고, 안내를 반복하는 대신 한 번만 작성하며, 여러 단계의 작업을 위해 여러 스킬을 조합하는 것입니다. 그중 마지막 이점은 아키텍처에서 가장 직접적으로 따라옵니다. 각 스킬이 필요할 때 열리는 폴더라면, 작업이 실제로 그 스킬들을 필요로 하기 전까지 여러 스킬을 쌓아 두는 비용은 매우 적기 때문입니다.

스킬은 프롬프트가 아니며, 커넥터도 아닙니다

대화에서는 세 가지가 뒤섞이지만, 로딩 순서 덕분에 그 차이를 쉽게 구분할 수 있다.

프롬프트는 대화 수준의 것입니다. 첫 턴부터 존재하고, 그 대화의 모든 것에 영향을 주며, 대화와 함께 사라집니다. 스킬은 필요할 때만 쓰입니다. 대화가 시작되기 전부터 존재하고, 대부분은 대화에 전혀 들어오지 않으며, 들어오는 부분은 설명이 일치했기 때문에 들어옵니다. 이것이 에이전트에게 어떻게 행동할지 알려주는 것과 에이전트가 집어 들 수 있는 무언가를 주는 것의 차이입니다.

커넥터는 도달 범위에 관한 것입니다. 커넥터는 앱 접근 권한이며, 이는 에이전트가 무엇을 다룰 수 있는지를 결정한다는 뜻입니다. 스킬은 에이전트가 무언가를 다룰 수 있게 된 후 그것을 어떻게 해야 하는지를 결정합니다. 한 팀이 뛰어난 커넥터를 갖추고도 일관성 없는 문서를 만들어낼 수 있는데, 접근 권한은 절차가 아니기 때문입니다. 또한 뛰어난 스킬을 갖추고도 데이터를 보지 못할 수 있는데, 절차는 접근 권한이 아니기 때문입니다.

Anthropic의 문서는 Skills와 Model Context Protocol을 서로 다른 계층으로 다루며, 3단계 메커니즘은 그 분리가 왜 깔끔한지를 보여준다. 로딩 순서는 정보가 언제 도착하는지에 관한 것이지, 어디서 왔는지에 관한 것이 아니다.

기부가 어디에 해당하는지, 한 문단으로.

2026년 10월 22일, Anthropic은 Agent Skills 표준을 Linux Foundation 산하의 Agentic AI Foundation에 기증했습니다. 여기에는 이름, 로고, GitHub 조직, agentskills.io 도메인이 포함되며, Anthropic, Google, OpenAI 및 다른 회사들의 엔지니어들이 개인 자격으로 이를 유지 관리합니다. 그중 어느 것도 위의 메커니즘을 바꾸지 않습니다. 폴더 형식, YAML frontmatter, 로딩 순서, 미리 구축된 문서 스킬은 바로 전날과 정확히 동일합니다. 바뀐 것은 그 이름의 소유자가 누구인지이며, 이는 표준의 장기적 안정성에는 매우 중요하지만 오늘 오후에 스킬을 작성하는 방식에는 전혀 중요하지 않습니다.

설치하기 전에 스킬 읽기

세 가지 수준이 아키텍처라면, 그것들은 짧은 검토 체크리스트도 만들어 준다. 설명을 먼저 읽어라. 설명이 다른 모든 일이 실제로 일어날지 여부를 결정하기 때문이다. 설명은 해당 스킬이 무엇을 하는지와 언제 사용해야 하는지를, 요청에서 실제로 쓸 법한 표현으로 밝혀야 한다. SKILL.md를 두 번째로 읽어라. 그것은 에이전트가 따를 절차이며, 여러분이 일어나길 바라는 일에 대한 요약이 아니라 유능한 동료에게 주는 지침처럼 읽혀야 한다. 세 번째로 그것이 참조하는 내용을 읽어라. 그다음 스크립트를 읽어라.

마지막 항목은 과도한 의심이 아니다. 이 형식은 스킬이 선택적 리소스와 함께 지침을 담을 수 있게 하며, 리소스에는 실행 가능한 코드가 포함될 수 있다. 따라서 설치한 스킬은 대화를 형성하는 텍스트일 뿐만 아니라, 유능한 에이전트가 파일을 열고 그에 따라 행동하는 폴더이기도 하다. 단계별 모델은 어디를 봐야 할지 정확히 알려 주며, 이는 대부분의 설치된 항목이 제공하는 것보다 더 많은 정보를 준다.

우리 페이지에서 오신 독자분들을 위해 한 가지 경계를 분명히 해두고자 합니다. OrcaRouter는 모델 호출을 라우팅하며, 저희는 Anthropic의 앱이나 스킬 표면을 호스팅하지 않습니다. 스킬은 에이전트의 파일 시스템이 있는 곳에서 실행되며, 그것은 저희 계층이 아닙니다. 저희가 하는 일은 모델 선택 그 아래에 있습니다. 하나의 OpenAI 호환 키 뒤에 200개 이상의 모델, 제공업체 정가를 마크업 없이 그대로 전달, 그리고 한 제공업체를 사용할 수 없을 때 제공업체 간 자동 페일오버입니다. 스킬은 작업이 어떻게 수행되어야 하는지를 결정합니다. 라우터는 어떤 모델이 그것을 수행할지를 결정하며, 어느 계층도 서로에 대해 많이 알 필요는 없습니다.

점진적 공개는 자신이 해결하는 제약에 대해 솔직하다. 맥락은 유한하고, 절차는 길며, 주어진 절차의 대부분은 눈앞의 작업과 무관하다. 이름, 본문, 파일 집합은 복잡한 설계가 아니다. 그것은 에이전트가 필요한 부분만 보유하면서 방대한 지식을 운반할 수 있게 하는 가장 작은 설계다.

그렇기 때문에 잘 만들어진 스킬에서 가장 중대한 줄은 동시에 가장 짧은 줄이기도 합니다. 폴더 안의 나머지 모든 것은 하나의 도서관입니다. 설명은 카드 목록이고, 그 목록이 틀렸다면 도서관은 없는 것이나 마찬가지입니다.