맥락을 스킬로 만든다는 것은 SKILL.md 하나에 언제 쓰는지와 어떻게 하는지를 적고, 그 옆에 세상에 없는 내 자료(참조 문서, 스크립트, 템플릿, 이미지)를 함께 넣은 폴더를 만드는 일입니다. 09-1에서 사람에게 남는 일 가운데 다시 쓸 수 있는 것은 맥락이고, 그 맥락이 모이는 그릇이 스킬이라고 했습니다. 스킬은 2장에서 처음 만들어 봤고 4장, 5장, 7장에서도 조금씩 나왔습니다. 이 절에서는 흩어져 있던 내용을 한 자리에 모아, 스킬을 처음부터 끝까지 만드는 방법으로 정리합니다. 스킬 폴더의 구조, Claude가 그 폴더를 읽는 방식, 그리고 세 종류의 맥락(제공되지 않은 내 데이터, 방대한 코드, 이미지와 템플릿 같은 에셋)을 각각 어떻게 담는지를 차례로 봅니다. 내용은 2026년 10월 현재 Claude 공식 문서로 확인한 것만 씁니다.

1. 스킬은 폴더 하나다

2장에서 .claude/skills/write-section/ 폴더에 SKILL.md와 예시 sample.md를 두어 첫 스킬을 만들었습니다. 그때는 기준과 진행 순서 정도만 적었지만, 스킬 폴더에는 SKILL.md 말고도 무엇이든 넣을 수 있습니다. 공식 문서가 보여 주는 기본 모양은 이렇습니다.

my-skill/
├── SKILL.md            ← 꼭 있어야 함. 앞머리와 본문
├── reference.md        ← 자세한 참조 문서. 필요할 때 읽음
├── examples.md         ← 예시 모음. 필요할 때 읽음
├── templates/          ← 결과물의 골격 파일
└── scripts/
    ├── helper.py       ← 실행만 하고, 코드 자체는 읽지 않음
    └── data.json       ← 스크립트가 읽는 데이터

references, templates, assets, scripts 같은 이름은 정해진 규칙이 아니라 관례입니다. 중요한 것은 SKILL.md가 이 파일들의 목차 역할을 한다는 점입니다. 본문에서 "자세한 표기 규칙은 references/style-guide.md를 본다"처럼 링크를 걸어 두어야 Claude가 그 파일이 있다는 것과 언제 읽어야 하는지를 압니다.

1.1 SKILL.md의 앞머리

SKILL.md 맨 위 --- 사이에 들어가는 앞머리(frontmatter)에서 가장 중요한 항목은 둘입니다.

---
name: write-section
description: IT 입문서의 한 절 원고를 출판사 서식으로 쓰고 검사한다. 절 쓰기, 꼭지 초안, 본문 작성 요청에 사용한다.
---

name: 스킬 이름이자 /write-section처럼 직접 부를 때의 명령어입니다. 영문 소문자, 숫자, 하이픈만 써서 64자 이내로 짓습니다. Claude Code에서는 생략하면 폴더 이름을 씁니다.

description: Claude가 이 스킬을 언제 꺼낼지 판단하는 유일한 단서입니다. 무엇을 하는지와 언제 쓰는지를 함께 적고, 사용자가 실제로 쓸 법한 단어를 넣습니다. 공식 모범 사례는 "나는 ~을 도와줄 수 있다" 같은 1인칭이 아니라 "~을 한다"처럼 3인칭으로 쓰라고 권합니다. API 문서 기준 상한은 1,024자이지만, claude.ai에 올릴 스킬은 도움말 기준 200자 이내로 짧게 쓰는 편이 안전합니다.

Claude Code에는 이 밖에도 직접 부를 때만 쓰게 하는 disable-model-invocation, 허락 없이 쓸 도구를 미리 정하는 allowed-tools, 특정 파일을 다룰 때만 켜지게 하는 paths 같은 항목이 더 있습니다. 처음에는 name과 description 두 줄이면 충분합니다.

1.2 Claude는 스킬을 세 단계로 펼쳐 읽는다

스킬이 맥락의 그릇으로 쓸모 있는 이유는 읽는 방식에 있습니다. 04-2에서 그림으로 본 내용을 공식 문서의 숫자와 함께 다시 보면 이렇습니다. 공식 문서는 이를 점진적 공개(progressive disclosure), 즉 필요한 만큼만 단계적으로 펼쳐 읽는 방식이라고 부릅니다.

특히 스크립트는 코드 내용이 컨텍스트에 들어가지 않고 실행 결과만 들어갑니다. 그래서 공식 문서는 쓰지 않는 파일은 비용이 들지 않으니 방대한 API 문서, 큰 데이터, 많은 예시를 넣어도 된다고 설명합니다. 다만 SKILL.md 본문은 불리는 순간 통째로 들어오므로 500줄 이내로 유지하고, 그보다 길어지는 내용은 참조 파일로 나누라고 권합니다.

이 차이를 공식 문서의 대략값으로 계산해 보면 다음과 같습니다. 스킬이 많아져도 평소에 깔리는 양은 이름과 설명뿐이라 완만하게 늘고, 모든 본문을 늘 깔아 두는 방식은 금방 감당할 수 없게 됩니다.

막대는 이름과 설명만 깔릴 때(스킬당 약 100토큰), 선은 본문까지 늘 깔아 둔다고 가정할 때(스킬당 상한 5천 토큰)입니다. 선은 상한으로 계산한 값이라 실제 본문이 짧으면 더 낮지만, 두 방식의 차이가 수십 배라는 점은 그대로입니다. 4장에서 본 Just-in-Time 컨텍스트, 즉 필요한 순간에 가져오는 전략이 스킬이라는 형태로 제품에 들어온 셈입니다.

2. 세 가지 맥락을 스킬로 묶기

이제 '세상에 없는 정보'를 실제 폴더로 옮깁니다. 09-1에서 정리한 대로, 글쓰기실습/의 write-section 스킬에 8장의 검사 스크립트까지 모아 다시 묶어 봅니다.

.claude/skills/write-section/
├── SKILL.md
├── references/
│   ├── style-guide.md       ← 톤, 금지 표현, 표기 규칙
│   ├── glossary.md          ← 우리 책의 용어 표기
│   └── past-feedback.md     ← 편집자가 지적했던 자리
├── scripts/
│   └── check.sh             ← 8장에서 폴더 맨 위에 두었던 검사 스크립트
└── assets/
    ├── sample.md            ← 2장에서 넣어 둔 잘 쓴 예시
    └── section-template.md  ← 절 원고의 골격

---
name: write-section
description: IT 입문서의 한 절 원고를 출판사 서식으로 쓰고 검사한다. 절 쓰기, 꼭지 초안, 본문 작성 요청에 사용한다.
---

# IT 책 한 절 쓰기

## 순서
1. 주제, 분량, 독자 수준을 확인한다. 빠진 것만 묻는다.
2. assets/section-template.md의 골격으로 초안을 쓴다. 문장의 결은 assets/sample.md를 본다.
3. 톤과 표기는 references/style-guide.md, 용어는 references/glossary.md를 따른다.
4. 저장한 뒤 scripts/check.sh로 검사하고, 실패한 항목만 고친다.
5. references/past-feedback.md의 지적을 같은 원고에서 되풀이하지 않는다.
6. 톤 검토는 reviewer 서브에이전트에게 맡긴다.

## 사람이 정할 것
- 외부 공개 여부는 묻고 기다린다.

파일은 늘었지만 본문은 오히려 짧습니다. "친근하게 써라", "단계별로 생각하라" 같은 설명은 지금 모델에게 필요 없습니다. 공식 모범 사례도 "Claude는 이미 매우 똑똑하다고 가정하고, Claude가 모르는 맥락만 넣으라" 고 권합니다. 대신 Claude가 절대 알 수 없는 것, 즉 우리 출판사의 표기 규칙, 용어집, 지난 지적이 파일로 들어갔습니다. 09-1에서 말한 흡수와 남음이 한 폴더 안에서 그대로 보입니다.

2.1 제공되지 않은 내 데이터

회사 정보, 단가표, 고객 응대 규정, 사내 용어집, 지난 프로젝트의 회고처럼 인터넷에 없는 자료가 여기에 해당합니다. 담는 요령은 공식 모범 사례에서 세 가지로 추릴 수 있습니다.

• 주제별로 파일을 나눕니다: 매출 질문에 영업 자료까지 읽을 필요는 없습니다. references/finance.md, references/sales.md처럼 나누고 SKILL.md에 어느 질문에 어느 파일을 보는지 적어 두면 Claude가 필요한 파일만 엽니다.
• 참조는 한 단계 깊이로 둡니다: SKILL.md가 가리킨 파일이 다시 다른 파일을 가리키면, Claude가 끝까지 읽지 않고 앞부분만 훑을 수 있습니다. 모든 참조 파일은 SKILL.md에서 바로 연결합니다.
• 100줄이 넘는 참조 파일은 맨 위에 목차를 둡니다: 일부만 읽더라도 파일 전체에 무엇이 있는지 알 수 있게 하기 위해서입니다.

그리고 날짜에 묶인 정보는 따로 관리합니다. "8월 전에는 옛 단가"처럼 쓰면 시간이 지나 틀린 정보가 됩니다. 현재 기준만 본문에 두고, 지난 기준은 '예전 방식' 항목으로 접어 두는 편이 낫습니다.

2.2 방대한 코드

코드베이스는 스킬에 통째로 넣는 대상이 아닙니다. 코드는 이미 저장소에 있고, Claude는 필요한 파일을 스스로 찾아 읽습니다. 스킬이 맡을 일은 코드에 적혀 있지 않은 것입니다.

반복해서 조사해야 하는 일은 스크립트로 만들어 scripts/에 넣습니다. 예를 들어 "이 함수를 부르는 곳을 모두 찾아 표로 정리"하는 스크립트를 두면, Claude가 매번 코드를 새로 짜지 않고 실행 결과만 받습니다. 공식 문서는 미리 만든 스크립트가 그때그때 생성한 코드보다 믿을 만하고, 토큰과 시간을 아끼며, 매번 같은 결과를 낸다고 설명합니다.

Claude Code에서는 몇 가지 장치가 더 있습니다.

• 저장소에 넣는 프로젝트 스킬: .claude/skills/에 두고 커밋하면 저장소를 받은 사람 모두가 같은 스킬을 씁니다.
• 하위 폴더 스킬: 큰 저장소라면 apps/web/.claude/skills/처럼 하위 폴더에 두어, 그 폴더에서 작업할 때만 불러오게 할 수 있습니다.
• 스킬 폴더 경로 변수: 본문에서 ${CLAUDE_SKILL_DIR}/scripts/check.sh처럼 쓰면 어느 폴더에서 작업하든 스킬 안의 스크립트를 찾습니다.
• 명령 결과 끼워 넣기: 본문에 !`git log --oneline -5`처럼 쓰면 스킬을 보내기 전에 명령을 실행해 그 결과를 끼워 넣습니다. 내 컴퓨터에서 도는 Claude Code 세션을 위한 기능입니다.

재사용할 코드 덩어리가 많은 경우도 있습니다. 회사가 쓰는 화면 골격, 자주 쓰는 설정 파일, 검증된 컴포넌트 같은 것들입니다. 이런 코드는 templates/에 넣고 "새 화면은 templates/page.html을 복사해서 시작한다"처럼 적어 둡니다. 코드를 설명하는 문장보다 실제 파일 하나가 결과를 훨씬 일정하게 만듭니다.

2.3 에셋, 이미지와 템플릿과 브랜드

로고, 캐릭터, 사진, 글꼴 규칙, 문서 서식, 회사 정보처럼 모델이 새로 만들어 내면 안 되는 것들입니다. 모델은 그럴듯한 로고를 그릴 수 있지만, 그것은 우리 로고가 아닙니다. 에셋은 파일로 넣고, 본문에는 쓰는 규칙을 적습니다.

## 에셋
- 로고는 assets/logo.svg를 그대로 쓴다. 다시 그리거나 색을 바꾸지 않는다.
- 회사 정보 표기는 assets/company.md의 문장을 그대로 옮긴다.
- 문서 골격은 assets/template.html에서 시작한다.

06-1의 표에서 본 위니브의 회사 표준 서식 스킬 일곱 개(슬라이드, 결과보고서, 계획서, 입찰 제안서, 포스터, 카드뉴스, 견적서)가 이 방식입니다. 각 스킬에는 서식과 함께 로고, 캐릭터, 사진, 회사 정보 같은 에셋이 들어 있어서, 문서를 만들 때마다 자료를 다시 찾아 붙이지 않고 그대로 재활용합니다. 모델이 바뀌어도 이 파일들은 바뀌지 않습니다. 모델이 좋아질수록 문장은 더 좋아지고, 서식과 에셋은 스킬이 그대로 지켜 줍니다.

3. 어디에 두고 어디서 쓰나

스킬은 같은 폴더 모양이지만, 어디에 두느냐에 따라 쓸 수 있는 곳과 함께 쓰는 사람이 달라집니다. Claude Code 공식 문서 기준 위치는 다음과 같습니다.

팀에 나누는 길, 곧 저장소에 커밋하기, 플러그인과 마켓플레이스로 묶기, claude.ai 조직 공유는 07-1에서 자세히 봤습니다. 이름이 겹치면 조직 관리, 개인, 프로젝트 순으로 앞선 쪽이 이깁니다. 플러그인 스킬은 이름 앞에 플러그인 이름이 붙어 겹치지 않습니다. 터미널에서 SKILL.md를 고치면 세션을 다시 시작하지 않아도 바로 반영됩니다.

claude.ai와 Claude Desktop의 대화에서는 방식이 다릅니다. 이쪽은 내 컴퓨터의 ~/.claude/skills/를 읽지 않고, 계정에 올려 켜 둔 스킬을 씁니다. Desktop 앱 옆 메뉴나 claude.ai의 Customize > Skills에서 스킬 폴더를 ZIP으로 올리고 켜고 끌 수 있습니다. 이 기능은 코드 실행과 파일 만들기 설정이 켜져 있어야 동작합니다. 계정에서 켠 스킬은 같은 계정으로 로그인한 Claude Code 터미널에도 내려받아집니다. Claude Desktop의 Code 탭처럼 내 컴퓨터 폴더에서 도는 세션은 위 표의 위치를 그대로 읽습니다.

API는 또 다른 길입니다. 공식 문서는 claude.ai에 올린 스킬과 API에 올린 스킬이 서로 자동으로 옮겨지지 않으니 쓰는 곳마다 따로 올리라고 안내합니다.

4. 직접 만들어 보기

만드는 길은 세 가지입니다. 어느 쪽이든 결과는 같은 모양의 폴더입니다.

4.1 함께 일한 뒤 Claude에게 스킬로 만들어 달라고 하기

가장 쉬운 길이고, 05-2에서 검토 순서를 스킬로 만들 때 쓴 방법이기도 합니다. 공식 모범 사례가 권하는 순서도 이것입니다. 먼저 스킬 없이 평소처럼 일을 한 번 끝냅니다. 그 과정에서 내가 여러 번 설명한 것, 고쳐 달라고 한 것, 붙여 넣은 자료가 바로 스킬에 담을 맥락입니다. 일이 끝나면 이렇게 부탁합니다.

방금 우리가 한 절 원고를 쓰면서 정한 규칙을 스킬로 만들어 줘.
표기 규칙과 용어는 references 폴더에 따로 두고,
8장의 check.sh도 scripts에 넣어 줘.
SKILL.md 본문에는 네가 이미 아는 일반적인 글쓰기 설명은 넣지 마.

공식 문서는 Claude가 스킬 형식과 구조를 이미 알고 있어서, 별도 도구 없이 부탁만 해도 앞머리와 본문을 갖춘 SKILL.md를 만든다고 설명합니다. 만들어진 뒤에는 불필요한 설명이 들어갔는지 한 번 보고 덜어 냅니다.

4.2 claude.ai에 ZIP으로 올리기

이미 만든 스킬 폴더를 claude.ai나 Claude Desktop 대화에서 쓰려면 ZIP으로 올립니다. 도움말이 정한 조건은 세 가지입니다.

1. 폴더 이름이 스킬 이름과 같아야 합니다.
2. ZIP을 풀었을 때 맨 위에 그 폴더가 있어야 합니다. 폴더 안의 파일만 압축하면 안 됩니다.
3. 폴더 안에 SKILL.md가 있어야 합니다.

Customize > Skills에서 추가 버튼을 누르고 스킬 올리기를 고른 뒤 ZIP을 넣고, 목록에서 켜면 됩니다. !`명령` 끼워 넣기처럼 내 컴퓨터 세션을 전제로 한 기능은 Cowork 같은 곳에서 실행되지 않으니, 여러 곳에서 함께 쓸 스킬은 앞머리와 본문을 단순하게 두는 편이 안전합니다.

4.3 하는 모습을 보여 주고 만들기

Claude for Mac의 Cowork에서는 손으로 쓰는 대신 작업하는 모습을 녹화해 스킬을 만드는 기능도 있습니다. 녹화를 시작하고 평소처럼 일을 한 뒤 끝내면, Claude가 본 것을 바탕으로 새 스킬을 제안하거나 기존 스킬의 수정안을 냅니다. 녹화 중에는 비밀번호나 민감한 화면을 띄우지 말라고 도움말이 경고합니다.

여기까지가 스킬 하나를 만드는 일입니다. 그런데 처음 만든 스킬은 대개 어딘가 어긋납니다. 불려야 할 때 안 불리거나, 불렸는데 규칙 하나를 빠뜨립니다. 09-3에서는 스킬을 쓰면서 고치고, 팀과 나누는 방법을 봅니다.

• Claude Code 스킬 문서: https://code.claude.com/docs/en/skills
• Agent Skills 개요: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
• 스킬 작성 모범 사례: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
• Claude에서 스킬 쓰기: https://support.claude.com/en/articles/12512180-use-skills-in-claude
• 사용자 스킬 만들기: https://support.claude.com/en/articles/12512198-how-to-create-custom-skills