에이전트를 만들지 말고 스킬을 만들라 — 앤트로픽 「Agent Skills」 완전 해부: 업무 매뉴얼로 범용 에이전트를 전문가로 만드는 법

들어가며 — 300 IQ 천재에게 세금 신고를 맡기겠습니까

크게 보기

2025년 11월 20일, 뉴욕 미드타운. 코딩 에이전트를 만드는 사람들만 초대받는 행사 AI Engineer Code Summit의 무대에 앤트로픽 엔지니어 두 사람이 올랐다. 배리 장(Barry Zhang)과 마헤시 무라그(Mahesh Murag). 한 해 전 같은 무대에서 "에이전트란 무엇인가"를 정의하던 사람들이다. 이번 발표 제목은 도발적이었다. 「Don't Build Agents, Build Skills Instead」. 에이전트를 만들지 말고, 스킬을 만들라.

발표는 이렇게 시작한다.

"누가 당신의 세금 신고를 해 주기를 바라십니까? IQ 300의 수학 천재 마헤시입니까, 아니면 경험 많은 세무 전문가 배리입니까? 저라면 매번 배리를 고르겠습니다. 마헤시가 2025년 세법을 제1원리에서부터 알아내는 것을 원하지 않습니다. 저에게 필요한 것은 전문가의 일관된 실행입니다. 오늘의 에이전트는 마헤시와 많이 닮았습니다. 뛰어나지만, 전문성이 없습니다."

이 비유가 발표 전체의 뼈대다. 모델은 이미 충분히 똑똑하다. 부족한 것은 지능이 아니라 업무를 해 본 사람만 아는 절차와 맥락이다. 그 절차와 맥락을 어디에 어떻게 담을 것인가. 두 사람의 답은 놀랄 만큼 단순하다. 폴더에 넣으라.

영상은 12월 8일 공개되었고, 이 글을 쓰는 2026년 9월 기준 조회수 150만 회를 넘었다. 16분 22초짜리 발표가 이 정도로 퍼진 것은 내용이 새로워서만이 아니다. 지난 1년 동안 많은 조직이 "업무마다 에이전트를 하나씩 만들자"는 방향으로 달렸고, 그 결과가 어땠는지 다들 몸으로 알게 되었기 때문이다. 에이전트가 다섯 개가 되면 유지보수해야 할 시스템도 다섯 개가 된다. 규정이 바뀌면 다섯 곳을 고쳐야 한다. 업무를 아는 사람은 코드를 못 고치고, 코드를 고치는 사람은 업무를 모른다.

이 특집은 네 가지를 한다. 첫째, 발표 전문과 그 바탕이 된 2025년 10월 엔지니어링 글 「Equipping agents for the real world with Agent Skills」를 처음부터 끝까지 읽고 주장을 하나씩 뜯는다. 둘째, 12월에 오픈 스탠다드로 공개된 사양과 앤트로픽의 저작 가이드를 통해 스킬이 "긴 프롬프트"와 무엇이 다른지 기술적으로 확인한다. 셋째, 출시 직후의 열광("MCP보다 큰 일")과 첫 사용기의 마찰, 그리고 2026년 2월 스킬 3,984개를 스캔한 보안 보고서까지 반론을 짚는다. 넷째, 한국의 보통 조직이 이미 갖고 있는 업무 문서, 예컨대 견적 업무 매뉴얼을 스킬로 바꾸는 절차를 위젯으로 직접 해 본다.

1. 발표자와 계보 — 「효과적인 에이전트 만들기」에서 「에이전트를 만들지 말라」까지

배리 장은 2024년 12월 19일 앤트로픽이 낸 「Building Effective Agents」의 공저자다. 이 글은 이후 1년 동안 에이전트를 만드는 사람들의 교과서 노릇을 했다. 핵심은 두 가지 구분과 한 가지 원칙이었다. 구분은 워크플로(LLM과 도구를 미리 정한 코드 경로로 엮은 것)와 에이전트(LLM이 스스로 절차와 도구 사용을 결정하는 것). 원칙은 "가장 단순한 해법에서 시작하고, 필요할 때만 복잡도를 더하라." 글은 이렇게 끝났다.

"LLM 분야의 성공은 가장 정교한 시스템을 만드는 데 있지 않습니다. 당신의 필요에 맞는 올바른 시스템을 만드는 데 있습니다."

마헤시 무라그는 MCP(Model Context Protocol)를 알리는 발표를 여러 차례 한 사람이다. MCP는 2024년 11월 앤트로픽이 공개한, 에이전트를 외부 도구와 데이터에 연결하는 표준이다. 발표에서 두 사람은 스스로 이렇게 요약한다. "MCP는 에이전트 연결의 표준이 되었고, 우리의 첫 코딩 에이전트 Claude Code가 세상에 나왔고, Claude Agent SDK는 이제 프로덕션용 에이전트를 상자에서 꺼내자마자 제공한다."

이 계보가 중요하다. 「에이전트를 만들지 말라」는 에이전트를 부정하는 발표가 아니다. 에이전트를 1년 동안 만들어 본 사람들이 "이제 뭘 반복해서 만들고 뭘 한 번만 만들어야 하는지 알게 되었다"고 말하는 발표다. 발표 첫 문장이 그 사실을 드러낸다. "지난번 여기 왔을 때 우리는 아직 에이전트가 무엇인지 알아내고 있었습니다. 오늘은 많은 사람이 매일 에이전트를 씁니다. 그런데도 빈틈이 있습니다."

전체 흐름을 한 줄에 놓으면 이렇다. 2024년 11월 MCP, 12월 「효과적인 에이전트 만들기」, 2025년 2월 Claude Code, 9월 Agent SDK, 10월 16일 Agent Skills 공개와 엔지니어링 글, 11월 20일 이 발표, 12월 18일 오픈 스탠다드, 2026년 2월 보안 보고서, 3월 지원 제품 40여 개. 아래 연대기에서 하나씩 눌러 보라.

2. 첫 번째 주장 — 코드가 전부다

발표의 첫 번째 명제는 스킬이 아니라 그 전제에 관한 것이다.

"간단히 말해, 우리는 코드가 우리에게 필요한 전부라고 생각합니다."

이 말의 뜻은 이렇다. 두 사람은 원래 도메인마다 에이전트가 아주 다르게 생길 것이라 믿었다. 재무 에이전트는 재무용 도구와 뼈대가, 법무 에이전트는 법무용 도구와 뼈대가 필요할 것이고, 그러니 도메인마다 별도의 에이전트를 만들어야 한다고. 그런데 Claude Code를 만들고 나서 생각이 바뀌었다.

"Claude Code를 만든 뒤에 우리는 깨달았습니다. Claude Code는 사실 범용 에이전트라는 것을."

코딩 에이전트로 만든 것이 왜 범용인가. 발표는 재무 보고서 생성을 예로 든다. 모델은 API를 호출해 데이터를 끌어오고 조사를 한다. 그 데이터를 파일 시스템에 정리한다. 파이썬으로 분석한다. 그리고 원하는 파일 형식으로 통찰을 합성한다. 전부 코드를 통해서다. 그래서 "핵심 뼈대는 갑자기 bash와 파일 시스템 정도로 얇아질 수 있다. 훌륭하고 아주 확장성이 좋다."

"우리가 깨달은 것은 코드가 단지 하나의 활용 사례가 아니라 디지털 세계에 대한 범용 인터페이스라는 점입니다."

이 명제를 받아들이면 결론이 따라온다. 에이전트 밑바닥, 즉 모델이 토큰을 읽고 쓰는 루프와 파일 시스템·코드 실행이 있는 런타임은 도메인과 무관하게 같다. 그렇다면 도메인마다 새로 만들 것은 밑바닥이 아니다. 밑바닥 위에 올릴 무엇이다. 발표는 그 "무엇"을 곧바로 말하지 않고, 먼저 문제를 하나 더 꺼낸다.

3. 두 번째 주장 — 부족한 것은 지능이 아니라 전문성이다

크게 보기

"우리는 아주 빨리 다른 문제에 부딪혔습니다. 그 문제는 도메인 전문성입니다." 여기서 세무사 비유가 나온다. 그리고 오늘의 에이전트가 가진 결함 세 가지를 짚는다.

셋 다 모델의 지능 문제가 아니다. 모델 바깥의 문제다. 지능은 이미 300 IQ인데, 그 지능이 우리 회사의 2025년 세법을, 우리 팀의 견적 규정을, 우리 고객의 이상한 요구를 모른다. 그래서 두 사람은 "에이전트 스킬"을 만들었다.

엔지니어링 글은 같은 생각을 다른 비유로 말한다.

"에이전트를 위해 스킬을 만드는 것은 신입 직원을 위한 온보딩 가이드를 준비하는 것과 같습니다. 활용 사례마다 조각난 맞춤형 에이전트를 만드는 대신, 이제 누구나 자기 절차적 지식을 포착하고 공유해서 조합 가능한 능력으로 에이전트를 전문화할 수 있습니다."

크게 보기

온보딩 가이드 비유는 정확하다. 좋은 회사는 신입이 오면 뇌를 바꾸지 않는다. 안내서를 준다. 우리 팀은 견적을 이렇게 낸다, 단가표는 여기 있다, 할인은 이 한도 안에서만, 계산은 이 시트를 쓴다, 보내기 전에 이 다섯 가지를 확인한다. 안내서는 사람이 쓴다. 필요할 때 펼친다. 규정이 바뀌면 안내서를 고친다. 신입이 바뀌어도 안내서는 남는다.

이 비유를 사용자가 보내 준 표현으로 바꾸면 이렇게 된다. "견적 업무를 위한 별도 AI 시스템을 매번 새로 설계하기보다, 견적을 만드는 절차·계산 스크립트·서식·검수 기준을 패키지로 제공하자." 이 한 문장에 스킬의 네 구성 요소가 다 들어 있다. 절차(지침), 계산(스크립트), 서식(자산), 검수(검증). 4장에서 이 네 가지가 폴더 안에 어떻게 놓이는지 본다.

4. 스킬의 해부 — 폴더, SKILL.md, 3단계 점진적 공개

발표는 스킬을 한 문장으로 정의한다.

"스킬은 에이전트를 위한 조합 가능한 절차적 지식을 패키지한, 조직된 파일들의 모음입니다. 다른 말로 하면, 폴더입니다. 이 단순함은 의도적입니다. 컴퓨터만 있으면 사람이든 에이전트든 누구나 만들고 쓸 수 있는 것을 원했습니다."

그리고 왜 새 형식을 발명하지 않았는지 설명한다. "이미 가진 것과 함께 동작합니다. Git으로 버전을 관리할 수 있고, 구글 드라이브에 던져 넣을 수 있고, 압축해서 팀에 공유할 수 있습니다. 우리는 수십 년 동안 파일을 원시 요소로 써 왔고 파일을 좋아합니다. 왜 지금 바꿔야 합니까?" 엔지니어링 글의 감사의 말은 세 저자를 "모두 폴더를 정말 좋아하는" 사람들이라고 소개한다.

크게 보기

사양이 요구하는 것은 단 두 줄

2025년 12월 18일 agentskills.io에 공개된 사양을 읽으면 스킬의 최소 요건은 놀랄 만큼 작다. 폴더 하나, 그 안에 SKILL.md 파일 하나. 파일은 YAML 프론트매터로 시작해야 하고, 필수 필드는 name과 description 둘뿐이다.

본문에는 형식 제한이 없다. "에이전트가 과제를 잘 수행하는 데 도움이 되는 것은 무엇이든 쓰라." 권장 절은 단계별 지시, 입출력 예시, 흔한 예외 상황. 그 밖에 관례로 scripts/(실행 코드), references/(참고 문서), assets/(템플릿·데이터)를 둔다.

이것이 "긴 프롬프트"와 다른 첫 번째 지점이다. 프롬프트는 한 덩어리 텍스트다. 스킬은 파일 시스템 위의 구조다. 지시문과 코드와 참고 자료가 서로 다른 파일에 있고, 에이전트가 파일 시스템을 탐색하듯 필요한 것만 연다.

점진적 공개 — 목차, 장, 부록

두 번째 다른 지점이 핵심이다. 발표는 이렇게 말한다.

"이 시점에서 스킬은 많은 정보를 담을 수 있고, 우리는 컨텍스트 창을 보호해서 수백 개의 스킬을 넣고 진정으로 조합 가능하게 만들고 싶습니다. 그래서 스킬은 점진적으로 공개됩니다. 런타임에는 이 메타데이터만 모델에 보여서 그 스킬이 있다는 것만 알립니다. 에이전트가 스킬을 써야 할 때 나머지 SKILL.md를 읽어 들이고, 거기에 핵심 지시와 폴더의 나머지에 대한 안내가 들어 있습니다. 그 밖의 것은 접근하기 쉽게 정리돼 있을 뿐입니다."

크게 보기

엔지니어링 글은 이것을 "잘 정리된 매뉴얼이 목차로 시작해 각 장으로, 마지막에 자세한 부록으로 이어지는 것"에 비유하고, 세 단계를 명시한다.

글의 PDF 스킬 예시가 이 구조를 잘 보여 준다. Claude는 PDF를 이해하는 데는 능하지만 직접 조작(예: 서식 채우기)에는 한계가 있었다. PDF 스킬의 SKILL.md는 본문을 가볍게 유지하고, 서식 채우기 지시를 별도 파일 forms.md로 뺐다. "스킬 저자는 Claude가 서식을 채울 때만 forms.md를 읽을 것이라고 믿고 스킬의 핵심을 얇게 유지할 수 있다." 그리고 이런 문장이 따라온다.

"파일 시스템과 코드 실행 도구를 가진 에이전트는 특정 과제를 수행할 때 스킬 전체를 컨텍스트 창에 읽어 들일 필요가 없습니다. 이것은 스킬에 묶어 넣을 수 있는 컨텍스트의 양이 사실상 무제한이라는 뜻입니다."

아래 탐색기에서 견적서 작성 스킬의 폴더를 하나씩 눌러 보라. 어떤 파일이 어느 단계에서 컨텍스트에 들어가고, 어떤 파일은 아예 들어가지 않는지(실행만 되는지) 확인할 수 있다.

숫자로 보는 점진적 공개

왜 이것이 "수백 개의 스킬"을 가능하게 하는지 숫자로 보자. 스킬 60개를 설치했고 각 본문이 3,000토큰이라고 가정한다. 전부 시스템 프롬프트에 넣으면 18만 토큰이다. 20만 토큰 창이라면 실제 대화에 쓸 자리가 거의 없다. 점진적 공개에서는 60개의 메타데이터 6,000토큰만 늘 들어가고, 이번 과제에 실제로 쓰는 두 개의 본문 6,000토큰이 더해진다. 합계 1만 2천 토큰. 전부 넣기의 7% 수준이다. 슬라이더를 움직여 직접 확인해 보라.

사이먼 윌리슨(Simon Willison)은 출시 당일 이 점을 짚었다. MCP 서버 여러 개를 연결하면 도구 정의만으로 "수만 토큰"이 들어가는데, 스킬은 세션 시작 시 "몇십 토큰"만 쓰고 자세한 내용은 필요할 때 로드된다는 것이다. 이것이 그가 스킬을 "MCP보다 큰 일일지도"라고 부른 이유 중 하나다(9장에서 다시 본다).

5. 스크립트를 도구로 — "미래의 자신을 위해 저장하라"

세 번째로 프롬프트와 다른 지점. 스킬은 코드를 도구로 품는다. 발표는 전통적인 도구(함수 호출로 노출되는 도구)의 세 가지 문제를 지적한다.

엔지니어링 글은 왜 어떤 일은 코드가 해야 하는지 두 가지 이유를 든다. 첫째 효율. "토큰 생성으로 리스트를 정렬하는 것은 정렬 알고리즘을 그냥 실행하는 것보다 훨씬 비싸다." 둘째 결정론. "많은 응용은 코드만이 줄 수 있는 결정론적 신뢰성을 요구한다." PDF 스킬에는 PDF의 서식 필드를 전부 추출하는 파이썬 스크립트가 들어 있고, "Claude는 스크립트도 PDF도 컨텍스트에 올리지 않고 이 스크립트를 실행할 수 있다. 코드는 결정론적이므로 이 워크플로는 일관되고 반복 가능하다."

이것이 사용자가 지적한 "Skill이 단순한 긴 프롬프트가 아니다"의 기술적 의미다. 프롬프트는 모델에게 "이렇게 계산해"라고 말한다. 모델은 매번 그 말을 다시 해석하고 다시 계산한다. 스킬은 "이 스크립트를 실행해"라고 말하고 스크립트를 함께 준다. 계산은 매번 같다. 견적 업무에서 단가에 수량을 곱하고 할인을 적용하는 일을 LLM의 산술에 맡길 이유가 없다.

얼마나 자유를 줄 것인가

그렇다면 무엇을 텍스트 지침으로 두고 무엇을 스크립트로 고정할까. 앤트로픽의 저작 가이드는 이 질문에 "자유도"라는 개념으로 답한다. 비유가 좋다.

"Claude를 길을 탐색하는 로봇이라고 생각하십시오. 양쪽이 절벽인 좁은 다리라면 안전한 길은 하나뿐입니다. 구체적인 난간과 정확한 지시를 주십시오(낮은 자유도). 예: 정확한 순서로 실행해야 하는 데이터베이스 마이그레이션. 위험 없는 열린 들판이라면 많은 길이 성공으로 이어집니다. 대략의 방향만 주고 Claude가 최선의 경로를 찾도록 맡기십시오(높은 자유도). 예: 맥락이 최선의 접근을 결정하는 코드 리뷰."

가이드는 세 단계를 둔다. 높은 자유도는 텍스트 지침(여러 접근이 유효하고 판단이 맥락에 달릴 때). 중간 자유도는 매개변수가 있는 스크립트나 의사코드(선호 방식은 있지만 변형을 허용할 때). 낮은 자유도는 매개변수가 거의 없는 특정 스크립트("정확히 이 스크립트를 실행하라. 명령을 수정하거나 플래그를 추가하지 마라"). 아래에서 업무의 성격을 고르면 권장 형태가 나온다.

6. 출시 5주 — 생태계의 세 갈래와 MCP와의 관계

발표 시점은 스킬 공개 5주 뒤였다. 무라그는 "이 아주 단순한 설계가 수천 개의 스킬로 빠르게 자라는 생태계로 번역되었다"고 말하고, 세 갈래로 나눈다.

무라그가 "개인적으로 가장 흥미롭다"고 한 관찰은 세 번째 갈래 안에 있다.

"기술직이 아닌 사람들이 스킬을 만들고 있습니다. 재무, 채용, 회계, 법무 같은 직능의 사람들입니다. 이것은 우리의 원래 생각, 즉 스킬이 코딩을 하지 않는 사람들도 이 범용 에이전트를 확장할 수 있게 하고 에이전트를 그들의 일상 업무에 더 가깝게 만든다는 생각의 초기 검증이라고 봅니다."

크게 보기

이 관찰이 발표 제목의 진짜 근거다. 전용 에이전트는 AI 엔지니어만 만들 수 있다. 업무를 아는 회계 담당자는 에이전트 루프를 못 짠다. 그러나 폴더에 마크다운을 쓰는 일은 할 수 있다. 업무 안내서를 쓰는 일은 원래 그 사람의 일이었다. 스킬은 전문성의 병목을 엔지니어에서 현업으로 옮긴다.

스킬은 MCP를 대체하지 않는다

두 번째 관찰은 MCP와의 관계다. 두 사람은 MCP를 만든 회사 소속이니 이 질문을 피할 수 없다. 답은 분명하다.

"스킬 생태계는 올해 쌓인 MCP 서버 생태계를 보완하고 있습니다. 개발자들은 여러 MCP 도구를 엮어 외부 데이터와 연결로 더 복잡한 일을 하는 워크플로를 스킬로 만들고 있습니다. 이런 경우 MCP는 바깥 세계로의 연결을 제공하고, 스킬은 전문성을 제공합니다."

전문성을 에이전트에 주는 방법은 스킬만이 아니다. 각 방법이 무엇을 해결하고 무엇을 못 하는지 한 표에 놓는다.

이 표에서 스킬이 특별한 칸은 마지막 두 열이다. 컨텍스트 비용이 낮고, 고치는 사람이 업무 담당자다. 나머지 열에서 스킬은 MCP와 RAG와 경쟁하지 않는다. MCP가 데이터를 가져오고, 스킬이 그 데이터로 무엇을 어떤 순서로 할지 안다. 발표는 실제 사례로 앤트로픽 자신을 든다. 스킬 출시 직후 금융 서비스와 생명과학 분야 제품을 냈는데, "각각 MCP 서버 한 세트와 스킬 한 세트를 갖추고 나와서 그 분야 전문가에게 Claude를 즉시 더 유용하게 만들었다."

7. 아키텍처 — 프로세서, 운영체제, 애플리케이션

발표 후반은 "범용 에이전트의 부상하는 아키텍처"를 정리한다. 수렴하고 있는 구성은 셋이다.

"오늘 에이전트에 새 도메인의 새 능력을 주는 일은 올바른 MCP 서버 세트와 올바른 스킬 라이브러리를 갖춰 주는 것만으로 끝날 수 있습니다."

여기서 발표 제목이 실질이 된다. 업무 다섯 개가 있다면 에이전트 다섯 개를 만드는 대신 에이전트 하나에 스킬 폴더 다섯 개를 준다. 아래 위젯에서 업무를 켜고 꺼 보며 두 방식에서 만들고 유지해야 하는 구성 요소가 어떻게 달라지는지, 그리고 "할인 규정이 바뀌었다"는 흔한 사건이 두 방식에서 각각 무엇을 건드리는지 비교해 보라. 발표는 비용 수치를 제시하지 않았으므로 위젯의 숫자는 구조 비교용이다.

스택 비유

발표의 마무리는 컴퓨팅 역사와의 비유다.

크게 보기

"대략의 비유로, 모델은 프로세서와 같습니다. 둘 다 막대한 투자가 필요하고 엄청난 잠재력을 담고 있지만, 그 자체로는 쓸모가 제한적입니다. 그다음 우리는 운영체제를 만들기 시작했습니다. OS는 프로세서 주위의 프로세스와 자원과 데이터를 조율해서 프로세서를 훨씬 가치 있게 만들었습니다. AI에서는 에이전트 런타임이 이 역할을 시작하고 있다고 봅니다. 우리 모두 모델에 올바른 토큰을 넣고 빼는 가장 깨끗하고 효율적이고 확장성 있는 추상화를 만들려 하고 있습니다. 그러나 플랫폼이 생기면 진짜 가치는 애플리케이션에서 옵니다. 프로세서와 운영체제를 만드는 회사는 몇 개지만, 우리 같은 수백만 명의 개발자가 도메인 전문성과 고유한 관점을 담은 소프트웨어를 만들었습니다. 우리는 스킬이 이 층을 모두에게 열어 주기를 바랍니다. 그냥 폴더에 뭔가를 넣는 것만으로 우리 자신과 서로와 세상을 위한 구체적인 문제를 푸는 곳입니다."

비유의 함의를 한 걸음 더 밀어 보자. 운영체제 시대에 "업무마다 컴퓨터를 따로 만들자"고 한 사람은 없었다. 회계용 컴퓨터, 문서용 컴퓨터, 설계용 컴퓨터를 따로 만드는 대신 범용 컴퓨터에 회계 프로그램, 워드프로세서, CAD를 설치했다. "업무마다 에이전트를 만들자"는 2025년의 유행은 바로 그 이상한 일을 하고 있었다는 것이 발표의 진단이다.

8. 잘 쓰는 법 — 앤트로픽 저작 가이드 해부

발표와 글이 "무엇"을 말한다면, 앤트로픽 개발자 문서의 「Skill authoring best practices」는 "어떻게"를 말한다. 이 문서는 스킬을 쓰는 사람이 반드시 읽어야 하는데, 여러 권고가 직관에 반한다. 중요한 것을 뽑는다.

원칙 1: 컨텍스트 창은 공공재다

"컨텍스트 창은 공공재입니다. 당신의 스킬은 시스템 프롬프트, 대화 이력, 다른 스킬들의 메타데이터, 사용자의 실제 요청과 컨텍스트 창을 나눠 씁니다."

그래서 기본 가정은 이것이다. "Claude는 이미 매우 똑똑하다." Claude가 모르는 맥락만 더하라. 문단마다 물어라. "이 설명이 정말 필요한가? Claude가 이미 안다고 가정할 수 없나? 이 문단은 토큰 비용을 정당화하는가?" 가이드가 든 예시는 PDF 텍스트 추출이다. 좋은 예는 라이브러리 이름과 네 줄 코드로 약 50토큰. 나쁜 예는 "PDF는 텍스트와 이미지를 담는 흔한 파일 형식이고, 추출하려면 라이브러리가 필요하고, 여러 라이브러리가 있지만…"으로 약 150토큰. 뒤의 것은 Claude가 다 아는 이야기다.

이 원칙은 사람의 업무 매뉴얼을 스킬로 바꿀 때 특히 중요하다. 신입용 매뉴얼은 배경 설명이 길다. 스킬은 그 배경을 잘라내고 우리 회사에서만 다른 것만 남긴다.

원칙 2: 설명문은 3인칭으로, 무엇과 언제를 함께

description은 에이전트가 100개 이상의 스킬 중에서 이 스킬을 고를 때 보는 유일한 단서다. 가이드는 두 가지를 강조한다. 첫째, 무엇을 하는지와 언제 쓰는지를 모두 적을 것. "PDF 파일에서 텍스트와 표를 추출하고 서식을 채우고 문서를 병합한다. PDF 파일을 다룰 때, 또는 사용자가 PDF·서식·문서 추출을 언급할 때 사용한다." 둘째, 항상 3인칭으로 쓸 것. "설명문은 시스템 프롬프트에 주입되므로 시점이 일관되지 않으면 발견에 문제가 생긴다." "I can help you process Excel files"는 피하라.

이름은 동명사형(processing-pdfs, analyzing-spreadsheets)을 권하고, helper·utils·documents·data 같은 모호한 이름과 anthropic·claude라는 예약어를 피하라고 한다. 아래 검사기에 설명문을 써 보라. 가이드의 권고를 체크 항목으로 옮긴 것이다.

원칙 3: 500줄, 한 단계 깊이, 100줄 넘으면 목차

SKILL.md 본문은 500줄 이하로 유지하고, 그 한계에 가까워지면 파일을 나눈다. 참조는 SKILL.md에서 한 단계만 깊게. 가이드는 이유를 구체적으로 적는다. 참조된 파일에서 또 참조된 파일은 Claude가 head -100 같은 명령으로 앞부분만 훑고 넘어가 정보가 불완전해질 수 있다. 100줄이 넘는 참고 파일은 맨 위에 목차를 두어 부분 읽기에서도 전체 범위가 보이게 한다.

원칙 4: 체크리스트와 피드백 루프

복잡한 작업은 순서 있는 단계로 쪼개고, "Claude가 자기 응답에 복사해 넣고 하나씩 지워 가는 체크리스트"를 제공하라. 그리고 "검증기 실행 → 오류 수정 → 반복" 패턴을 넣으라. 가이드는 이것이 "출력 품질을 크게 높인다"고 말한다. 검증기는 스크립트일 수도 있고(validate.py), 문서일 수도 있다(스타일 가이드를 읽고 체크리스트와 비교). 사용자가 짚은 "업무를 맡기는 방법과 결과를 검수하는 방법을 함께 문서화한다"가 바로 이것이다. 절차만 적은 스킬은 반쪽이다. 완료 기준과 검증 단계가 있어야 한다.

원칙 5: 평가를 먼저 만들라

가장 반직관적인 권고다.

"광범위한 문서를 쓰기 전에 평가를 만드십시오. 이렇게 하면 스킬이 상상한 문제를 문서화하는 것이 아니라 실제 문제를 풀게 됩니다."

절차는 다섯 단계다. ① 스킬 없이 대표 과제를 시켜 보고 구체적 실패를 기록한다. ② 그 빈틈을 시험하는 시나리오 세 개를 만든다. ③ 스킬 없는 성능을 기준선으로 잰다. ④ 빈틈을 메우고 평가를 통과할 최소한의 지시만 쓴다. ⑤ 평가를 돌리고 기준선과 비교하며 다듬는다. 엔지니어링 글도 첫 지침으로 같은 말을 한다. "평가에서 시작하라. 에이전트를 대표 과제에 돌려 어디서 어려움을 겪고 어떤 맥락이 더 필요한지 관찰한 뒤, 그 부족을 메우는 스킬을 점진적으로 만들라."

사용자의 요약, "에이전트 수부터 늘리지 말고, 기존 업무 문서를 실행 가능한 지침으로 바꾸며 단순한 구성부터 검증하라"가 정확히 이 원칙이다.

원칙 6: Claude와 함께 반복하라

가이드는 두 인스턴스를 쓰라고 한다. "Claude A"는 스킬을 설계·다듬는 조력자, "Claude B"는 스킬을 로드해 실제 과제를 수행하는 실행자. B가 어디서 막히는지 관찰하고 A에게 가져가 고친다. "Claude B가 지역별 매출 보고서를 만들 때 테스트 계정 제외 규칙을 잊었다. 스킬에 규칙이 있는데 눈에 덜 띄는 것 같다." A는 규칙을 앞으로 옮기거나 "always" 대신 "MUST"로 바꾸는 식의 수정을 제안한다. 엔지니어링 글의 표현으로는 "과제를 함께 하면서 Claude에게 성공한 접근과 흔한 실수를 스킬 안의 재사용 가능한 컨텍스트와 코드로 포착하라고 요청하라. 이 과정이 Claude가 실제로 필요한 맥락을 미리 짐작하는 대신 발견하게 해 준다."

스크립트 쪽의 권고

코드가 있는 스킬을 위한 권고도 있다. "해결하라, 미루지 말라": 스크립트는 오류를 스스로 처리해야 하고 "그냥 실패하고 Claude가 알아내게 두는" 코드는 나쁘다. "부두 상수를 피하라"(오스터하우트의 법칙): TIMEOUT = 47 # 왜 47? 같은 설명 없는 숫자는 금지. 값을 모르면 Claude는 어떻게 알겠는가. 실행할 스크립트인지 참고용으로 읽을 스크립트인지를 지시문에서 분명히 하라. "plan-validate-execute", 즉 Claude가 먼저 구조화된 계획 파일을 만들고 스크립트로 검증한 뒤 실행하는 패턴은 일괄 작업과 되돌리기 어려운 작업에 쓰라. 그리고 하이쿠·소넷·오퍼스 세 모델 모두로 시험하라. "오퍼스에 완벽한 것이 하이쿠에는 설명이 더 필요할 수 있다."

9. 반론과 위험 — 열광, 마찰, 그리고 ToxicSkills

열광: "MCP보다 큰 일일지도"

출시 당일인 2025년 10월 16일, 사이먼 윌리슨은 「Claude Skills are awesome, maybe a bigger deal than MCP」를 올렸다. 그는 공식 발표 전 주에 이미 claude.ai의 코드 실행 환경 /mnt/skills/ 경로에서 스킬을 발견해 글을 썼던 사람이다. 그의 논지는 단순함이다. 스킬은 "약간의 YAML 메타데이터와 선택적 스크립트가 붙은 마크다운"이고, 복잡한 프로토콜 사양이 필요한 MCP와 달리 LLM이 이미 잘하는 것, 즉 파일 시스템 탐색과 명령 실행을 그대로 쓴다. 어떤 모델, 어떤 CLI 도구와도 동작한다. 그는 이렇게 예측했다.

"올해의 MCP 러시가 시시해 보일 만큼 스킬의 캄브리아기 대폭발이 올 것이라 예상합니다."

수치로 보면 예측은 맞는 쪽으로 갔다. 앤트로픽의 공개 저장소 anthropics/skills는 2026년 9월 기준 별 17만 7천 개, 포크 2만 1천 개다. agentskills.io의 클라이언트 쇼케이스에는 Cursor, OpenAI Codex, Gemini CLI, VS Code, GitHub Copilot, Goose, JetBrains Junie, Kiro, Spring AI 등 40여 제품이 올라 있다. 12월 18일 오픈 스탠다드 발표 때 마이크로소프트·OpenAI·아틀라시안·피그마·커서·깃허브가 지원을 밝혔다.

마찰: 첫 사용기

같은 달 20일, 개발자 톰 맥라이트(Tom MacWright)는 첫 사용기를 올렸다. Claude Code에 코드 검색 도구 ast-grep을 쓰는 스킬을 만들라고 했더니 두 가지가 틀렸다. 파일을 .claude/skills/ast-grep.md에 만들었다(정답은 .claude/skills/ast-grep/SKILL.md). 그리고 필수인 YAML 프론트매터를 빼먹었다. 그는 "앤트로픽이 스킬 파일이 어디에 가야 하는지 알려 주는 강한 프롬프트를 갖고 있지 않다는 것이 놀랍다"고 썼다. 의존성 관리도 "매우 엉성하다"고 봤다. 원격 실행 환경(최소 파이썬)과 로컬(무제한 시스템 접근)이 크게 달라 스킬을 옮겨 쓰기 어렵다는 것이다. 그리고 보안.

"자동화는 95%의 시간 동안 당신을 편안하게 만들고, 나머지 5%의 시간에 당신의 완전한 경계심을 요구합니다."

첫 번째 문제(파일 위치)는 이후 skill-creator 스킬과 문서로 대체로 해결되었다. 두 번째(의존성)는 발표에서 두 사람이 스스로 "다음 과제"로 꼽았다. 세 번째는 넉 달 뒤 숫자로 확인되었다.

위험: 스킬 3,984개를 스캔하다

크게 보기

2026년 2월 5일, 보안 회사 Snyk가 「ToxicSkills」 보고서를 냈다. 스킬 등록소 ClawHub와 skills.sh에서 3,984개의 스킬을 스캔한 결과다.

공격 패턴은 세 가지였다. 신뢰할 수 없는 바이너리를 내려받아 실행하게 하는 설치 지시(종종 암호 걸린 압축 파일), base64나 유니코드로 숨긴 자격 증명 탈취 명령, 안전장치를 끄거나 설정을 바꾸게 하는 지시. 그리고 한 문장이 스킬 위험의 본질을 말한다. "확인된 악성 스킬의 100%가 악성 코드 패턴을 담고 있었고, 91%는 동시에 프롬프트 주입 기법을 썼다." 스킬은 지시와 코드를 함께 담기 때문에 두 종류의 공격이 한 폴더에서 만난다.

공정하게 적어야 할 것이 있다. 이 수치는 OpenClaw라는 개인 에이전트 프레임워크의 커뮤니티 등록소 위주이고, 앤트로픽의 공식 스킬이나 기업 내부 스킬의 상태가 아니다. 그러나 스킬의 장점, 즉 "누구나 만들고 zip으로 공유할 수 있다"는 성질이 곧 위험의 근원이라는 점은 등록소가 어디든 같다. 앤트로픽의 엔지니어링 글도 출시 당일부터 이 경고를 넣었다. "신뢰할 수 있는 출처의 스킬만 설치하라. 덜 신뢰할 수 있는 출처라면 사용 전에 철저히 감사하라. 코드 의존성과 이미지·스크립트 같은 동봉 자원에 특히 주의하고, 잠재적으로 신뢰할 수 없는 외부 네트워크에 연결하게 하는 지시나 코드에 주의하라." 조직 안에서 스킬을 쓸 때는 npm 패키지를 다루듯 다뤄야 한다. 출처를 정하고, 검토를 거치고, 버전을 고정한다.

비판: 증거는 어디에

2026년 3월 해커뉴스의 한 토론에서 한 사용자는 스킬 담론 전체에 이렇게 물었다. "이 담론 대부분은 권위 편향 위에 세운 종교 의식 같다. 스킬이 다른 방법론보다 성능을 높인다는 증거가, 지금 인기 있다는 사실 말고 어디에 있나?" 정직한 답은 "통제된 공개 벤치마크는 아직 없다"이다. 앤트로픽 가이드조차 "현재 이 평가를 돌리는 내장 방법은 없다. 사용자가 자기 평가 시스템을 만들어야 한다"고 적고 있다. 발표자들도 "테스트와 평가, 스킬이 올바른 때에 올바른 과제에 로드되는지 확인하는 도구, 스킬을 갖춘 에이전트의 출력 품질을 측정하는 도구"를 앞으로의 숙제로 꼽았다.

같은 토론의 다른 댓글은 배포 문제를 짚었다. "배포 문제는 보기보다 어렵다. 사실은 위장한 조합 문제이기 때문이다. 스킬 하나는 zip으로 공유하면 그만이지만, 실제로는 다른 스킬에 의존하는 스킬, 특정 지시가 이미 로드돼 있다고 가정하는 스킬, 서로 충돌하는 스킬, 버전과 공급망 문제가 생기고, 갑자기 의존성 해결이 필요해진다." 발표의 "다음 과제" 세 가지, 즉 테스트·평가, 버전과 계보, 다른 스킬·MCP 서버·패키지에 대한 명시적 의존성이 정확히 이 지적에 대응한다. 두 사람은 이렇게 요약했다. "스킬을 소프트웨어처럼 다루기 시작하고 싶다."

10. 스스로 배우는 에이전트 — 1일째와 30일째

발표에서 배리 장이 가장 힘을 준 부분은 스킬을 지속 학습의 구체적 한 걸음으로 설계했다는 대목이다.

크게 보기

"Claude를 처음 쓰기 시작할 때, 이 표준화된 형식은 매우 중요한 보장을 하나 줍니다. Claude가 적어 둔 것은 무엇이든 미래의 자신이 효율적으로 쓸 수 있습니다. 이것이 학습을 실제로 이전 가능하게 만듭니다. 맥락이 쌓이면 스킬은 메모리라는 개념을 더 손에 잡히게 합니다. 모든 것을 포착하지는 않습니다. 모든 종류의 정보를 포착하지도 않습니다. 특정 과제에 Claude가 쓸 수 있는 절차적 지식만 포착합니다. Claude와 오래 일했다면 스킬의 유연성이 더 중요해집니다. Claude는 새 능력을 즉시 얻고, 필요에 따라 진화시키고, 쓸모없어진 것을 버릴 수 있습니다. 우리의 목표는 당신과 30일째 일하는 Claude가 1일째 Claude보다 훨씬 낫게 되는 것입니다."

여기서 스킬과 "메모리"의 구분이 중요하다. 흔히 말하는 에이전트 메모리는 대화에서 나온 사실, 선호, 일화를 저장한다. 스킬은 그중 절차만 저장한다. "이 고객은 결제가 느리다"는 메모리다. "견적서를 보내기 전에 할인율 상한을 확인한다"는 스킬이다. 절차만 저장하는 이유는 발표가 말한 대로 "재사용 가능하고 전이 가능한 것"이 절차이기 때문이고, 앤트로픽의 가이드가 말한 대로 "시간에 민감한 정보는 스킬에 넣지 말라"는 원칙과도 맞는다.

이 방향은 이미 제품이 되었다. 발표는 "Claude는 오늘 skill-creator 스킬로 당신을 위해 스킬을 만들 수 있다"고 했고, 엔지니어링 글은 "더 멀리 보면 에이전트가 스스로 스킬을 만들고, 편집하고, 평가해서 자기 행동 패턴을 재사용 가능한 능력으로 코드화할 수 있게 하고 싶다"고 적었다. 그리고 발표가 그린 조직 차원의 그림이 있다.

"우리를 가장 흥분시키는 비전은 조직 안의 사람과 에이전트가 함께 큐레이션하는, 축적되고 진화하는 능력의 지식 기반입니다. 에이전트와 상호작용하며 피드백과 제도적 지식을 줄수록 에이전트가 나아지고, 팀과 조직 안의 모든 에이전트가 함께 나아집니다. 누군가 팀에 합류해 처음 Claude를 쓰면, Claude는 이미 팀이 무엇을 중요하게 여기는지, 일상이 어떤지, 이 일에서 어떻게 가장 효과적일 수 있는지 압니다."

이 그림이 사용자의 요약과 만난다. "업무마다 새로운 AI 에이전트를 만들기보다, 범용 AI가 따라 할 수 있는 업무 매뉴얼을 만들고 계속 개선하자." 계속 개선하는 주체가 사람만이 아니라는 것, 그리고 개선된 매뉴얼이 팀 전체의 자산이 된다는 것이 발표의 추가분이다.

11. 우리 조직에 적용 — 견적 매뉴얼을 스킬로

이론은 충분하다. 한국의 보통 중소기업에 이미 있는 것에서 시작하자. 견적 업무를 예로 든다. 대부분의 회사에는 다음이 이미 있다. 견적을 내는 순서를 아는 담당자, 엑셀 단가표, 견적서 서식, 할인은 얼마까지라는 암묵적 규정, 그리고 "보내기 전에 이건 꼭 확인해"라는 구두 전승.

크게 보기

이것을 전용 "견적 에이전트"로 만들려면 개발자가 필요하다. 스킬로 만들면 담당자가 만들 수 있다. 절차는 이렇다.

아래 빌더에서 이 절차를 직접 밟아 보라. 절차와 검수 항목을 고치고 스크립트·서식·참고 자료를 켜면 SKILL.md와 폴더 구조가 실시간으로 만들어진다. 만들어진 텍스트는 그대로 시작점으로 쓸 수 있다.

어떤 업무가 스킬에 맞는가

모든 업무가 스킬로 좋아지지는 않는다. 스킬에 잘 맞는 업무의 특징을 정리한다.

12. 이번 주에 해볼 일

발표와 글과 가이드에서 실천 항목을 다섯 개로 줄인다.

1. 에이전트를 하나 더 만들려던 계획을 멈추고, 그 업무의 매뉴얼을 찾으라. 없다면 담당자에게 30분 동안 절차를 말하게 하고 받아 적으라. 그것이 SKILL.md의 초안이다.
2. 스킬 없이 세 번 시켜 보고 실패를 적으라. 이 세 건이 당신의 평가 세트다. 평가 없이 쓴 스킬은 상상한 문제를 문서화한다.
3. 설명문을 3인칭으로, 무엇과 언제를 넣어 한 문장으로 쓰라. 8장의 검사기에 넣어 보라. 에이전트가 스킬을 고르는 단서는 이 한 문장뿐이다.
4. 숫자가 나오는 곳은 스크립트로 바꾸라. LLM이 곱셈을 하게 두지 말라. 스크립트는 에이전트가 짜고 사람이 검증하면 된다.
5. 출처 규칙을 정하라. 외부 스킬은 npm 패키지처럼 다룬다. 어디서 받는지, 누가 읽어 보는지, 어떻게 고정하는지를 도입 전에 정한다. 3,984개 중 1,467개에 결함이 있었다.

마치며 — 그냥 폴더에 넣는 것만으로

발표는 이렇게 끝난다.

"우리는 범용 에이전트를 위한 이 일반 아키텍처로 수렴하고 있다고 생각합니다. 우리는 새 능력을 배포하고 공유하는 새 패러다임으로 스킬을 만들었습니다. 그래서 이제 에이전트를 다시 만드는 일을 멈추고 스킬을 만들기 시작할 때라고 생각합니다."

이 발표가 열어 준 것은 기술이 아니라 관점이다. 지난 1년 동안 우리는 모델이 얼마나 똑똑한지에 집중했다. 발표는 질문을 바꾼다. 똑똑한 것에게 우리 일을 어떻게 가르칠 것인가. 답은 회사가 신입에게 하는 것과 같다. 뇌를 바꾸지 않는다. 안내서를 준다. 안내서는 절차와 계산과 서식과 검수를 담고, 필요할 때 펼치고, 규정이 바뀌면 고치고, 사람이 바뀌어도 남는다.

그 안내서를 폴더에 넣으면 스킬이 된다. 무라그의 말대로 "그냥 폴더에 뭔가를 넣는 것만으로." 이 단순함이 발표의 결론이자 이 특집의 결론이다. 에이전트는 이미 있다. 이제 만들 것은 우리가 아는 것을 적은 폴더다.

참고 문헌

발표와 원문

• Zhang, B. & Murag, M. (2025-11-20 발표, 2025-12-08 공개). Don't Build Agents, Build Skills Instead. AI Engineer Code Summit, New York. 16분 22초. 발표 페이지: ai.engineer/talks/CEvIs9y1uog-agent-skills. 행사 일정: AI Engineer Code Summit, Nov 19–22, 2025. 발표 날짜는 행사 일정과 "출시 5주 뒤"라는 발언에서 추정했다.
• Zhang, B., Lazuka, K. & Murag, M. (2025-10-16). Equipping agents for the real world with Agent Skills. Engineering at Anthropic.
• Anthropic (2025-10-16). Introducing Agent Skills.
• Schluntz, E. & Zhang, B. (2024-12-19). Building Effective Agents. Anthropic.

사양과 문서

• Agent Skills — 오픈 스탠다드 홈. Specification. 공개 2025-12-18. 저장소: github.com/agentskills/agentskills.
• Anthropic. Skill authoring best practices. Claude Developer Platform 문서.
• Anthropic. Agent Skills overview; Extend Claude with skills (Claude Code 문서, 2026-09 열람).
• anthropics/skills — 공개 스킬 저장소. 2026-09-19 기준 별 177.1k, 포크 21.0k. 문서 스킬은 소스 공개(source-available), 나머지는 Apache 2.0.

반응과 비판

• Willison, S. (2025-10-16). Claude Skills are awesome, maybe a bigger deal than MCP.
• MacWright, T. (2025-10-20). First-run with agent skills from Anthropic.
• Hacker News (2026-03-22). Skills are quietly becoming the unit of agent knowledge. "권위 편향"·"조합 문제" 댓글 출처.
• Snyk (2026-02-05). ToxicSkills: Malicious AI Agent Skills on ClawHub. 3,984개 스캔, 36.82%(1,467개) 결함, 13.4%(534개) 심각, 76개 악성 확인, 8개 공개 중, ClawHub 스킬의 10.9% 하드코딩 비밀 키.
• SiliconANGLE (2025-12-18). Anthropic makes agent Skills an open standard; VentureBeat (2025-12-18). Anthropic launches enterprise Agent Skills and opens the standard.

맥락

• Anthropic (2024-11-25). Introducing the Model Context Protocol.
• Anthropic (2025-02-24). Claude 3.7 Sonnet and Claude Code. Claude Code 리서치 프리뷰.
• Anthropic (2025-09-29). Building agents with the Claude Agent SDK.

발표와 원문의 인용은 이 글의 우리말 번역이며, 정확한 표현은 원문과 영상으로 확인하기를 권한다. 위젯의 견적 업무 예시와 구성 요소 개수는 이 글이 설명을 위해 만든 것이다. 참고로 이 특집을 쓴 도구 자체가 이 글에서 설명한 스킬 형식을 쓴다. 우리가 위젯을 만들고 글을 쓰는 방식도 폴더 안의 SKILL.md에 적혀 있다.