클로드 스킬 만들기 2026 — SKILL.md 작성법과 MCP와의 차이 비교

클로드 스킬이란 — 3줄 요약

같은 지시를 반복해서 붙여넣고 있다면, 그것을 파일로 만든 것이 스킬이다. 스킬 만들기는 새 문법을 배우는 일이 아니라 이미 말로 하던 절차를 마크다운 파일 하나로 옮기는 일이다. SKILL.md 파일에 절차를 적어 두면 Claude가 필요할 때 알아서 불러 쓰거나, /스킬이름으로 직접 호출할 수 있다.

핵심은 본문이 쓸 때만 로드된다는 점이다. CLAUDE.md에 적은 내용은 매 세션 컨텍스트에 통째로 올라가 상시 토큰을 소모하지만, 스킬 본문은 실제로 호출될 때만 읽힌다. 긴 참고 자료를 부담 없이 넣을 수 있는 이유다.

둘은 경쟁 관계가 아니라 층이 다르다. HWP 파일을 열려면 MCP가 필요하고, "계약서를 어떤 순서로 검토할지"는 스킬이 담당한다. 실무에서는 같이 쓴다.

어디에 두는가 — 저장 위치와 우선순위

스킬은 폴더 하나에 SKILL.md 하나가 기본 단위다. 위치에 따라 적용 범위가 달라진다.

같은 이름이 여러 위치에 있으면 하나만 적용된다. 어느 쪽이 이기는지는 버전에 따라 달라질 수 있으므로 이름을 겹치지 않게 두는 것이 안전하다. 고쳤는데 반영이 안 되는 느낌이면 다른 위치의 동명 스킬을 보고 있을 가능성이 높다.

팀과 공유할 규칙은 프로젝트에 두고 저장소에 커밋한다. 개인 작업 습관은 ~/.claude/skills/에 두면 모든 프로젝트에서 따라온다.

가장 단순한 스킬 만들기

스킬 만들기의 전부는 이것이다 — 폴더를 만들고 파일 하나를 넣으면 끝이다. 빌드도 설치도 없다.

mkdir -p ~/.claude/skills/summarize-changes

---
name: summarize-changes
description: 커밋되지 않은 변경사항을 검토용으로 요약한다. 변경 내용을 정리하거나 PR 설명을 쓸 때 사용한다.
---

# 변경사항 요약

1. `git diff` 로 커밋되지 않은 변경을 확인한다.
2. 파일별로 무엇이 왜 바뀌었는지 한 줄씩 정리한다.
3. 리뷰어가 먼저 봐야 할 파일을 맨 위에 둔다.

이제 /summarize-changes 로 호출할 수 있고, 관련 상황에서 Claude가 알아서 쓰기도 한다.

description이 가장 중요하다. Claude는 이 문장을 보고 스킬을 쓸지 판단한다. "무엇을 하는지"와 "언제 쓰는지"를 함께 적어야 한다. 목록에 실리는 설명에는 길이 제한이 있고 그 값은 버전에 따라 달라진다. 숫자를 외우기보다 핵심 용도를 첫 문장에 두는 습관이 안전하다.

SKILL.md 뜯어보기 — 무엇을 적고 무엇을 적지 않나

파일 하나가 전부이므로, 그 안에서 무엇을 어떻게 쓰느냐가 스킬의 품질을 결정한다. 구조는 두 층이다.

---
name: pr-review
description: PR 리뷰를 요청받았을 때 따르는 절차. 변경 파일을 훑고
             8개 항목을 대조해 파일:줄 형식으로 지적한다.
---

(본문 — 호출될 때만 읽힌다)

프론트매터는 「언제 쓸지」를, 본문은 「어떻게 할지」를 담는다. 이 분담이 흐려지면 둘 다 제 몫을 못 한다. 프론트매터에 절차를 적으면 상시 토큰을 낭비하고, 본문에만 조건을 적으면 호출 판단을 못 해 아예 안 불린다.

프론트매터 필드

빈도는 로컬에 설치된 스킬 645개를 훑어 센 것이다. 배포처마다 다르니 절대 수치로 받아들이지 말고, description 하나에 공이 몰려 있다는 사실만 가져가면 된다.

description 이 전부인 이유. 스킬 목록에 올라가는 것은 이름과 이 한 문장뿐이다. 본문은 호출이 결정된 뒤에야 읽힌다. 즉 Claude 는 본문을 보지 못한 채 쓸지 말지를 정한다. 아무리 본문이 좋아도 이 문장이 부실하면 영영 안 불린다.

차이는 길이가 아니라 트리거가 문장에 들어 있는가다. 왼쪽은 주제만 적었고 오른쪽은 「어떤 요청이 오면」을 적었다.

목록에 올라가는 설명에는 길이 제한이 있다. 정확한 상한은 버전에 따라 달라지므로 숫자를 외우기보다 핵심 용도를 첫 문장에 두는 습관이 안전하다. 뒤로 밀린 조건은 잘려 나갈 수 있다.

본문 쓰는 법. 본문은 사람이 읽는 설명서가 아니라 모델이 따라갈 절차서다. 세 가지만 지키면 된다.

1. 번호 매긴 순서로 쓴다. 산문으로 쓰면 단계가 섞인다.
2. 판단이 필요한 지점에 기준을 준다. "적절히 정리한다"가 아니라 "파일별로 한 줄, 리뷰어가 먼저 볼 파일을 위에".
3. 하지 말 것을 적는다. 모델은 금지를 적어 두지 않으면 좋은 뜻으로 범위를 넘는다.

분량은 한 화면을 넘지 않는 편이 좋다. 길어지면 다음 절의 방법으로 쪼갠다.

한 파일로 부족할 때 — 참고 자료를 곁에 두는 구조

절차가 길거나 참고표가 붙으면 SKILL.md 한 장이 버겁다. 이때 폴더 안에 파일을 더 둔다.

~/.claude/skills/contract-review/
├── SKILL.md           ← 절차. 호출되면 읽힌다
├── checklist.md       ← 점검 항목 30개
└── templates/
    └── report.md      ← 결과를 적을 서식

핵심은 부속 파일이 자동으로 읽히지 않는다는 점이다. SKILL.md 본문에서 "checklist.md 를 읽고 그 항목을 대조한다"처럼 명시적으로 지시해야 읽는다. 이게 단점처럼 보이지만 사실 이 구조의 이점이다 — 30개 항목표를 매번 컨텍스트에 올리지 않고, 실제로 대조할 때만 읽는다.

세 층을 구분하지 않으면 둘 중 하나가 된다 — 전부 프론트매터에 넣어 상시 토큰을 태우거나, 전부 본문에 넣어 호출 한 번에 수천 토큰을 쓰거나. 스킬 하나가 커지기 시작하면 이 표를 기준으로 갈라내면 된다.

어떤 작업을 스킬로 만들면 좋은가

기준은 하나다. 같은 설명을 두 번 이상 붙여넣었다면 스킬 후보다.

국내 실무에서 특히 효과가 큰 유형을 정리한다.

반대로 한 번만 하는 작업이나 매번 조건이 달라지는 일은 스킬로 만들 이유가 없다. 그냥 그때 설명하는 편이 빠르다.

한국어로 일하게 만드는 스킬 — 용어·말투·번역 규칙 고정하기

영어로 답하거나, 같은 대상을 매번 다른 말로 부르거나, 보고서 문체가 회차마다 바뀌는 문제는 매번 지시해서 풀 일이 아니라 한 번 파일로 굳힐 일이다.

---
name: korean-style
description: 한국어로 문서나 답변을 쓸 때 따르는 용어·문체 규칙.
             보고서·공지·리뷰 코멘트를 작성하면 이 규칙을 적용한다.
---

용어는 아래 표기로 통일한다. 괄호 안은 쓰지 않는다.

- 배포 (deploy, 디플로이)
- 장애 (인시던트, incident)
- 회귀 (리그레션)
- 산출물 (deliverable, 결과물)

문체
1. 보고서·공지는 한다체. 고객 대상 문서는 존댓말.
2. 한 문장에 주어 하나. 번역투 「~되어지다」·「~에 있어서」를 쓰지 않는다.
3. 영어 약어는 첫 등장에만 한글 풀이를 괄호로 붙이고 이후에는 약어만 쓴다.

번역
- 영문 원문을 옮길 때 직역하지 않는다. 한국어 문장으로 다시 쓴다.
- 고유명사와 제품명은 원문 표기를 유지한다.

이 한 장이 있으면 "존댓말로 써 줘", "그거 배포라고 해" 같은 지시를 반복하지 않는다. 용어표가 특히 값이 크다 — 사람이 문서를 쓸 때도 같은 표를 보게 되므로 팀 표기가 저절로 맞는다.

붙여 쓰면 좋은 규칙이 몇 개 더 있다.

프로젝트마다 용어가 다르면 이 스킬은 개인이 아니라 프로젝트 폴더에 둔다. 저장소를 받은 사람이 같은 표기를 쓰게 된다.

문서 작성 스킬 — 주간보고 하나를 통째로

가장 많이 쓰이는 유형이라 완성본을 그대로 싣는다. 복사해서 이름과 항목만 바꾸면 된다.

---
name: weekly-report
description: 주간보고를 사내 양식으로 작성한다. 「주간보고 써줘」,
             「이번 주 정리해줘」 같은 요청이 오면 이 절차를 따른다.
---

1. 이번 주 범위를 확정한다. 지난 월요일부터 오늘까지다.
2. 근거를 먼저 모은다 — git log, 완료한 이슈, 회의록.
   기억으로 쓰지 않는다. 근거가 없는 항목은 적지 않는다.
3. 아래 네 절로만 쓴다. 절을 추가하지 않는다.

   이번 주 한 일
     - 결과를 먼저, 과정은 한 줄. 「~를 했다」가 아니라 「~가 되었다」
     - 항목당 한 줄. 세 줄 넘으면 쪼갠다

   다음 주 할 일
     - 날짜가 있는 것만. 「검토 예정」 같은 표현은 쓰지 않는다

   막힌 것
     - 누가 무엇을 해 주면 풀리는지까지 적는다
     - 없으면 「없음」이라고 적는다. 절을 지우지 않는다

   숫자
     - 지난주 대비 증감을 괄호로 붙인다

4. 전체 분량은 한 화면을 넘기지 않는다.
5. 마지막에 「확인이 필요한 결정」이 있으면 맨 위로 올린다.

「막힌 것」 절을 비워 두지 않고 「없음」이라고 적게 한 것이 이 스킬의 핵심이다. 절이 사라지면 읽는 사람은 막힌 게 없는 건지 안 적은 건지 모른다. 이런 판단이 스킬에 들어가야 할 종류의 지식이고, 매번 지시하기 번거로워 결국 안 지켜지는 종류이기도 하다.

회의록은 같은 틀에서 절만 바꾸면 된다 — 참석자·결정된 것·미결·다음 액션(담당자와 기한 포함). 결정과 미결을 갈라 적게 하는 것이 회의록 스킬의 값어치다. 합의된 줄 알았던 항목이 나중에 미결로 드러나는 일이 줄어든다.

개발 루프에 박아 두는 스킬

트리숲은 팀원 전원이 Claude Code 를 기본 개발 환경으로 쓴다. 실제로 매일 불리는 스킬은 화려한 것이 아니라 순서가 틀리면 사고가 나는 일들이다.

릴리즈와 장애 대응에는 disable-model-invocation: true 를 넣는다. 절차는 문서로 남기되 실행 시점은 사람이 정한다. 모델이 좋은 뜻으로 배포를 시작하는 상황을 만들지 않는 것이 이 필드의 존재 이유다.

코드 리뷰 스킬에서 실제로 효과가 컸던 것은 「지적하지 말 것」 목록이었다. 포매터가 잡는 스타일, 팀이 이미 합의한 관례, 취향 문제를 명시적으로 빼 두지 않으면 리뷰가 소음으로 덮인다. 금지를 적지 않으면 모델은 범위를 넓게 잡는다.

한글 문서 작업에 스킬을 쓸 때

국내 업무 문서 상당수가 HWP인데, Claude는 .hwp·.hwpx를 기본 지원 형식으로 받지 않는다. 그래서 이 영역은 MCP로 파일을 열 수 있게 만들고, 스킬로 처리 절차를 고정하는 2단 구성이 된다.

1. MCP 연결 — Claude가 한글 파일을 읽고 쓸 수 있게 한다. 설치는 HWP-MCP 한글문서 AI 도입 가이드 참고
2. 스킬 작성 — "계약서를 읽고 5개 조항을 표로 정리한다" 같은 절차를 SKILL.md에 고정
3. 호출 — 파일을 주면서 /계약서검토 한 줄

한글 양식 작업 스킬 한 벌 — 처음부터 끝까지

말로 설명하는 대신 실제로 만들어 보는 편이 빠르다. 「받은 HWP 양식에 내용을 채워 돌려준다」는 업무를 스킬로 만든다.

1단계 — 반복되는 지시를 찾는다. 매번 이런 말을 붙여넣고 있다면 그것이 스킬 후보다.

「이 양식 원본을 그대로 편집해 줘. PDF로 바꿔서 덮어쓰면 괘선이 지워지니까 안 돼. 표 안의 값은 셀 단위로 넣고, 넣기 전에 어떤 셀에 뭘 넣을지 먼저 보여 줘.」

2단계 — 폴더와 파일을 만든다.

mkdir -p ~/.claude/skills/hwp-form-fill

3단계 — SKILL.md 를 쓴다. 절차와 함께 금지 사항을 적는 것이 핵심이다.

---
name: hwp-form-fill
description: 받은 HWP·HWPX 양식의 원본을 직접 편집해 내용을 채운다. 양식 서류 작성, 신청서·계약서 양식 기입, 표가 있는 한글 문서 수정에 사용한다.
---

# HWP 양식 채우기

## 금지
- **PDF 변환 후 덮어쓰지 않는다.** 괘선과 서식이 지워진다.
- 표 안의 값을 텍스트 치환으로 넣지 않는다. 줄바꿈이 깨진다.
- 원본을 덮어쓰기 전에 사본을 둔다.

## 절차
1. 문서를 열어 전체 구조(섹션·표·필드)를 먼저 읽는다.
2. 채울 자리를 **셀 좌표와 함께** 목록으로 만들어 사용자에게 보여 준다.
3. 승인받은 뒤 셀 단위로 값을 넣는다.
4. 채운 뒤 한 페이지를 이미지로 렌더해 눈으로 확인한다.
5. 빈 칸으로 남긴 자리를 따로 보고한다.

## 값을 모를 때
비워 두고 「확인 필요」로 표시한다. 추측해서 채우지 않는다.

4단계 — 호출한다. 파일을 주면서 /hwp-form-fill 한 줄이면 된다.

5단계 — 실패하면 금지 목록을 늘린다. 스킬을 만드는 일은 한 번에 끝나지 않는다. 사고가 날 때마다 그 사고를 금지 항목으로 적어 두는 것이 스킬이 쌓이는 방식이다. 위 「금지」 세 줄은 전부 실제로 한 번씩 당한 것들이다.

이 스킬이 MCP 와 나뉘는 지점

같은 작업에 둘 다 쓰이지만 역할이 섞이면 안 된다.

MCP만 있으면 매번 같은 주의사항을 말로 반복해야 한다. 스킬만 있으면 파일을 열 수가 없다. 둘을 같이 만들어 두면 「양식 주면 채워 줘」 한 줄로 끝난다.

실제 업무 자동화 워크플로는 클로드로 한글파일 변환·작성·자동화하는 법에 정리했다. 한국어 환경 전반 설정은 클로드 코드 한글 환경 설정을 참고하면 된다.

만든 스킬을 팀에 돌리는 법

혼자 쓸 스킬과 팀이 쓸 스킬은 두는 자리가 다르다.

팀 스킬은 레포에 넣는 것만으로 공유가 끝난다. 받은 사람이 따로 설치할 것이 없다.

팀 스킬로 만들 때 달라지는 것 세 가지.

description 을 더 구체적으로 쓴다. 내가 만든 스킬은 내가 언제 쓸지 알지만, 남은 모른다. 「배포한다」가 아니라 「프로덕션에 배포한다. 스테이징 배포나 로컬 빌드에는 쓰지 않는다」처럼 쓰지 않을 상황까지 적어야 엉뚱한 데서 불리지 않는다.

되돌리는 방법을 본문에 적는다. 팀 스킬은 만든 사람이 없는 자리에서 실행된다. 잘못됐을 때 무엇을 되돌려야 하는지가 절차 안에 있어야 한다.

사람 확인 지점을 남긴다. 되돌릴 수 없는 작업(배포·삭제·외부 전송) 앞에는 「진행해도 되는지 묻는다」를 넣는다. 혼자 쓸 때는 생략해도 되지만 팀 스킬에서는 이게 유일한 안전장치다.

그리고 스킬이 늘어나면 이름이 겹친다. 같은 이름이 개인과 프로젝트 양쪽에 있으면 어느 쪽이 불리는지 헷갈리므로, 팀 스킬에는 deploy-web 처럼 대상을 붙여 두는 편이 낫다.

스킬이 안 불릴 때 — 원인 다섯과 진단 순서

만들어 놓고 안 쓰이는 것이 가장 흔한 실패다. 위에서부터 차례로 짚으면 대부분 여기서 끝난다.

1. description 에 트리거가 없다. 압도적 1위 원인이다. 주제만 적고 「어떤 요청이 오면」을 안 적은 경우다. Claude 는 목록의 이 한 문장만 보고 판단한다 — 본문이 아무리 좋아도 소용없다. → 실제로 하게 될 말("주간보고 써줘")을 description 에 넣는다.

2. 파일 위치나 이름이 어긋났다. 폴더명과 SKILL.md 라는 파일명이 규칙이다. skill.md·SKILLS.md·폴더 없이 파일만 둔 경우가 모두 안 잡힌다. → ~/.claude/skills/<이름>/SKILL.md 또는 .claude/skills/<이름>/SKILL.md 인지 그대로 확인한다.

3. 프론트매터가 깨졌다. 앞뒤 --- 가 없거나, 값에 콜론이 들어갔는데 따옴표를 안 씌운 경우다. description: 배포: 순서대로 처럼 콜론이 들어가면 파싱이 깨진다. → 콜론·따옴표가 든 값은 따옴표로 감싼다.

4. disable-model-invocation: true 를 켜 두고 잊었다. 이 경우 자동 호출만 안 되고 /이름 직접 호출은 된다. 직접 호출은 되는데 알아서는 안 쓰는 증상이면 여기를 먼저 본다.

5. 같은 이름이 여러 군데 있다. 개인과 프로젝트에 같은 이름이 있으면 하나만 적용된다. 고쳤는데 반영이 안 되는 느낌이면 다른 위치의 동명 스킬을 보고 있을 가능성이 높다. → 이름을 바꿔 충돌을 없애고 다시 본다.

진단 순서

1. /이름 으로 직접 불러 본다 → 되면 파일은 정상이다. 원인은 1번이나 4번이다.
2. 직접 호출도 안 되면 → 위치·파일명(2번)과 프론트매터(3번)를 본다.
3. 둘 다 정상인데 안 되면 → 같은 이름이 다른 곳에 있는지(5번) 본다.

이 순서가 중요한 이유는, 직접 호출이 되는지 여부가 「파일 문제」와 「설명 문제」를 한 번에 가르기 때문이다. 이걸 먼저 확인하지 않으면 멀쩡한 파일을 붙잡고 오래 고치게 된다.

스킬·MCP·CLAUDE.md·서브에이전트 — 어디에 무엇을 둘까

비슷해 보이는 장치가 여럿이라 「이건 어디에 적지」에서 막힌다. 판단 기준은 언제 읽히는가다.

가장 흔한 실수는 스킬에 둘 것을 CLAUDE.md 에 넣는 것이다. CLAUDE.md 는 매 세션 통째로 올라간다. 거기에 「배포 절차 12단계」를 적으면 배포와 무관한 모든 작업에서 그 토큰을 낸다. 반대로 「들여쓰기는 2칸」처럼 항상 적용되는 규칙을 스킬에 넣으면 호출되지 않아 안 지켜진다.

판단 문장 하나. 이 내용이 이번 작업과 무관할 때도 모델이 알아야 하는가?

• 그렇다 → CLAUDE.md
• 아니다 → 스킬

MCP 와의 구분은 더 단순하다. 능력이 없어서 못 하는 일이면 MCP, 방법을 몰라서 못 하는 일이면 스킬이다. HWP 파일을 열지 못하는 것은 능력 문제이므로 MCP 가 필요하고, 계약서를 어떤 순서로 검토할지는 방법 문제이므로 스킬이 맡는다. 둘은 층이 달라서 같이 쓴다.

서브에이전트는 성격이 또 다르다. 스킬이 「어떻게」를 알려준다면 서브에이전트는 그 일을 다른 문맥에서 하게 만든다. 파일 20개를 훑어야 하는 탐색을 메인 대화에서 하면 그 내용이 전부 쌓이지만, 서브에이전트에 맡기면 결론만 돌아온다. 스킬 본문에서 "이 작업은 서브에이전트로 돌린다"고 지시하는 식으로 겹쳐 쓸 수 있다.

FAQ

스킬과 슬래시 명령(/명령)은 다른 건가요? 같아졌다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만든다. 기존 commands/ 파일은 그대로 동작한다. 스킬 쪽이 보조 파일을 담을 폴더, 호출 주체를 정하는 frontmatter, 자동 로드를 추가로 지원한다.

스킬을 만들면 항상 컨텍스트를 잡아먹나요? 아니다. 목록에는 이름과 description만 올라가고, 본문은 실제로 호출될 때 로드된다. 그래서 긴 참고 자료를 넣어도 평소 비용이 거의 없다.

Claude가 원하지 않을 때 스킬을 실행하면? frontmatter에 disable-model-invocation: true를 넣으면 직접 호출할 때만 동작한다. 배포나 커밋처럼 부작용이 있는 작업에 권장한다.

팀원과 어떻게 공유하나요? 프로젝트 저장소의 .claude/skills/에 두고 커밋하면 된다. 저장소를 받은 사람은 별도 설치 없이 같은 스킬을 쓴다.

정리

스킬은 새로운 도구가 아니라 반복 설명을 파일로 굳히는 방법이다. MCP가 Claude의 손을 늘린다면 스킬은 일하는 순서를 알려준다. 같은 지시를 두 번 붙여넣은 순간이 만들 때다.

스킬은 개인 작업 습관을 파일로 굳히는 데서 시작하지만, 팀 단위로 쓰면 업무 표준을 코드처럼 관리하는 수단이 됩니다. 트리숲은 팀원 전원이 Claude Code Max를 기본 개발 환경으로 쓰며, Brainstorming·Writing-plans·Subagent 스킬을 실전 개발 루프에 적용하고 있습니다 — 그 방식은 AI-Native 개발 방식에 정리했습니다.