[Agent Skills 완전정복 #2] SKILL.md 규격, 한 장으로 끝내기

Agent Skills 공식 문서를 한 장씩 정리하는 시리즈, 두 번째 편입니다.
이번엔 스킬을 "규격에 맞게" 만드는 데 필요한 SKILL.md 포맷 규칙을 한 번에 정리합니다.

결론부터 말하면, 꼭 알아야 할 건 딱 두 가지예요 — 이름(name)과 설명(description). 나머지는 전부 선택입니다.

---

📁 1. 디렉토리 구조

스킬은 SKILL.md 파일이 든 폴더입니다. 그 외는 모두 선택이에요.

skill-name/          # 폴더 이름 = name 필드와 반드시 일치!
├── SKILL.md          # 필수: 메타데이터 + 지침
├── scripts/          # 선택: 실행 코드
├── references/       # 선택: 필요할 때 읽는 상세 문서
└── assets/           # 선택: 템플릿·이미지·데이터

---

📝 2. SKILL.md = 머리말(YAML) + 본문(Markdown)

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

여기부터는 마크다운 본문 — 에이전트가 따를 실제 지침을 적습니다.

---

🧾 3. Frontmatter 필드 총정리

필드	필수	핵심 제약
name	✅	최대 64자 · 소문자/숫자/하이픈만 · 하이픈 시작·끝 ❌ · 연속 하이픈 ❌ · 폴더명과 일치
description	✅	최대 1024자 · 빈 값 ❌ · "무엇을 + 언제 쓰는지" 둘 다
license	❌	라이선스 이름 또는 번들 파일 참조
compatibility	❌	최대 500자 · 환경 요구사항(제품·패키지·네트워크)
metadata	❌	임의의 key-value (author, version 등)
allowed-tools	❌	미리 승인할 도구 목록 (실험적)

name 규칙 예시

• ✅ pdf-processing   ✅ data-analysis
• ❌ PDF-Processing (대문자)   ❌ -pdf (하이픈 시작)   ❌ pdf--processing (연속 하이픈)

description — 가장 중요한 필드 🔑

이게 좋아야 에이전트가 제때 스킬을 호출합니다. (자세한 건 #5편에서 다룹니다.)

좋은 예: "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction." → 무엇을 + 언제 + 트리거 키워드 포함
나쁜 예: "Helps with PDFs." → 너무 모호함

---

📂 4. 선택 디렉토리

• scripts/ — 실행 코드. 자체 완결적이거나 의존성 명시, 친절한 에러 메시지
• references/ — 필요할 때만 읽는 상세 문서(예: REFERENCE.md). 작게 쪼갤수록 컨텍스트 절약
• assets/ — 템플릿, 이미지, 데이터 파일(스키마·룩업표)

---

🎯 5. 핵심 철학 — 점진적 로딩(Progressive Disclosure)

스킬은 3단계로 나눠 필요한 만큼만 로드됩니다. 토큰 예산이 이 구조의 이유예요.

단계	로드 대상	크기 / 시점
1. Metadata	name + description	~100토큰 / 시작 시 모든 스킬
2. Instructions	SKILL.md 본문	<5000토큰 권장 / 활성화 시
3. Resources	scripts·references·assets	필요 시만 / 실제 사용 시

규칙: SKILL.md는 500줄 이하로 유지하고, 상세 내용은 references/로 빼라.

---

🔗 6. 파일 참조 & 검증

참조는 스킬 루트 기준 상대경로, 한 단계 깊이만 사용합니다.

See [the reference guide](references/REFERENCE.md) for details.

규격 검증은 공식 도구로:

skills-ref validate ./my-skill

---

✍️ 마무리

규격은 단순합니다. name·description만 제대로 쓰면 절반은 끝이에요. 무겁고 상세한 건 전부 references/·scripts/·assets/로 빼서 필요할 때만 로드되게 하면 됩니다.

👉 다음 편 → [#3] 내 첫 스킬 만들기 (주사위 굴리기 따라하기)

---

📎 출처: 이 글은 Agent Skills 공식 문서 — Specification (© Anthropic, CC BY 4.0)를 한국어로 번역·재구성한 것입니다.

---