Anthropic Skills 공식 레포 완벽 분석 (2026): SKILL.md부터 첫 호출까지

"Claude한테 매번 같은 가이드를 붙여넣는 게 지긋지긋한데, Skills로 한 번에 끝낼 수 있다는 게 사실일까?"

📌 핵심 3줄 요약

• anthropic skills는 Claude가 필요할 때만 자동으로 불러오는 모듈형 지시서다 — 매 대화에 프롬프트를 통째로 끼워 넣지 않아도 된다.
• 공식 레포 anthropics/skills는 SKILL.md 한 장 + 보조 파일 구조이며, 폴더 하나가 곧 스킬 하나다.
• MCP가 "외부 도구 호출 규격"이라면 Skills는 "Claude의 작업 절차서"라서 역할이 겹치지 않고 함께 쓰인다.

1. Skills가 등장한 이유와 누가 읽어야 하나

2025년 후반부터 Claude를 업무에 붙이는 팀이 늘면서, 매 세션마다 동일한 사내 가이드·코드 스타일·금지어 목록을 시스템 프롬프트에 통째로 욱여넣는 패턴이 자리 잡았다. 토큰은 매번 누적되고, 가이드를 고치면 모든 자동화 스크립트를 같이 바꿔야 했다. Anthropic이 2025년 10월에 공개한 Agent Skills는 이 문제를 정면으로 겨냥한다.

핵심 아이디어는 간단하다. "스킬"이라는 작은 폴더를 미리 등록해 두면, Claude가 사용자 요청을 보고 "지금 이 스킬이 필요하다"고 판단했을 때만 해당 폴더의 SKILL.md를 읽어 들인다. 평소엔 메타데이터(이름·설명)만 메모리에 떠 있으니, 가이드가 50개여도 컨텍스트는 무겁지 않다.

이 글은 다음 독자를 위한 1차 데이터 가이드다.

• Claude Code·Claude Desktop에 사내 워크플로를 붙이려는 백엔드/플랫폼 엔지니어
• Custom GPT처럼 "재사용 가능한 Claude 모듈"을 만들어 두고 싶은 1인 개발자
• MCP·Subagent·Skills의 역할 차이가 헷갈리는 AI 도입 담당자

2. anthropics/skills 레포는 어떻게 생겼나

필자가 직접 git clone https://github.com/anthropics/skills를 받아 폴더를 열어 보니, 구조는 의외로 평평했다. 루트 바로 아래에 카테고리별 디렉터리가 있고, 각 디렉터리 안에 "스킬 하나 = 폴더 하나" 규칙으로 정리돼 있다.

skills/
├── README.md
├── document-skills/
│   ├── pdf/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   └── references/
│   ├── docx/
│   └── xlsx/
├── artifacts-builder/
└── public-skills/

각 스킬 폴더에서 가장 중요한 파일은 SKILL.md 한 장이다. 이 파일이 곧 Claude가 읽는 진입점이고, 나머지 scripts/·references/·assets/는 SKILL.md가 필요할 때 추가로 참조하는 보조 자원이다. 필자가 PDF 스킬을 열어 보니 SKILL.md는 약 200줄, 그 외 PDF 파싱용 파이썬 헬퍼와 샘플 양식이 함께 들어 있었다.

💡 한 줄 정리

"스킬 = 폴더 하나, 진입점 = SKILL.md 한 장." 이 규칙만 외우면 레포 어디를 열어도 길을 잃지 않는다.

3. SKILL.md 작성 규칙 (frontmatter + 본문)

SKILL.md는 YAML frontmatter 블록과 마크다운 본문으로 구성된다. frontmatter엔 Claude가 스킬 선택을 판단할 때 쓰는 메타데이터를, 본문엔 실제 작업 절차를 쓴다. 공식 레포의 PDF 스킬을 단순화하면 다음 형태다.

SKILL.md · Markdown

---
name: pdf-extractor
description: Extracts text and tables from PDF files. Use when the user uploads a PDF and asks to summarize or extract structured data.
---

# PDF Extractor

## When to use
- 사용자가 PDF 파일을 업로드하고 "표만 뽑아줘"·"요약해줘"라고 할 때

## Steps
1. `scripts/extract.py`를 실행해 텍스트와 표를 분리한다.
2. 표는 마크다운으로, 본문은 섹션 단위로 정리한다.
3. 사용자가 추가 가공을 요청하면 `references/format-guide.md`를 참고한다.

여기서 결정적으로 중요한 필드가 description이다. Claude는 평소엔 SKILL.md 본문을 읽지 않고 frontmatter만 메모리에 둔다. 그러다 사용자 메시지를 보고 description과 매칭이 된다고 판단하면 그제야 본문을 불러온다. 따라서 description은 "언제 호출해야 하는지"를 자연어 한두 문장으로 명확히 써야 한다. "PDF 파싱"처럼 모호하게 쓰면 호출이 누락된다.

4. 첫 스킬 만들기 — 회의록 정리 봇

가장 단순한 스킬을 직접 만들어 본 과정이다. 목표는 "회의 녹취록을 붙여 넣으면 결정 사항·할 일·담당자를 표로 정리하는 스킬".

먼저 폴더 구조를 잡았다.

my-skills/
└── meeting-minutes/
    └── SKILL.md

SKILL.md엔 다음 내용을 넣었다.

---
name: meeting-minutes
description: Converts raw meeting transcripts into a structured minutes table with decisions, action items, and owners. Use when the user pastes a transcript and asks for minutes.
---

# Meeting Minutes Formatter

## Output schema
| 구분 | 내용 | 담당자 | 기한 |

## Rules
- 잡담·인사·중복 발언은 제외한다.
- 결정 사항과 단순 의견을 구분한다. 결정 사항만 "구분=결정"으로 표기.
- 담당자가 명시되지 않은 항목은 "미정"으로 둔다.

등록은 Claude Code 기준으로 ~/.claude/skills/ 아래에 폴더를 그대로 두기만 하면 된다. Claude Desktop이라면 설정 화면의 "Skills" 섹션에서 폴더를 가리키도록 한다. 등록 후 새 대화에서 "이 회의록 정리해줘"라고 했을 때 Claude가 "meeting-minutes 스킬을 사용합니다"라고 응답하면 정상이다.

⚠️ 흔한 실수

• description을 한국어로만 쓰면 영어 프롬프트에선 매칭이 잘 안 된다. 영어 한 문장 + 한국어 보충이 안전하다.
• SKILL.md 본문을 1,000줄 넘게 키우면 호출 시 토큰이 그만큼 소모된다. 길어지면 references/로 쪼개고 본문에선 "필요 시 참고하라"고만 안내한다.

5. Skills vs MCP vs Subagent 비교

세 개념은 자주 뒤섞이는데, 추상화 레벨이 다르다. 필자가 실제로 같은 작업("월간 보고서 자동 생성")을 세 방식으로 모두 구현해 보고 정리한 비교다.

구분	Skills	MCP	Subagent
본질	작업 절차서	외부 도구 호출 규격	하위 LLM 인스턴스
진입점	SKILL.md	JSON-RPC 서버	에이전트 정의 파일
호출 방식	자동 (description 매칭)	툴 콜 (모델이 결정)	메인 에이전트가 위임
잘하는 일	반복 작업의 절차 표준화	DB·API·파일시스템 연결	긴 컨텍스트 격리·병렬 처리
함께 쓰는가	예 (MCP 도구를 호출하는 스킬 가능)	예	예 (Subagent가 스킬을 사용)

요약하면 MCP는 "외부 세계와 통신하는 케이블"이고, Skills는 "그 케이블을 언제 어떻게 쓸지 적은 매뉴얼"이다. Subagent는 그 매뉴얼대로 일하는 별도의 작업자다. 셋은 경쟁 관계가 아니라 층위가 다른 부품이다.

6. 자주 묻는 질문

Skills는 Custom GPT의 카피인가

지시문을 미리 저장한다는 점은 비슷하다. 다만 Custom GPT는 단일 챗봇 단위로 묶이고, Skills는 폴더 단위로 쪼개져 한 대화에서 여러 스킬이 자동으로 골라 쓰인다는 점이 다르다. 회의록 스킬과 PDF 스킬이 같은 세션에 공존하고, Claude가 입력을 보고 적절한 쪽을 고른다.

스킬을 직접 만들 수 있나

가능하다. 필요한 건 SKILL.md 한 장과, 원한다면 보조 스크립트·참고 문서다. anthropics/skills 레포의 document-skills/ 아래 예제 폴더를 그대로 복사해 시작 템플릿으로 쓰면 가장 빠르다.

비용은 어떻게 되나

스킬 자체는 무료다. 다만 Claude가 스킬을 호출하면 SKILL.md 본문 분량만큼 입력 토큰이 추가된다. 필자 기준으론 일반적인 1KB 안팎 SKILL.md 한 장이면 응답 품질이 눈에 띄게 좋아져 토큰 비용 대비 효과가 컸다.

⚠️ 단점과 주의할 점

• 아직 표준이 빠르게 바뀐다 — 2026년 상반기에도 SKILL.md 필드 규격이 한두 번 갱신됐다. 운영 환경 투입 전에 공식 레포 변경 이력을 확인할 것.
• description 매칭은 결정론적이지 않다 — 같은 입력에도 스킬이 가끔 호출되지 않는다. 핵심 워크플로엔 "이 스킬을 써서"라고 명시적으로 유도하는 백업 경로를 둬야 한다.
• 민감 정보를 SKILL.md에 평문으로 적으면 모든 호출에 노출된다. 자격증명은 MCP나 환경변수로 분리한다.

🚀 지금 바로 할 일

1. git clone https://github.com/anthropics/skills로 공식 레포를 받고, document-skills/pdf/SKILL.md 한 장을 통째로 읽어 본다.
2. 내 업무 중 "매번 같은 가이드를 복붙하던 작업" 1개를 골라 SKILL.md 한 장 분량으로 옮긴다.
3. ~/.claude/skills/ 아래에 폴더를 두고 새 대화를 열어, Claude가 스킬을 자동으로 호출하는지 확인한다.

💬 의견

직접 Skills를 만들어 본 적이 있다면, 어떤 워크플로를 가장 먼저 스킬로 옮겼는지 댓글로 공유 부탁드립니다.

✅ 핵심 정리

• Skills는 "폴더 하나 + SKILL.md 한 장" 구조의 모듈형 지시서다.
• frontmatter의 description이 자동 호출의 성패를 가른다 — "언제 쓰는지"를 한두 문장으로 명확히.
• MCP·Subagent와 경쟁 관계가 아니라 함께 쓰는 다른 층위의 부품이다.
• 운영 환경 투입 전엔 표준 변경 이력과 description 매칭 누락 가능성을 점검해야 한다.

---

참고 자료

• anthropics/skills — 공식 GitHub 레포
• Anthropic — Agent Skills 발표 (Anthropic News)
• Anthropic Docs — Agent Skills 가이드
• Model Context Protocol 공식 문서

작성자: 사내 AI 자동화 파이프라인을 운영하며 Claude Code·Claude Desktop을 6개월 이상 실무에 적용해 온 개발자. 이 글은 anthropics/skills 레포를 직접 clone해 PDF·문서 스킬 예제를 분해하고, 자체 워크플로 3개를 SKILL.md로 옮겨 본 경험을 바탕으로 작성했다.