무엇인가
Agent Skills는 범용 에이전트가 필요할 때 꺼내 읽는 업무 안내서를 폴더 하나로 묶는 형식입니다. Anthropic이 2025년 10월 16일 공개했고, 같은 해 12월 18일 agentskills.io에 오픈 스탠다드 사양을 올렸습니다. 최소 요건은 폴더 하나와 그 안의 SKILL.md 하나입니다. 파일은 YAML 프론트매터로 시작하고, 필수 필드는 name과 description 둘뿐입니다.
발상은 Anthropic의 배리 장·마헤시 무라그가 2025년 11월 AI Engineer Code Summit에서 한 발표 「Don't Build Agents, Build Skills Instead」에 압축돼 있습니다. 모델은 이미 IQ 300의 천재처럼 똑똑하지만, 우리 회사의 견적 규정이나 2025년 세법은 모릅니다. 부족한 것은 지능이 아니라 업무를 해 본 사람만 아는 절차와 맥락이고, 이것을 새 에이전트가 아니라 폴더에 담으라는 주장입니다. 에이전트의 밑바닥(모델 루프 + 파일 시스템 + 코드 실행)은 도메인과 상관없이 같으니, 업무 다섯 개에는 에이전트 다섯 개가 아니라 에이전트 하나와 스킬 폴더 다섯 개를 준다는 것입니다.
코어닷투데이는 스킬을 '긴 프롬프트'와 세 가지가 다른 것으로 봅니다. 프롬프트는 한 덩어리 글이지만 스킬은 파일 시스템 위의 구조이고, 필요한 부분만 점진적으로 읽히며, 코드를 도구로 품습니다.
어떻게 동작하나
name + description, 설치된 모든 스킬이 항상 로드. 스킬당 약 100토큰
관련 있다고 판단될 때만 읽음. 5,000토큰·500줄 이하 권장
참고 문서는 필요할 때 읽고, 스크립트는 읽지 않고 실행. 사실상 무제한
description은 에이전트가 수많은 스킬 중 이것을 고를 때 보는 유일한 단서입니다. 그래서 무엇을 하는지와 언제 쓰는지를 함께, 3인칭으로 씁니다. 숫자 예로 보면 스킬 60개(본문 각 3,000토큰)를 시스템 프롬프트에 전부 넣으면 18만 토큰이지만, 점진적 공개에서는 메타데이터 6,000토큰에 이번 과제에 쓰는 본문 두 개 6,000토큰을 더한 1만 2천 토큰, 약 7%입니다(원 글의 가정 계산).
| 필드 | 필수 | 제약 |
|---|---|---|
name | 예 | 64자 이하, 소문자·숫자·하이픈만, 하이픈으로 시작·끝·연속 불가, 폴더 이름과 일치 |
description | 예 | 1~1,024자. 무엇을 하고 언제 쓰는지 |
license · compatibility · metadata | 아니오 | 라이선스 이름, 요구 환경(500자 이하), 문자열 맵 |
allowed-tools | 아니오 | 사전 승인 도구 목록. 실험적 |
본문 형식은 자유이고, 관례로 scripts/(실행 코드)·references/(참고 문서)·assets/(템플릿·데이터)를 둡니다. 계산처럼 결정론이 필요한 일은 스크립트로 고정합니다. "토큰 생성으로 리스트를 정렬하는 것은 정렬 알고리즘을 실행하는 것보다 훨씬 비싸다"는 것이 Anthropic 엔지니어링 글의 설명입니다. 저작 가이드는 이것을 자유도로 나눕니다. 판단이 맥락에 달린 일은 텍스트 지침(높은 자유도), 선호 방식이 있는 일은 매개변수 스크립트(중간), 순서가 하나뿐인 일은 "정확히 이 스크립트를 실행하라"(낮은 자유도)입니다.
MCP와는 경쟁이 아니라 분업입니다. 발표의 표현으로 "MCP는 바깥 세계로의 연결을, 스킬은 전문성을 제공"합니다. MCP 도구 정의는 컨텍스트에 상주하고 도구를 어떻게 엮을지는 알려 주지 않습니다. 스킬은 메타데이터만 상주하고 그 순서와 검수 기준을 담습니다.
빠른 시작
원 글의 견적 업무 예시를 스킬로 옮기면 이렇게 됩니다(빌더 위젯이 만드는 형태를 줄인 것이며, 절차·파일 이름은 설명용 예시입니다). Claude Code에서는 개인 스킬을 ~/.claude/skills/<name>/SKILL.md, 프로젝트 스킬을 .claude/skills/<name>/SKILL.md에 둡니다.
---
name: quotation-builder
description: 고객 요청서를 받아 견적서를 작성하고 검수한다. 견적, 단가표, 할인 규정, 납기 산정을 언급하거나 견적서 작성을 요청받으면 사용한다.
---
## 절차
1. 요청서에서 품목·수량·납기를 뽑는다.
2. 단가·할인 계산은 반드시 `python scripts/calc_quote.py --input request.json` 을 실행한다. 직접 계산하지 않는다.
3. 할인 상한과 예외는 [references/pricing-rules.md](references/pricing-rules.md) 를 읽고 적용한다.
4. `assets/quote-template.xlsx` 를 복사해 채운다. 셀 위치와 서식은 바꾸지 않는다.
## 검수
- [ ] 합계 = 항목 합
- [ ] 할인율 ≤ 규정 상한
- [ ] 납기는 영업일 기준
- [ ] 고객명·담당자·유효기간 기재
마지막 단계로 반드시 `python scripts/validate_quote.py output.xlsx` 를 실행한다. 통과하지 못하면 전달하지 않고 실패 항목을 고친다.
Anthropic 가이드가 권하는 순서는 평가가 먼저입니다. 스킬 없이 대표 과제를 세 번 시켜 실패를 적고, 그 빈틈을 메울 최소한의 지시만 쓴 뒤 다시 돌려 비교합니다. 스킬 초안 작성과 호출 정확도 점검에는 공식 플러그인 skill-creator(/plugin install skill-creator@claude-plugins-official, 2026년 8월 글 기준)를 쓸 수 있습니다.
공개 수치 다시 보기
코어닷투데이가 직접 잰 값이 아니라, 원 글이 공개 자료에서 확인한 숫자입니다(글 작성 시점, 2026년 9월 기준).
- 생태계.
anthropics/skills저장소는 2026-09-19 기준 별 177.1k, 포크 21.0k. agentskills.io 쇼케이스에는 Cursor·OpenAI Codex·Gemini CLI·VS Code·GitHub Copilot·JetBrains Junie 등 40여 제품이 올라 있습니다. 발표 영상은 조회수 150만 회를 넘었습니다. - Claude Code 세부(2026년 9월 문서 기준). 설명문은 스킬 목록에서 1,536자에서 잘립니다. 대화가 자동 압축될 때 스킬별 최근 호출분은 5,000토큰까지, 전체 25,000토큰 한도 안에서 다시 붙습니다.
disable-model-invocation: true로 배포 같은 위험한 스킬을 사용자 전용으로 잠그고,context: fork로 별도 서브에이전트에서 돌릴 수 있습니다. - 공급망(Snyk ToxicSkills, 2026-02-05). ClawHub·skills.sh의 스킬 3,984개 중 36.8%(1,467개)에 결함 1개 이상, 13.4%(534개)가 심각 등급, 76개가 악성으로 확인됐고 ClawHub 스킬의 10.9%에 비밀 키가 박혀 있었습니다. 확인된 악성 스킬의 100%가 악성 코드를, 91%가 동시에 프롬프트 주입을 썼습니다.
언제 쓰고, 언제 피하나
| 특징 | 스킬이 맞는다 | 다른 방법이 낫다 |
|---|---|---|
| 반복성 | 같은 절차가 주 1회 이상 반복된다 | 한 번뿐인 작업 |
| 절차 | 순서와 완료 기준을 글로 쓸 수 있다 | '감'으로 하는 판단이 대부분 |
| 계산 | 결정론적 계산이 섞여 있다(스크립트로 고정) | 계산 없이 전부 판단 |
| 변경 빈도 | 규정·단가가 가끔 바뀐다(파일 하나 수정) | 매일 바뀌는 사실 정보 — 메모리·RAG |
| 외부 시스템 | 파일 중심이거나 MCP로 이미 연결됨 | 새 시스템 연결 자체가 과제 — MCP 서버 먼저 |
| 실수의 대가 | 검수 단계로 잡을 수 있다 | 되돌릴 수 없고 검수 불가 — 사람이 직접 |
스킬의 진짜 강점은 성능보다 운영입니다. 고치는 사람이 엔지니어가 아니라 업무 담당자이고, 할인 규정이 바뀌면 references/ 파일 하나만 고칩니다. 발표에서도 재무·채용·회계·법무 같은 비기술 직군이 스킬을 만들기 시작한 것을 가장 흥미로운 관찰로 꼽았습니다. 스킬은 '이 고객은 결제가 느리다' 같은 사실(메모리)이 아니라 '보내기 전에 할인 상한을 확인한다' 같은 절차만 담습니다.
한계와 주의
- 성능 우위를 보인 통제된 공개 벤치마크는 없습니다. Anthropic 가이드조차 "이 평가를 돌리는 내장 방법은 없다"고 적었고, 발표자들도 테스트·평가, 버전과 계보, 다른 스킬·MCP 서버에 대한 명시적 의존성을 "다음 과제"로 꼽았습니다. 스킬끼리 의존·충돌하는 조합 문제는 아직 사양 밖입니다.
- 런타임에 파일 시스템과 코드 실행이 필요합니다. 원격 실행 환경(최소 Python)과 로컬(시스템 전체 접근)의 차이가 커서 스킬을 그대로 옮기기 어렵다는 첫 사용기(톰 맥라이트, 2025-10-20)가 있었습니다. 그는 파일을
.claude/skills/ast-grep.md에 만들거나 필수 프론트매터를 빠뜨리는 실수도 보고했습니다. 정답은<name>/SKILL.md입니다. - 사양 필드는 여섯 개뿐입니다.
disable-model-invocation·context같은 필드는 Claude Code 확장이라 다른 클라이언트에서는 무시될 수 있고,allowed-tools는 실험적입니다. - 스킬 하나가 지시와 코드를 함께 실어 옵니다. 외부 스킬은 npm 패키지처럼 출처를 정하고, 읽어 보고, 버전을 고정합니다. 단 ToxicSkills 수치는 OpenClaw 커뮤니티 등록소 위주이며 Anthropic 공식 스킬이나 사내 스킬의 상태가 아닙니다. 다른 연구(arXiv 2604.02837, 42,447개 중 26.1% 취약)와 숫자를 섞지 않습니다.
- 숫자의 성격을 구분합니다. 7% 계산과 스택 비교 위젯의 구성 요소 개수는 설명용 가정입니다. 발표 날짜 2025-11-20은 행사 일정과 "출시 5주 뒤"라는 발언에서 추정한 값입니다.
anthropics/skills도 전부 Apache 2.0이 아니라 문서 스킬은 소스 공개(source-available)입니다. - 시간에 민감한 정보는 스킬에 넣지 않습니다. 참조는 SKILL.md에서 한 단계만 깊게 둡니다. 더 깊은 파일은
head -100처럼 앞부분만 읽혀 정보가 빠질 수 있고, 100줄 넘는 참고 파일은 맨 위에 목차를 둡니다. - 사이먼 윌리슨의 "MCP보다 큰 일일지도"(출시 당일)는 단순함에 대한 평가였지 대체론이 아닙니다. 발표자들도 스킬이 MCP를 보완한다고 말했습니다.
