SKILL.md 완전 해부: 에이전트 스킬 6개 필드로 AI에게 회사의 절차를 가르치는 법

2026-09-01 · AI & 바이브코딩

💡 3줄 요약

- 에이전트 스킬(Agent Skills)은 지시문·스크립트·리소스를 담은 폴더를 AI가 필요할 때만 읽게 하는 공개 표준이며, 핵심은 폴더 안의 SKILL.md 파일 하나입니다.

- 표준이 정의하는 frontmatter 필드는 필수 2개(name, description)와 선택 4개(license, compatibility, metadata, allowed-tools)로 모두 6개뿐이고, 이 6개를 벗어나면 이식성이 깨집니다.

- 스킬 디렉터리 SkillMD.ai에는 2026년 8월 31일 확인 기준 111,562개 이상의 스킬이 등록돼 있습니다.

■ 1. 프롬프트를 매번 다시 쓰는 문제

같은 지시를 매번 다시 입력해 본 사람은 문제를 압니다. 보고서 양식, 코드 리뷰 기준, 사내 용어 정리, 배포 순서 같은 것은 대화가 바뀔 때마다 처음부터 설명해야 합니다. 이 반복을 없애기 위해 나온 것이 에이전트 스킬입니다.

공식 정의는 간결합니다. 에이전트 스킬은 "AI 에이전트의 능력을 전문 지식과 워크플로로 확장하는 경량 오픈 포맷"이며, 실체는 "SKILL.md 파일을 담은 폴더"입니다. 앤트로픽(Anthropic)은 이를 "전문성을 패키징하는 맞춤 온보딩 자료"라고 설명합니다. 새로 온 직원에게 건네는 업무 인수인계 문서를 AI에게 주는 셈입니다.

중요한 점은 이것이 한 회사의 사유 규격이 아니라는 것입니다. 포맷은 앤트로픽이 개발했지만 공개 표준으로 내놨고, 표준 자체는 외부 기여에 열려 있습니다. 공식 문서: https://agentskills.io/

■ 2. 폴더 구조 — 필수는 파일 하나뿐

표준이 정의하는 디렉터리 구조는 다음과 같습니다.

세 하위 디렉터리는 모두 선택입니다. 그 외 임의 파일도 허용됩니다. 즉 가장 단순한 스킬은 마크다운 파일 하나입니다.

■ 3. frontmatter는 정확히 6개 필드다

여기가 실무에서 가장 자주 어긋나는 지점입니다. 표준이 정의하는 frontmatter 필드는 전부 6개입니다.

■ 자주 하는 실수: description을 한 줄 제목처럼 쓰는 것

description은 사람이 읽는 요약이 아니라 AI가 이 스킬을 쓸지 말지 판단하는 유일한 근거입니다. 뒤에 나올 점진적 공개 구조 때문에, 평소 AI가 보는 것은 name과 description뿐입니다. "코드 리뷰용"이라고만 적으면 언제 발동해야 하는지 알 수 없습니다. "파이썬 서비스의 PR을 리뷰할 때. 예외 처리 누락과 N+1 쿼리를 우선 확인한다"처럼 쓰는 조건까지 적어야 합니다.

■ 4. 점진적 공개 — 왜 컨텍스트가 터지지 않는가

스킬을 수십 개 등록해도 대화가 무거워지지 않는 이유는 3단계 점진적 공개(progressive disclosure) 때문입니다.

1) 발견(Discovery): 시작 시점에 각 스킬의 name과 description만 로드합니다. 스킬당 약 100토큰입니다.

2) 활성화(Activation): 작업이 맞아떨어지면 그때 SKILL.md 본문 전체를 로드합니다. 본문은 5,000토큰 미만, 500줄 이하가 권장입니다.

3) 실행(Execution): scripts, references, assets 안의 파일은 실제로 필요할 때만 읽습니다.

스킬 100개를 등록해도 평소 소비는 1만 토큰 안팎이고, 실제로 쓰는 한두 개만 펼쳐집니다. 이 설계가 스킬을 "많이 만들어도 되는 것"으로 만듭니다.

검증 도구도 있습니다. 공식 레퍼런스 라이브러리 skills-ref로 `skills-ref validate ./my-skill`을 실행하면 규격 위반을 잡아줍니다.

■ 5. 확장 필드의 함정 — 이식성이 깨지는 지점

클로드 코드(Claude Code)는 표준을 확장합니다. 공식 문서 표현대로 "Claude Code는 Agent Skills 공개 표준을 따르되, 호출 제어·서브에이전트 실행·동적 컨텍스트 주입 같은 기능으로 표준을 확장"합니다. 확장 필드에는 when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, disallowed-tools, model, effort, context, agent, background, hooks, paths, shell 등이 있습니다.

문제는 이 필드를 쓴 스킬을 다른 경로로 옮길 때 생깁니다. 실제 오류 메시지는 이렇습니다.

```

Unexpected key(s) in SKILL.md frontmatter: argument-hint.

Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

```

■ 유의사항

여러 도구에서 돌려 쓸 스킬이라면 표준 6개 필드만 쓰십시오. 특정 제품에서만 쓸 스킬이라면 확장 필드가 훨씬 편리합니다. 처음부터 둘 중 무엇인지 정해놓고 만드는 편이 나중에 옮기느라 고생하는 것보다 낫습니다.

참고로 클로드 코드에서는 커스텀 커맨드가 스킬로 통합됐습니다. `.claude/commands/deploy.md`와 `.claude/skills/deploy/SKILL.md`는 둘 다 `/deploy`를 만듭니다.

■ 6. 어디까지 퍼졌나 — 채택 현황

이 포맷을 지원한다고 공식 쇼케이스에 등재된 클라이언트는 앤트로픽 제품 밖으로 넓게 퍼져 있습니다.

- 앤트로픽 제품: 클로드 앱(Pro·Max·Team·Enterprise), Claude Developer Platform(Messages API 및 /v1/skills 엔드포인트), 클로드 코드

- 타사 제품: Gemini CLI, Cursor, GitHub Copilot, VS Code, ChatGPT & Codex, OpenCode, OpenHands, Goose(Block), Amp, JetBrains Junie, Roo Code, Kiro, Factory, Letta, Databricks Genie Code, Snowflake Cortex Code, Spring AI, Laravel Boost, Tabnine, Mistral AI Vibe, Pulumi Neo

API 경로에서 스킬을 쓸 때는 조건이 하나 붙습니다. 코드 실행 도구(code execution tool)를 런타임 컨테이너로 요구합니다. scripts/를 실제로 돌려야 하기 때문입니다.

■ 7. SkillMD.ai — 11만 개의 스킬이 모인 곳

직접 만들기 전에 남이 만든 것을 보는 편이 빠릅니다. SkillMD.ai는 "클로드·커서를 비롯한 AI 코딩 어시스턴트에서 쓰는 SKILL.md 파일의 공개 디렉터리이자 제작 작업공간"을 표방합니다.

자연어 설명만 넣으면 SKILL.md 초안을 만들어 주는 기능도 제공합니다. 주소는 https://skillmd.ai/ 입니다.

■ 유의사항: 남의 스킬을 그대로 쓰기 전에

스킬은 AI에게 "이 순서로 하라"고 지시하는 문서입니다. scripts/ 안에 실행 코드가 들어 있을 수도 있습니다. 출처가 불분명한 스킬을 검토 없이 설치하는 것은 출처 불명의 스크립트를 실행하는 것과 성격이 같습니다. 최소한 SKILL.md 본문과 scripts/ 내용은 직접 읽고 넣으십시오.

■ 8. 실제로 만들 때의 순서

1) 반복되는 작업 하나를 고릅니다. 이번 주에 같은 설명을 두 번 이상 한 것이면 후보입니다.

2) 그 작업을 사람에게 인수인계한다고 생각하고 순서를 적습니다. 판단 기준과 예외 처리를 빼지 마십시오. AI가 막히는 지점은 대개 거기입니다.

3) description에 "언제 쓰는가"를 반드시 넣습니다.

4) 본문이 500줄을 넘어가면 references/로 분리합니다. 본문은 판단에 필요한 것만 남기고, 참조표·예시 모음은 밖으로 빼는 편이 활성화 비용을 낮춥니다.

5) skills-ref로 검증하고, 실제 작업에서 발동하는지 확인합니다. 발동하지 않으면 십중팔구 description 문제입니다.

■ 9. 정리

에이전트 스킬은 새로운 기술이라기보다 정리 습관을 파일 포맷으로 만든 것에 가깝습니다. 어려운 부분은 마크다운 문법이 아니라, 머릿속에 있던 절차를 남이 읽고 따라 할 수 있게 적어내는 일입니다. 그 일을 한 번 해두면 사람에게도 AI에게도 같은 문서를 쓸 수 있습니다.

■ 참고 자료 및 출처

Agent Skills 공식 사이트 및 사양

https://agentskills.io/

Agent Skills 사양 문서

https://agentskills.io/specification

Anthropic, Introducing Agent Skills

https://www.anthropic.com/news/skills

Anthropic 엔지니어링 블로그(2025-10-16)

https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

Claude Developer Platform 스킬 개요

https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

Claude Code 스킬 문서

https://code.claude.com/docs/en/skills

SkillMD.ai

https://skillmd.ai/

본문의 필드 제약, 토큰 권장치, 채택 제품 목록, 스킬 등록 수는 모두 위 1차 출처에서 2026년 8월 31일에 확인한 값입니다. 표준 사양은 갱신될 수 있으므로 실제 적용 전 공식 문서를 다시 확인하시기 바랍니다.