앤스로픽이 SKILL.md 표준의 이름까지 넘겼다

effidev·2026년 10월 23일

클로드 코드나 코덱스, 커서에 같은 부탁을 할 때마다 “우리 팀은 커밋 메시지를 이렇게 쓴다”, “배포는 이 순서로 한다” 같은 설명을 다시 붙여 넣고 있다면 이 글이 맞는 사람에게 쓴 글이다. 그 설명을 폴더 하나에 적어 두고, AI가 필요할 때만 꺼내 읽게 하는 방식이 **스킬(Agent Skills)**이다. 2026년 10월 22일 앤스로픽이 이 SKILL.md 표준의 이름과 로고, 깃허브 조직, 도메인(agentskills.io)을 리눅스 재단 산하의 에이전트 재단에 통째로 넘겼다.

숫자부터 크다. 앤스로픽은 같은 글에서 지금까지 스킬이 100만 개 공개됐고 설치는 2억 8천만 번에 가깝다고 밝혔다. 챗GPT, 커서, 깃허브 코파일럿, VS Code를 포함해 70곳이 넘는 에이전트 제품이 이 형식을 지원한다는 말도 있다. 경쟁사 제품이 이미 쓰는 형식을 만든 회사가 소유권을 내려놓은 셈이다.

이 글은 다섯 가지를 순서대로 다룬다. 스킬이 정확히 무엇인지, 이번에 무엇이 바뀌고 무엇이 그대로인지, MCP·AGENTS.md와 어떻게 다른지, 퀵스타트의 20줄짜리 스킬을 클로드 코드에서 실제로 돌려 본 결과, 공식 검증기에 스킬 열다섯 가지를 넣어 본 결과다. 근거는 앤스로픽 공식 글, agentskills.io의 명세·퀵스타트·모범 사례 문서, 클로드 코드와 코덱스 공식 문서, 리눅스 재단 보도자료와 재단 사이트, 깃허브 공개 조회, 그리고 이 맥에서 10월 23일 아침에 직접 돌린 시험이다.

SKILL.md 표준의 정체: 폴더 하나와 파일 하나

에이전트는 AI가 스스로 도구를 써 가며 일을 해내는 프로그램이다. 클로드 코드, 코덱스, 커서의 에이전트 모드가 여기에 든다. 이런 에이전트는 일반적인 일은 잘하지만 “우리 회사 데이터베이스는 삭제를 지우기 표시로 처리한다” 같은 우리 쪽 절차는 모른다. 앤스로픽은 클로드 코드를 만들며 바로 이 빈틈을 봤다고 적었다. 일반 지식 작업은 잘 다루는데, 실제 업무에 필요한 절차 지식이 모자랐다는 것이다.

스킬은 그 빈틈을 메우는 폴더다. 명세(agentskills.io)가 정한 모양은 이렇다.

my-skill/
├── SKILL.md          # 필수: 설정 + 지시문
├── scripts/          # 선택: 실행할 코드
├── references/       # 선택: 참고 문서
└── assets/           # 선택: 템플릿, 데이터

SKILL.md는 위쪽의 설정 칸(프런트매터, 파일 맨 위 --- 두 줄 사이에 적는 이름표)과 아래쪽의 지시문으로 이뤄진다. 이름표에는 최소한 name과 description이 들어간다. 퀵스타트에 나오는 가장 작은 스킬은 이렇게 생겼다.

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use the following command that generates a random number from 1
to the given number of sides:

echo $((RANDOM % <sides> + 1))

Replace `<sides>` with the number of sides on the die (e.g., 6 for a standard
die, 20 for a d20).

name은 폴더 이름과 같아야 하고, description은 “무엇을 하는지”와 “언제 쓰는지”를 함께 적는 칸이다. 지시문은 자유롭게 쓴다. 퀵스타트의 표현으로 파일 하나, 20줄 미만이다.

에이전트는 스킬을 세 번에 나눠 읽는다

스킬을 수십 개 깔아도 AI가 매번 전부 읽는 건 아니다. 명세는 점진적 공개(필요한 만큼만 단계적으로 펼치는 방식)를 권한다.

토큰은 AI가 글을 읽는 단위다(대략 단어 조각 하나). 여기서 중요한 건 평소의 부담이 이름과 설명뿐이라는 점이다. 스킬이 많아져도 AI가 한 번에 들고 있는 작업 메모(컨텍스트)가 바로 차지 않는다.

반대로 이 구조는 description이 모든 짐을 진다는 뜻이다. 공식 문서도 그렇게 말한다. 설명이 부실하면 스킬이 있어도 켜지지 않고, 너무 넓으면 엉뚱한 때 켜진다. 설명서가 권하는 방식은 세 가지다. “이 스킬은 ~한다”가 아니라 “~할 때 이 스킬을 써라”처럼 명령형으로 쓴다. 구현 방식이 아니라 사용자가 하려는 일을 적는다. 사용자가 분야 이름을 직접 말하지 않는 경우까지 적는다.

문서에는 한 가지 단서도 붙어 있다. 에이전트는 혼자 처리할 수 있는 단순한 한 단계 부탁에는 스킬을 안 찾을 수 있다는 것이다. “이 PDF 읽어 줘”에 PDF 스킬이 안 켜질 수 있다. 클로드 코드는 설명 길이를 따로 제한한다. 표준은 설명을 1,024자까지 허용하지만, 클로드 코드 문서에 따르면 description과 when_to_use를 합친 글은 스킬 목록에서 1,536자에서 잘린다. 핵심 사용처를 앞에 쓰라는 이유다.

이번 발표의 숫자와 그 숫자의 주인

숫자는 누가 어떻게 얻었는지에 따라 무게가 다르다. 발표문에서 가져온 것과 내가 직접 조회한 것을 나눠 적는다.

별과 포크는 관심의 지표이지 쓰는 사람의 수가 아니다. 그리고 100만 개와 2억 8천만 번은 앤스로픽이 센 값이다. 발표문에는 “설치”를 어디서 어떻게 센 것인지 정의가 없다. 그러니 이 숫자는 “이 형식이 작은 실험 단계를 한참 넘었다”는 신호로 읽는 정도가 안전하다. 같은 조회에서 눈에 띈 점도 하나 있다. 표준 문서 저장소의 마지막 푸시는 8월 9일이다. 명세 문서가 한동안 크게 바뀌지 않았다는 뜻으로 읽을 수 있고, 내가 읽은 명세 페이지에는 버전 표기가 없었다.

넘긴 것, 그대로 두는 것, 앞으로 정할 것

발표문이 적은 내용을 세 갈래로 나눴다.

넘긴 것: Agent Skills라는 이름과 로고, 깃허브 조직, agentskills.io 도메인.

그대로인 것: SKILL.md 표준을 쓰거나 기여하려고 재단(AAIF)에 가입할 필요는 없다. 관리는 앤스로픽, 구글, 오픈AI를 비롯한 여러 회사의 엔지니어가 개인 자격으로 맡는다. 리드 메인테이너(핵심 관리자)는 데이비드 소리아 파라(David Soria Parra)와 마헤시 무라그(Mahesh Murag) 두 사람이다.

앞으로 정할 것: 앤스로픽이 제안한 로드맵은 세 가지다. 버전이 붙은 릴리스, 정식 제안 절차, 스킬을 만들고 설치하는 사람을 위한 보안 안내.

AAIF는 리눅스 재단 산하 재단이다. 2025년 12월 9일 출범했고, 첫 프로젝트는 앤스로픽의 MCP, 블록의 goose, 오픈AI의 AGENTS.md였다. 출범 당시 플래티넘 회원은 아마존 웹 서비스, 앤스로픽, 블록, 블룸버그, 클라우드플레어, 구글, 마이크로소프트, 오픈AI 여덟 곳이었다. 10월 23일 아침 AAIF 프로젝트 페이지에는 Agent Skills를 포함해 프로젝트 열 개가 올라 있었다. 앤스로픽이 밝힌 이유는 스킬을 “열려 있고, 커뮤니티가 이끌며, 한 회사에 묶이지 않게” 유지하려는 것이다. 발표문에는 그 이상의 동기가 없고, 이 글도 추측하지 않는다.

같은 재단 식구 셋은 무엇이 다른가

AAIF 이야기가 나오면 MCP, AGENTS.md, Agent Skills가 한 묶음으로 언급된다. 셋은 서로 다른 일을 한다. 각 프로젝트의 공식 소개를 한 줄씩 옮기고, 아래 비유는 내가 붙인 것이다.

내 기준은 단순하다. AI가 외부 서비스나 데이터에 접속해야 하면 MCP, 프로젝트 전체에 늘 적용할 규칙이면 AGENTS.md, 특정 작업을 할 때만 펼칠 절차면 스킬이다. 셋은 경쟁이 아니라 겹쳐 쓰는 층이다. MCP 쪽의 최근 변화는 MCP 2026-07-28 스펙: 세션이 사라졌다에서 코드 수준으로 다뤘다.

퀵스타트 스킬을 클로드 코드에 시켜 봤다

위의 roll-dice 스킬을 그대로 .claude/skills/roll-dice/SKILL.md에 두고, 임시 폴더에서 클로드 코드(2.1.303)를 비대화형으로 한 번 돌렸다. 부탁은 한국어로 “주사위 d20 한 번 굴려 줘”였고, 스킬의 설명은 영어 그대로다. 출력에서 읽은 순서는 이렇다.

1. 시작 정보의 스킬 목록에 roll-dice가 들어 있었다.
2. 모델이 Skill 도구를 roll-dice와 인자 d20으로 불렀다.
3. 도구 결과는 “Launching skill: roll-dice”였다.
4. 이어서 echo $((RANDOM % 20 + 1))을 실행했고 결과는 17이었다.
5. 최종 답은 “d20을 굴려서 17이 나왔어요”였고, 4턴, 출력에 찍힌 추정 비용은 0.129달러였다.

한국어 부탁이 영어 설명과 이어졌다는 점이 이 시험에서 가장 쓸모 있는 관찰이다. 설명을 영어로 쓰든 한국어로 쓰든 에이전트는 뜻으로 맞춘다. 다만 한 번 돌려 본 결과일 뿐이다. 켜지는 비율은 재 보지 않았고, 퀵스타트도 도구 사용 성공률이 모델마다 다르다고 경고한다.

폴더를 어디에 두느냐는 도구마다 다르다. 공식 문서에서 확인한 위치만 적는다.

클로드 코드는 예전 커스텀 명령(.claude/commands/)을 스킬로 합쳤다. 두 방식이 같은 /이름 명령을 만들고 기존 파일도 계속 동작한다. 클로드 코드 쪽 작업 방식은 Claude Code CLI 팀 자동화에서 다뤘다.

공식 검증기에 열다섯 가지를 넣어 봤다

명세 저장소에는 참조 검증기 skills-ref(0.1.0)가 들어 있다. 이 맥의 새 가상환경에서 깃허브의 소스를 내려받아 돌렸다. 가상환경에 따로 설치한 것은 strictyaml 1.7.3과 click 8.5.0 두 가지다. 임시 폴더에 스킬 폴더를 만들고 validate를 부른 결과다.

여기서 나온 사실 넷을 정리한다. 첫째, 이름 규칙은 말만이 아니라 실제로 걸린다. 둘째, 설명 한도 1,024는 글자 수다. 한글 1,024자는 통과했고 1,025자에서 걸렸으니 바이트가 아니다. 셋째, 명세 문장은 이름을 “소문자 영숫자(a-z, 0-9)와 하이픈”이라고 적는데 검증기는 한글 이름을 받았다. 코드가 유니코드 글자를 허용하기 때문이다. 어느 도구에서나 돌아가게 하려면 영문 소문자가 안전하다. 넷째, 소문자 skill.md도 통과하지만 명세의 이름은 SKILL.md다. 대문자로 쓰는 쪽이 문서와 맞는다.

클로드 코드에서 되던 설정이 다른 곳에서 막히는 경우

열 번째와 열한 번째 시험이 이 글에서 가장 실용적인 부분이다. 명세가 허용하는 프런트매터는 name, description, license, compatibility, metadata, allowed-tools 여섯 개다. 그런데 클로드 코드는 훨씬 많은 필드를 받는다. 공식 문서 표에는 disable-model-invocation, argument-hint, context, hooks, paths처럼 표준 밖 필드가 줄줄이 있고, 클로드 코드는 모르는 필드를 오류 없이 무시한다.

문제는 그 스킬을 밖으로 내보낼 때다. 클로드 코드 문서에 따르면 claude.ai 업로드, 스킬 API, 앤스로픽 저장소의 package_skill.py로 묶을 때는 여섯 필드만 허용되고, 그 밖의 필드가 있으면 무시하지 않고 하드 오류가 난다. 문서에 실린 오류 메시지는 이렇다.

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

참조 검증기도 같은 방향이었다. 10번과 13번, 따옴표를 씌운 argument-hint는 모두 “허용되지 않은 필드”로 걸렸다. 같은 값을 metadata: 아래로 옮기면 통과했다. 다만 거기엔 대가가 있다. 클로드 코드 문서는 metadata 안의 내용을 클로드 코드가 해석하지 않는다고 적는다. 통과시키려고 옮기면 그 설정은 클로드 코드에서도 힘을 잃는다.

11번은 필드가 아니라 YAML 문법 때문에 걸렸다. 검증기가 쓰는 strictyaml이 [issue-number] 같은 대괄호 목록을 “허용되지 않는 JSON식 표기”라며 거부했고, 따옴표로 감싸니 해석 오류는 사라졌다. 정리하면 이렇다. 클로드 코드 안에서만 쓸 스킬이면 확장 필드를 써도 된다. 다른 도구나 claude.ai, API로 옮길 스킬이면 여섯 필드로 제한하고 올리기 전에 검증기를 돌리는 편이 낫다.

설치하는 쪽이 알아야 할 것: 스킬은 글이 아니라 실행 가능한 묶음이다

스킬 폴더에는 scripts/가 들어갈 수 있다. 명세는 이 폴더를 “에이전트가 실행할 수 있는 코드”라고 설명하고, 파이썬·배시·자바스크립트가 흔하다고 적는다. allowed-tools 필드는 스킬이 미리 허락받은 도구 목록이고 명세는 이것을 실험 단계라고 밝힌다. 남이 만든 스킬을 깔면 글만 들이는 게 아니라 에이전트에게 읽히고 실행될 수 있는 묶음을 들이는 것이다.

앤스로픽의 로드맵에 “스킬을 쓰고 설치하는 사람을 위한 보안 안내”가 들어간 것은 그 구조를 의식한 선택으로 읽힌다. 다만 내가 읽은 명세 페이지에는 보안 절이 없었다. 스킬 묶음을 통한 실제 침해 사례는 이 글을 쓰며 찾아보지 않았다. 아래는 구조에서 나온 추론이고, 사고 보고가 아니다.

• 설치 전에 폴더를 열어 SKILL.md와 scripts/ 안의 파일을 직접 읽는다.
• allowed-tools가 미리 허락하는 도구가 무엇인지 본다.
• 만든 사람이 누구인지, 어디서 받았는지 확인한다. 별 개수는 안전 보증이 아니다.
• 처음 써 볼 때는 중요한 프로젝트가 아니라 임시 폴더에서 돌린다.

에이전트가 읽는 글이 곧 지시가 될 수 있다는 문제는 오토 모드 0.00%, 실제 공격은 80% 뚫렸다에서 외부 평가 숫자로 다뤘다. 스킬도 같은 맥락에서 읽어야 한다.

오늘 해 볼 일 넷

1. 최근 일주일 동안 AI에게 붙여 넣은 설명 중 세 번 넘게 반복한 것을 하나 고른다. 커밋 메시지 규칙, 배포 순서, 코드 리뷰 체크 항목 같은 것이다.
2. .claude/skills/<이름>/SKILL.md(코덱스·VS Code라면 .agents/skills/<이름>/SKILL.md)에 20줄 안팎으로 옮긴다. name은 폴더 이름과 똑같이, description은 “무엇을 한다 + 언제 쓴다(Use when …)” 두 가지를 모두 적는다.
3. 에이전트가 이미 아는 설명은 지운다. 공식 모범 사례도 “에이전트가 모르는 것만 써라”고 한다. 가장 가치 있는 부분으로는 에이전트가 반복해서 틀리는 지점을 모은 **함정 절(Gotchas)**을 꼽는다. 고쳐 줘야 했던 실수는 그 절에 한 줄씩 더하면 된다.
4. 다른 도구와 나눌 스킬이라면 프런트매터를 여섯 필드로 제한하고 skills-ref validate ./my-skill을 돌려 본다.

내가 잰 것, 발표문에 기댄 것, 못 본 것

직접 확인한 것: 깃허브 공개 조회의 별·포크·생성일·마지막 푸시(10월 23일), 참조 검증기에 넣은 열다섯 가지 시험, 클로드 코드 2.1.303에서 roll-dice를 한 번 돌린 결과, 명세·퀵스타트·모범 사례·클로드 코드 문서·코덱스 문서의 문장 대조, AAIF 사이트의 프로젝트 목록과 리눅스 재단 보도자료.

발표문에 기댄 것: 70곳 이상, 100만 개, 2억 8천만 번, 메인테이너 구성, 로드맵 세 가지, 앤스로픽이 밝힌 이유. 모두 앤스로픽 공식 글의 문장이다.

못 본 것: 지원 제품 전체 목록(agentskills.io의 클라이언트 쇼케이스는 화면에서 불러오는 방식이라 내려받은 문서에 목록이 비어 있었다), 클로드 코드 밖의 도구에서 같은 스킬이 켜지는지, 설명이 한국어일 때와 영어일 때의 활성화 비율, 스킬 묶음을 통한 침해 사례.