클로드 스킬 만들기, SKILL.md 구조와 대화로 만들고 고치는 법

클로드 스킬 만들기에 필요한 것을 두 갈래로 정리합니다. 앞부분은 스킬이 프롬프트⁠·프로젝트 지시문과 무엇이 다르고 SKILL.md가 어떤 구조인지, 뒷부분은 Claude와 Codex에서 대화로 스킬을 만들고 올리고 고치는 31단계입니다. 스킬은 프롬프트를 대신하는 것이 아니라 프롬프트를 넓힌 것이라서, 지시를 잘 쓰는 사람이 스킬도 잘 만듭니다.

프로젝트 지시문과 스킬은 뭐가 다른가

프로젝트에 지시문을 넣어 두면 그 안에서는 같은 방식으로 반복 작업을 해 줍니다. 그래서 "프로젝트면 충분하지 않나" 싶을 수 있습니다. 차이는 두 가지입니다.

• 부르는 방식: 프로젝트는 작업할 때마다 그 프로젝트로 들어가야 합니다. 스킬은 아무 대화창에서나 요청만 하면 Claude가 관련 스킬을 알아서 꺼내 씁니다. Codex도 같은 방식입니다.
• 담는 것: 지시문은 텍스트뿐입니다. 스킬은 지시문, 참고 자료, 템플릿 파일, 검증 스크립트를 한 꾸러미로 묶습니다.

비유하면 프로젝트 지시문은 레시피, 스킬은 재료까지 담긴 밀키트입니다.

스킬이 나온 배경

예전 AI는 묻는 말에 답하는 대화 상대였습니다. 지금은 여러 단계를 이어 처리하고, 외부 시스템과 연동하고, 스스로 판단하는 에이전트로 일합니다.

언어 이해력이 좋아져서 어설프게 말해도 의도를 알아듣다 보니, 완벽한 문장을 다듬는 기술만으로는 차이가 덜 납니다. 대신 "어떻게 물을까"보다 "무엇을 해결하게 할까", 곧 복잡한 업무를 AI가 처리할 수 있게 구조화하는 능력이 중요해졌습니다. 그렇게 구조화한 업무 꾸러미를 담는 기본 그릇이 스킬입니다.

SKILL.md 구조: 스킬은 폴더 하나다

스킬은 폴더입니다. 안에는 SKILL.md 파일 하나가 반드시 들어가고, 필요하면 참고 자료 폴더(reference)와 스크립트 폴더(scripts)를 더합니다.

• SKILL.md: 핵심이고 필수입니다. 이것만 있어도 스킬은 작동합니다.
• reference, scripts 폴더: 필요할 때 추가합니다. 처음부터 없어도 됩니다.

MD(마크다운) 파일은 글자만으로 구조를 표현하는 문서라 AI가 읽기 쉽습니다. # 하나는 큰 제목이고 개수가 늘수록 작은 제목, 목록은 하이픈(-), 강조는 별표 두 개(**)로 씁니다.

SKILL.md의 맨 위에는 --- 줄 사이에 이름(name)과 설명(description)을 적고, 그 아래에 본문을 씁니다. 가장 작은 스킬은 이런 모양입니다.

---
name: weekly-report
description: 주간 업무 보고서를 회사 양식으로 작성한다. 사용자가 "주간 보고", "주간 업무 정리", "weekly report"를 요청할 때 사용한다.
---

# 주간 보고서 작성

## 순서
1. 이번 주 한 일을 사용자에게 묻는다.
2. reference/template.md의 양식대로 정리한다.
3. 수치가 들어간 문장은 사용자에게 한 번 더 확인받는다.

이름은 영어 소문자, 숫자, 하이픈만 쓰고 64자를 넘기지 않습니다. 앤트로픽 공식 문서 기준으로 이름에 "claude"나 "anthropic"은 넣을 수 없습니다.

왜 파일을 나누나

한 파일에 다 넣으면 길어져서 AI가 지시를 잘 따르지 않습니다. 그래서 핵심 순서는 SKILL.md에 두고, 참고 문서는 필요할 때만 꺼내 쓰게 나눕니다. 앤트로픽은 SKILL.md 본문을 500줄 아래로 유지하고, 넘을 것 같으면 별도 파일로 나누라고 안내합니다. 참고 파일은 SKILL.md에서 바로 가리키게 하고, 참고 파일이 또 다른 파일을 가리키는 식으로 깊게 엮지 않습니다.

설명(description)은 검색어처럼 쓴다

AI는 등록된 모든 스킬의 이름과 설명을 먼저 읽고, 그중 어떤 스킬을 꺼낼지 고릅니다. 본문은 그 스킬을 고른 뒤에야 읽습니다. 그래서 설명은 검색 엔진에 걸리게 쓰는 글처럼 써야 합니다. 예를 들어 스킬을 만들어 주는 스킬이라면 "스킬 만들어 줘, 스킬 생성, 에이전트 스킬 같은 요청이 들어올 때 사용하는 스킬"처럼 적습니다.

설명을 쓸 때 지킬 점은 세 가지입니다.

• 무엇을 하는지와 언제 쓰는지를 함께 쓴다. 영어로 쓴다면 "Use when ~"으로 언제 쓰는지를 밝힌다.
• 작업 순서(워크플로)는 여기에 넣지 않는다. 순서는 본문에 쓴다.
• 사용자가 실제로 입력할 한국어⁠·영어 표현을 넣는다.

"이런 요청이 오면 항상 이 스킬을 쓴다"처럼 분명하게 쓰면 더 잘 불립니다. 흐릿하게 쓰면 AI가 다른 스킬을 고르거나 스킬 없이 일반 답변으로 처리합니다. 앤트로픽 문서는 "I can help you"처럼 1인칭으로 쓰지 말고 "주간 보고서를 작성한다"처럼 3인칭 서술로 쓰라고 권합니다. 설명 길이는 API 기준 1,024자까지지만, Claude 앱 도움말은 업로드하는 스킬의 설명을 200자 이내로 안내하니 앱에 올릴 스킬은 짧게 씁니다.

워크플로

본문에는 AI가 따라야 할 단계별 순서를 씁니다. 스킬을 만들어 주는 스킬이라면 첫 단계를 인터뷰로 두는 식입니다. 도메인(어떤 분야의 일인지)과 세부 도메인을 묻고, 목적과 입력⁠·출력을 확인하는 6단계 인터뷰 같은 구성입니다. 법무⁠·계약⁠·채용⁠·보안처럼 잘못되면 피해가 큰 분야는 "사람이 마지막에 검토한다"는 단계를 본문에 박아 둡니다. 이런 인터뷰 단계 수나 분야 목록은 스킬마다 정하는 것이지 정해진 규격은 아닙니다.

reference 폴더와 scripts 폴더

• reference 폴더: 본문이 길어질 때 쓰는 지식 창고입니다. 특정 단계에서 "이 파일을 읽어라"라는 지시를 받으면 그때 꺼내 읽습니다. 읽기 전까지는 컨텍스트(AI가 한 번에 기억하는 분량)를 차지하지 않습니다.
• scripts 폴더: 매번 같은 결과나 정확한 검증이 필요한 작업을 코드로 적어 둔 자동화 파일입니다. 라면 끓이는 기계처럼 넣으면 늘 같은 결과가 나옵니다. PPT 도형의 위치와 색을 코드로 정해 두는 경우가 예입니다. 본문에는 "이 스크립트를 실행한다"인지 "참고로 읽는다"인지 분명히 씁니다.

그럼 프롬프트는 의미가 없어졌나

아닙니다. 지시문 하나에 다 담을 수 없어서 SKILL.md와 reference·scripts로 나눈 것이고, 목적은 도구와 연결해 업무를 자동화하는 에이전트를 만드는 데 있습니다.

같은 AI에게 "이거 오를까 떨어질까"만 묻는 사람과, "손실을 줄이는 쪽으로 판단 기준을 먼저 세우고 근거⁠·위험⁠·확인할 지표 순서로 답해 줘"처럼 목표를 정의하고 답의 구조를 정해 주는 사람은 다른 답을 받습니다. 질문 설계의 차이를 보여 주는 예입니다. 질문과 지시 방식을 계속 고민하고 시험해야 하고, 스킬 제작도 에이전트 설계도 그 연장선입니다.

따라 하기: Claude·Codex에서 스킬 만들기 31단계

SKILL.md를 손으로 쓰지 않고 Claude나 Codex가 대화로 만들어 주는 방법입니다.

준비물

• Claude 계정과 Claude 앱(웹 또는 데스크톱). 스킬은 무료를 포함한 모든 요금제에서 쓸 수 있고, 설정 → 기능(Capabilities)에서 "코드 실행 및 파일 생성"(새 화면에서는 "파일 만들기 및 편집")이 켜져 있어야 합니다. Team·Enterprise는 관리자가 조직 설정에서 스킬을 켜 두어야 합니다. 메뉴 이름은 2026년 10월 기준입니다.
• (Codex로 만들 경우) Codex 앱 또는 CLI와 OpenAI 계정
• 만들고 싶은 스킬의 목적, 곧 어떤 일을 시킬지

1. Claude에서 대화로 스킬 만들기

1단계. Claude를 엽니다. - 확인: 왼쪽 사이드바에 "사용자 지정(Customize)" 항목이 보입니다.

2단계. "사용자 지정"을 클릭합니다. - 확인: 안에 "스킬" 항목이 보입니다.

3단계. "스킬"을 클릭합니다. - 확인: 내 스킬 목록이 열리고 위쪽에 "+" 버튼이 나타납니다.

4단계. "+"를 클릭하고 "스킬 만들기"를 고릅니다. - 확인: "Claude와 함께 만들기"와 "스킬 업로드" 같은 항목이 보입니다.

5단계. "Claude와 함께 만들기"를 클릭합니다. - 확인: 대화창이 나타납니다.

6단계. 원하는 스킬을 만들어 달라고 요청합니다. 예를 들면 "매주 금요일에 쓰는 주간 업무 보고서를 우리 팀 양식으로 정리해 주는 스킬 만들어 줘"처럼 씁니다. - 확인: Claude가 언제 쓸지, 어떤 양식인지 같은 확인 사항을 묻습니다.

7단계. Claude가 묻는 확인 사항에 하나씩 답합니다. - 확인: 요청한 스킬이 만들어집니다.

8단계. 완성된 스킬을 저장합니다. 대화 안에서 바로 내 스킬로 추가되면 9~12단계는 건너뜁니다. 파일로 받았다면 내려받습니다. - 확인: 스킬이 목록에 있거나, 스킬 파일(zip)이 내 컴퓨터에 저장됩니다.

2. Claude에 스킬 업로드하기

9단계. "사용자 지정"에서 "스킬"을 엽니다. - 확인: 스킬 목록이 열립니다.

10단계. "+"를 클릭하고 "스킬 만들기"를 고릅니다. - 확인: "스킬 업로드" 항목이 보입니다.

11단계. "스킬 업로드"를 선택합니다. - 확인: 파일을 고를 수 있습니다.

12단계. 스킬 파일을 골라 업로드합니다. zip 안에는 스킬 폴더가 맨 위에 있어야 하고(파일만 흩어 넣지 않는다), 폴더 이름은 스킬 이름과 같게 맞춥니다. - 확인: 업로드가 끝나면 스킬 목록에 등록되고 켜짐 상태가 됩니다.

13단계. (선택) 다른 사람이 공유한 스킬 파일도 같은 방법으로 업로드합니다. 받은 파일은 올리기 전에 SKILL.md와 scripts 폴더를 열어 무엇을 하는지 읽어 봅니다. - 확인: 목록에 그 스킬이 보입니다.

올린 스킬을 끄려면 사용자 지정 → 스킬에서 스킬 옆 토글을 끕니다. 지우려면 스킬을 눌러 오른쪽 위 토글을 끈 뒤 "…" → 삭제를 누릅니다.

클로드 코드를 쓴다면 스킬 폴더를 ~/.claude/skills/스킬이름/SKILL.md 자리에 두면 모든 프로젝트에서, 프로젝트 안 .claude/skills/스킬이름/SKILL.md 자리에 두면 그 프로젝트에서만 쓰입니다. SKILL.md가 한 단계 더 안쪽 폴더에 들어가 있으면 인식되지 않습니다. 입력창에 /skills를 치면 목록에서 확인할 수 있고, 지울 때는 그 스킬 폴더를 지웁니다.

3. Codex에서 스킬 화면으로 만들기

14단계. 검색창에 "Codex"를 검색합니다. - 확인: OpenAI의 Codex 안내 페이지가 보입니다.

15단계. OpenAI 공식 사이트로 들어갑니다. - 확인: 다운로드 안내가 보입니다.

16단계. 내 운영체제(윈도우⁠·맥)에 맞는 버전을 내려받습니다. - 확인: 설치 파일이 내려받아집니다.

17단계. 파일을 설치합니다. - 확인: 설치가 끝납니다.

18단계. Codex 프로그램을 실행하고 OpenAI 계정으로 로그인합니다. - 확인: Codex 화면이 나옵니다.

19단계. 사이드바에서 스킬 화면을 엽니다. - 확인: 프로젝트에 깔린 스킬 목록이 보입니다.

20단계. 새 스킬 만들기(Create) 버튼을 클릭합니다. 버튼이 보이지 않으면 21단계처럼 대화창에서 $skill-creator를 불러도 같습니다. - 확인: 새 스킬을 만드는 대화가 열립니다.

21단계. Codex에게 만들고 싶은 스킬을 대화로 요청합니다. - 확인: Codex가 스킬이 무엇을 하는지, 언제 불려야 하는지 묻고 스킬을 만듭니다.

4. Codex에서 슬래시로 만들기

22단계. 대화창에서 슬래시(/)를 입력합니다. - 확인: 명령 목록이 나옵니다.

23단계. skills를 입력해 스킬 목록을 엽니다. - 확인: 쓸 스킬을 고를 수 있는 목록이 나옵니다.

24단계. 목록에서 skill-creator(스킬 크리에이터)를 고릅니다. 대화창에 $skill-creator라고 직접 적어도 됩니다. - 확인: skill-creator가 선택됩니다.

25단계. 만들고 싶은 스킬을 요청합니다. - 확인: 스킬 생성 대화가 진행됩니다. Codex는 기본으로 지시문만 있는 스킬을 만들고, 스크립트는 필요할 때만 넣습니다.

Claude와 Codex 모두 요즘은 스킬 만드는 과정이 잘 정리돼 있어서, 처음에는 어느 쪽이든 대화로 만드는 편이 빠릅니다.

5. 만든 스킬 점검하고 고치기

26단계. 만들어진 스킬이 좋은지 검토합니다. - 주의: 잘 모르는 분야라면 AI가 그럴듯하게 만들어도 좋은지 판단하기 어렵습니다. 그 분야의 기초 지식, 적어도 그 분야에서 쓰는 말은 익혀 둬야 합니다. - 확인: 스킬 내용이 맞는지 내 말로 설명할 수 있습니다.

27단계. AI에게 깃허브에 공개된 스킬 중 내 분야에서 참고할 좋은 예시를 찾아 달라고 합니다.

내가 만들려는 스킬은 주간 업무 보고서 작성용이야. 깃허브에 공개된 스킬 가운데 이 분야에서 참고할 만한 좋은 예시를 찾아서 구조를 비교해 줘.

• 확인: 참고할 스킬 예시 목록이 나옵니다.

28단계. 찾은 스킬의 SKILL.md를 읽어 구조를 파악합니다. - 확인: 내 스킬에 가져다 쓸 부분을 정했습니다.

29단계. 스킬을 실제 업무에 써 봅니다. 그 스킬이 불려야 할 요청을 서너 가지 말투로 바꿔 보내 봅니다. - 확인: 스킬이 불렸는지, 결과가 기대와 맞는지 알 수 있습니다. Claude 앱에서는 생각 과정에 스킬을 읽는 줄이 보이는지로 확인합니다.

30단계. 부족한 점을 고치고 보완합니다. 안 불렸다면 설명을, 결과가 틀렸다면 본문 순서를 고칩니다. - 확인: 고친 스킬이 저장됩니다.

31단계. 다시 써 보고 다시 고칩니다. 이 과정을 반복합니다. - 주의: 어떤 스킬도 한 번에 완벽하지 않습니다. 써 보고 고치는 반복이 스킬을 완성하는 방법입니다. - 확인: 반복할수록 결과가 내 기준에 가까워집니다.

끝나고 점검할 것

• Claude나 Codex에서 스킬이 만들어졌다.
• (Claude) 스킬 목록에 새 스킬이 등록되고 켜져 있다.
• 스킬 설명에 "언제 쓰는지"가 실제로 입력할 한국어⁠·영어 표현과 함께 적혀 있다.
• 대화창에서 요청만 했을 때 그 스킬이 불리는지 확인했다.
• 결과를 보고 한 번 이상 고쳤다.

스킬이 잘 안 될 때

스킬이 불리지 않고 일반 답변만 나온다

설명(description)이 흐릿하면 AI가 다른 스킬을 고르거나 일반 답변으로 처리합니다. 설명에 "이런 요청이 오면 이 스킬을 쓴다"를 분명히 쓰고, 사용자가 실제로 입력할 한국어⁠·영어 표현을 넣습니다. 급할 때는 "주간 보고 스킬 써서 정리해 줘"처럼 스킬을 직접 언급합니다.

만든 스킬이 좋은지 모르겠다

그 분야 지식이 부족해서일 수 있습니다. 기초 지식을 쌓고, 깃허브의 좋은 스킬 예시를 참고합니다(27·28단계).

AI가 지시를 잘 따르지 않는다

한 파일에 내용이 너무 길어졌을 수 있습니다. 핵심 순서는 SKILL.md에, 참고 문서는 reference 폴더에 나눠 둡니다.

직접 만들어야 자산이 된다

남이 만든 스킬을 가져다 쓰기만 하면 내 업무를 구조화해 보는 경험이 쌓이지 않습니다. 직접 만들고 고치면서 정리한 업무 순서와 기준이 남는 자산입니다. 처음에는 매주 반복하는 일 하나를 골라 스킬로 만들어 보는 것으로 시작합니다.