Claude 스킬 직접 만들기: SKILL.md 한 장으로 반복 업무를 맡기는 법

매주 월요일마다 같은 형식의 보고서를 쓰는데, 매번 "지난번처럼 항목 나눠서, 톤은 간결하게, 숫자는 표로 정리해 줘"라는 긴 지시문을 복사해 붙여넣고 있다면 이 글이 맞습니다. 같은 지시문을 반복해서 쓰는 대신 한 번만 정의해 두고, 관련 주제가 나올 때 Claude가 알아서 찾아 쓰게 하는 방법이 스킬입니다.

이번 달 Anthropic이 에이전트 스킬을 리눅스 재단 산하 Agentic AI Foundation에 기부해 열린 표준으로 만든다는 소식도 나왔습니다. 공개 표준이 되었다는 것은 같은 형식의 스킬을 여러 도구에서 재사용할 가능성이 커졌다는 뜻이라, 지금 파일 구조를 익혀 두면 나중에 손해가 없습니다. 이 글에서는 스킬의 핵심인 SKILL.md 파일을 직접 쓰는 과정을 한 번 따라 해 보겠습니다.

스킬과 프롬프트는 무엇이 다른가요

프롬프트는 대화 한 번을 위한 지시문입니다. 대화가 끝나면 사라지고, 다음에 쓰려면 다시 찾아 붙여넣어야 합니다. 스킬은 폴더 하나에 담긴 지침 묶음입니다. 핵심 차이는 Claude가 스킬의 이름과 설명만 먼저 보고, 지금 하는 일과 맞을 때만 본문을 읽는다는 점입니다. 그래서 스킬을 여러 개 만들어 두어도 대화가 쓸데없이 길어지지 않습니다.

정리하면 이렇습니다. 한두 번 쓰고 말 요청은 프롬프트로 충분합니다. 같은 절차를 매주, 매달 반복하고 매번 같은 기준을 지켜야 하는 일은 스킬로 만들 가치가 있습니다. 예를 들어 주간 보고서 작성, 회의록에서 결정 사항 뽑기, 고객사 메일 톤 맞추기 같은 일이 여기에 해당합니다.

SKILL.md의 구조: 머리말과 본문

스킬의 중심은 SKILL.md 파일 하나입니다. 파일 맨 위에는 머리말(frontmatter)이 있고, 그 아래에 실제 지침을 적습니다. 머리말에는 이름과 설명, 두 줄이 필수입니다.

---
name: weekly-report
description: 팀원들의 주간 업무 메모를 받아 상위 보고용 주간 보고서를 만들 때 사용. "주간 보고", "이번 주 보고서", "업무 메모 정리" 요청에 적용.
---

# 주간 보고서 작성 절차

1. 메모를 프로젝트별로 묶는다.
2. 각 프로젝트마다 진행률, 완료 항목, 막힌 점, 다음 주 계획을 나눈다.
3. 막힌 점에는 필요한 도움과 요청 대상을 함께 적는다.
4. 숫자가 없는 항목은 추측하지 말고 "수치 미확인"으로 표시한다.
5. 전체 분량은 A4 한 장 안쪽으로 맞춘다.

여기서 가장 중요한 부분은 description입니다. Claude는 이 설명을 읽고 스킬을 쓸지 판단하므로, 언제 쓰는지와 어떤 말에 반응해야 하는지를 구체적으로 적어야 합니다. 반대로 본문은 짧고 명확한 절차로 쓰는 것이 좋습니다. 본문에 "최고의 보고서를 작성하라"처럼 모호한 말을 넣으면 결과도 모호해집니다.

실제로 만들어 보기: 주간 보고서 스킬

먼저 Claude에게 스킬의 초안을 쓰게 하면 빠릅니다. 지금까지 쓰던 지시문과 잘 나온 보고서 예시 한 개를 함께 주고, 아래처럼 요청해 보세요.

아래는 내가 매주 쓰는 보고서 지시문과 지난주 완성본이다.
이 내용을 바탕으로 SKILL.md 초안을 만들어 줘.

조건:
- 머리말에 name과 description을 넣는다. description에는 이 스킬을 쓸 상황과 요청 문구 예시를 3개 이상 적는다.
- 본문은 번호 매긴 절차 5~7단계로 쓴다.
- 지시문에 없던 기준은 새로 만들지 말고, 빈칸으로 두고 나에게 물어볼 항목으로 따로 적는다.

[지시문]
...

[지난주 완성본]
...

이렇게 받은 초안을 그대로 쓰기보다, 실제 메모 두세 개를 넣어 보며 빠진 기준을 채우는 편이 낫습니다. 초안에 "수치 미확인은 표시한다"처럼 한 번 실수한 내용을 넣어 두면, 다음부터 같은 실수가 줄어듭니다.

스킬 파일이 완성되면 다음처럼 평소 쓰던 말로 요청합니다.

이번 주 업무 메모 세 개를 붙여 넣을게.
이번 주 보고 형식으로 정리해 줘.
막힌 점에는 누구에게 무엇을 요청해야 하는지도 적어 줘.

스킬이 제대로 불러졌다면 응답은 이렇게 나옵니다. 아래는 예시입니다.

[주간 보고서 - 10월 4주차]

1. 신규 고객 제안서
 - 진행률: 약 70%
 - 완료: 가격표 초안, 경쟁사 비교 항목
 - 막힌 점: 법무 검토 일정 미정 → 법무팀에 목요일 전 검토 요청
 - 다음 주: 제안서 본문 초안 공유

2. 내부 교육 자료
 - 진행률: 수치 미확인
 - 완료: 목차 확정
 - 다음 주: 강사 일정 확인

여기서 핵심은 "수치 미확인"처럼 근거가 없는 값을 채우지 않는 것입니다. 보고서는 틀린 숫자 하나가 신뢰를 무너뜨리기 때문에, 스킬에 이 원칙을 명시해 두는 것만으로도 효과가 큽니다.

description을 잘 쓰는 법

스킬이 엉뚱한 때 불리거나, 필요한 때 안 불리는 문제는 대부분 description 때문입니다. 좋은 설명에는 세 가지가 들어 있습니다. 첫째, 이 스킬이 하는 일을 한 문장으로 적습니다. 둘째, 사용자가 실제로 쓸 법한 요청 문구를 따옴표로 넣습니다. 셋째, 반대로 쓰지 말아야 할 상황을 한 줄로 적습니다. 예를 들어 주간 보고서 스킬이라면 "월간 보고나 프로젝트 기획서에는 사용하지 않음"이라고 적어 두면 오작동이 줄어듭니다.

반대로 "업무를 도와주는 스킬"처럼 넓은 설명은 거의 모든 요청에 붙어 버려 효과가 없습니다. 설명 한 줄을 고치는 데 몇 분이면 충분하니, 처음 몇 번은 설명을 집중해서 다듬어 보세요.

테스트하고 고치는 순서

스킬은 만들고 끝나는 파일이 아니라 몇 번 돌려 보며 다듬는 파일입니다. 저는 세 가지 테스트를 권합니다. 첫 번째는 정상 사례입니다. 평소와 비슷한 메모를 넣고 결과가 형식에 맞는지 봅니다. 두 번째는 까다로운 사례입니다. 메모가 두 줄뿐이거나, 같은 항목이 두 번 나오거나, 수치가 빠진 경우를 넣어 봅니다. 세 번째는 경계 사례입니다. 보고서가 아닌 요청을 했을 때 스킬이 괜히 불리지 않는지 확인합니다.

결과가 기대와 다르면 본문 절차를 고치기 전에 먼저 원인을 찾으세요. 스킬이 안 불렸다면 description 문제이고, 불렸는데 결과가 틀렸다면 본문 절차에서 기준이 빠진 것입니다. 원인을 구분해서 고쳐야 같은 문제가 다시 생기지 않습니다.

또 하나 중요한 점은 스킬을 한 번에 여러 개 만들지 않는 것입니다. 보고서, 회의록, 메일처럼 역할이 다른 스킬 세 개를 한꺼번에 만들면 어느 것이 불렸는지 확인하기 어렵습니다. 하나를 완성해서 한 달 정도 쓴 뒤에 다음 스킬로 넘어가는 편이 훨씬 안정적입니다.

공유할 때 주의할 점

스킬을 팀과 나눌 때는 지침 안에 개인 정보나 고객 이름, 내부 수치를 넣지 않도록 주의해야 합니다. 예시 보고서를 넣을 때도 실명과 금액은 가상의 값으로 바꾸세요. 스킬은 파일이므로 한 번 공유되면 회수하기 어렵습니다. 대신 절차와 형식 기준만 담으면 팀원 누구나 자기 상황에 맞게 바꿔 쓸 수 있습니다.

한눈에 정리

반복되는 업무는 프롬프트 대신 스킬로 정의해 두면 매번 지시문을 붙여넣을 필요가 없습니다. SKILL.md는 이름과 설명을 적은 머리말과 짧은 절차 본문으로 구성합니다. 설명에는 쓰는 상황과 요청 문구를 구체적으로 넣고, 본문에는 모호한 말 대신 번호 절차를 적습니다. 완성한 뒤에는 정상, 까다로운, 경계 사례로 테스트하며 설명과 절차를 나눠서 고칩니다.

자주 묻는 질문

Q. 스킬은 프롬프트와 비교해 무엇이 가장 큰 장점인가요? A. 같은 지침을 매번 붙여넣지 않아도 되고, 관련 상황에서 Claude가 스스로 찾아 쓴다는 점입니다. 긴 지침을 항상 대화에 싣지 않아도 되어 대화도 가벼워집니다.

Q. SKILL.md는 꼭 영어로 써야 하나요? A. 아닙니다. 본문은 한국어로 써도 됩니다. 다만 머리말의 name은 영문 소문자와 하이픈으로 쓰는 것이 일반적이고, description에는 실제로 쓸 한국어 요청 문구를 함께 넣어 두면 불리는 정확도가 올라갑니다.

Q. 스킬이 생각한 것보다 자주 불리거나 안 불리면 어떻게 하나요? A. 먼저 description을 확인하세요. 너무 넓으면 쓰지 않을 때도 불리고, 너무 좁으면 요청 문구가 조금만 달라도 안 불립니다. 요청 문구 예시를 3개 이상 넣고 쓰지 말아야 할 상황을 한 줄 적으면 대부분 해결됩니다.