[스킬] Claude Code 스킬 만들기: SKILL.md 구조와 저장 위치

안녕하세요, muaco입니다.

무엇을 만드나

이 글에서는 Claude Code에 나만의 스킬 하나를 직접 만들어 넣습니다. 스킬은 SKILL.md라는 파일 하나와 그 파일을 담은 폴더입니다. 한 번 만들어 두면 같은 지시문을 매번 채팅창에 붙여 넣지 않아도 되고 관련된 요청이 들어올 때 Claude가 알아서 그 파일을 찾아 읽습니다. 끝까지 따라 하면 개인 스킬 한 개가 생기고 슬래시 명령 /스킬이름으로 직접 부를 수도 있습니다.

이 글은 2026년 9월 기준 Anthropic 공식 문서를 따릅니다. 버전에 따라 동작이 갈리는 항목은 본문에 버전을 함께 적었습니다.

먼저 갖춰야 할 준비물

• Claude Code가 설치된 컴퓨터. 터미널(명령을 글자로 쳐서 컴퓨터를 부리는 창)에서 claude를 쳤을 때 실행되면 됩니다.
• 텍스트 편집기. 스킬은 마크다운(#이나 - 같은 기호 몇 개로 제목과 목록을 표시하는 간단한 문서 형식) 파일 하나라 메모장 수준의 편집기로 충분합니다.
• git 저장소와 커밋하지 않은 변경. 이 글이 만드는 예제 스킬은 git diff HEAD를 실행합니다. 문서도 시험 전에 git 프로젝트를 열고 아무 파일이나 조금 고쳐 두라고 안내합니다.
• 터미널 사용 환경. 스킬 본문에서 셸 명령을 쓰려면 bash가 필요합니다. 문서는 Git Bash가 없는 윈도우에서 shell: bash를 지정한 스킬이 명령 실행 전에 실패한다고 밝힙니다.
• 요금제. Claude Code의 스킬은 내 컴퓨터의 파일이라 별도 업로드가 필요 없습니다. 다만 claude.ai에 커스텀 스킬을 올리는 경로는 Pro, Max, Team, Enterprise 플랜에서 코드 실행이 켜져 있어야 한다고 문서에 나옵니다.

따라 하기

1단계. 폴더 만들기

1. 터미널을 열고 폴더를 만듭니다. 공식 문서의 예제를 그대로 씁니다. mkdir -p ~/.claude/skills/summarize-changes
   여기에 두는 이유는 ~/.claude/skills/가 개인 스킬 자리라서입니다. 어느 프로젝트에서 Claude Code를 켜도 따라옵니다. 폴더 이름이 곧 명령 이름이 되므로 나중에 /summarize-changes로 부르게 됩니다.
2. 만들어졌는지 봅니다. ls ~/.claude/skills를 쳐서 방금 만든 이름이 보이면 됩니다.

2단계. SKILL.md 쓰기

1. 폴더 안에 SKILL.md를 만듭니다. 파일은 두 부분입니다. 위쪽 --- 사이에 들어가는 YAML 머리말이 "언제 쓰는 스킬인지"를 알려주고 그 아래 마크다운 본문이 "무엇을 하라"는 지시입니다. 아래는 공식 문서의 예제입니다.

   ---
   description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
   ---
   Current changes
   !git diff HEAD
   Instructions
   Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

   느낌표로 시작하는 줄은 Claude Code가 먼저 실행해 결과로 바꿔치기한 다음 Claude에게 넘깁니다. 덕분에 지시문이 도착할 때 이미 현재 변경 내역이 안에 들어가 있습니다.
2. 머리말의 ---를 파일 첫 줄에 둡니다. 문서는 여는 ---가 첫 줄일 때만 머리말로 읽는다고 못 박습니다. 앞에 빈 줄이나 제목이 있으면 ---까지 통째로 본문 취급을 받습니다.
3. description을 손봅니다. 여기가 성패를 가릅니다. Claude는 이 한 줄만 보고 스킬을 부를지 판단합니다. 문서는 세 가지를 권합니다. 무엇을 하는지와 언제 쓰는지를 함께 적고 3인칭으로 쓰고("Processes Excel files and generates reports"), 사용자가 실제로 입에 올릴 단어를 넣습니다. "Helps with documents" 같은 문장은 피하라고 예시까지 들어 있습니다.
4. 이름 규칙을 지킵니다. name 필드는 소문자와 숫자, 하이픈만 쓰고 64자를 넘기지 않습니다. "anthropic"과 "claude"는 예약어라 쓸 수 없습니다. Claude Code에서는 name이 필수가 아니고 생략하면 폴더 이름을 씁니다. 반면 claude.ai 업로드나 Skills API 경로에서는 name과 description이 필수입니다.
5. 여기서 바로 검사합니다. 머리말 YAML이 깨져도 파일은 조용히 실려서 다음 단계까지 가서야 이상을 눈치채기 쉽습니다. v2.1.233 이상이면 claude plugin validate ~/.claude/skills로 그 자리에서 깨진 파일을 찾을 수 있습니다. 그 아래 버전이면 --debug로 실행해 파싱 오류가 찍히는지 봅니다.

3단계. 불러서 확인하기

1. git 저장소 폴더에서 Claude Code를 켜고 목록을 확인합니다. 예제 스킬이 git diff HEAD를 쓰므로, git으로 관리되는 프로젝트 폴더에서 아무 파일이나 조금 고쳐 둔 뒤 claude로 실행합니다. 그다음 "What skills are available?"라고 물으면 됩니다. 방금 만든 이름이 목록에 있어야 다음 단계가 의미가 있습니다.
2. 직접 불러 봅니다. /summarize-changes를 칩니다. 파일 본문의 지시대로 답이 나오면 파일 자체는 정상입니다.
3. 자동 호출을 시험합니다. 이번에는 명령 대신 "What did I change?"처럼 설명과 맞아떨어지는 문장을 던집니다. 여기서 스킬이 안 걸리면 파일이 아니라 description이 문제입니다.
4. 저장 위치를 정합니다. 혼자 쓸지 팀과 나눌지에 따라 자리가 다릅니다.

프로젝트 스킬은 저장소에 함께 커밋해 동료와 나눌 수 있습니다. 이름이 겹치면 개인 스킬이 프로젝트 스킬을 이깁니다. 즉 내 홈 폴더에 같은 이름이 있으면 팀 스킬 대신 내 스킬이 돕니다.

언제 스킬로 빼면 이득인가

문서가 제시하는 기준은 명확합니다. 같은 지시나 체크리스트, 여러 단계짜리 절차를 대화창에 계속 다시 붙여 넣고 있을 때입니다. CLAUDE.md의 한 대목이 사실 정리를 넘어 절차로 자라났을 때도 옮길 때가 된 신호입니다. CLAUDE.md 내용과 달리 스킬 본문은 실제로 쓰일 때만 읽히기 때문에, 긴 참고 자료를 넣어둬도 부르기 전까지는 비용이 거의 없습니다.

비용 감각은 이렇습니다. 시작 시점에는 스킬당 이름과 설명 약 100토큰이 늘 올라갑니다. 본문은 불렸을 때 들어가며 문서는 5천 토큰 미만, 500줄 이하를 권합니다. 넘어가면 별도 파일로 쪼개고 SKILL.md에서 링크로 가리키는 방식을 씁니다. 참고 파일은 한 단계 깊이까지만 연결하라는 지침도 있습니다. 링크의 링크를 타고 들어가면 Claude가 파일을 일부만 읽고 넘어갈 수 있습니다.

막히기 쉬운 곳

• 스킬이 안 불립니다. 순서대로 확인합니다. 설명에 사용자가 실제로 쓸 단어가 들어 있는지, 목록에 스킬이 뜨는지, 요청 문장을 설명에 가깝게 바꾸면 걸리는지 봅니다. 머리말 YAML이 깨졌으면 본문은 빈 메타데이터로 실려 /스킬이름은 되는데 자동 호출만 안 됩니다. 2단계 마지막의 검사 명령으로 잡습니다.
• /summarize-changes가 오류로 끝납니다. 이 스킬은 git diff HEAD를 먼저 실행하는데, git 저장소가 아닌 폴더에서 켰다면 그 명령이 실패하고 문서 기준으로 스킬 호출 자체가 중단됩니다. git 프로젝트 폴더에서 다시 켜세요.
• 부르지도 않았는데 자꾸 끼어듭니다. 설명을 더 좁게 고치거나, 머리말에 disable-model-invocation: true를 넣어 사람이 칠 때만 돌게 합니다. 배포나 전송처럼 부작용이 있는 작업에 특히 권장됩니다.
• 스킬이 늘어나자 설명이 잘립니다. Claude Code는 스킬 이름과 설명 목록을 문맥에 싣는데, 예산은 모델 문맥 창의 1%입니다. 넘치면 덜 쓰는 스킬부터 설명을 떨어뜨립니다. /doctor로 비용과 주범을 확인합니다.
• 파일을 고쳤는데 반영이 안 됩니다. Claude Code는 스킬 폴더의 변경을 세션 중에 감지합니다. 다만 세션 시작 시점에 아예 없던 최상위 스킬 폴더를 새로 만들었다면 재시작해야 합니다. 실시간 감지는 SKILL.md 텍스트만 대상입니다.
• 예약 실행에서 스킬을 못 찾습니다. Cowork 세션과 클라우드 세션은 내 컴퓨터의 ~/.claude/skills/를 읽지 않습니다. 저장소의 .claude/skills/에 커밋하거나 claude.ai 계정 쪽에 올려야 합니다.

여기서 더 나아가려면

다음 단계는 스킬을 하나 더 만드는 쪽이 아니라, 만든 스킬을 실제 업무에 며칠 써보고 다듬는 쪽입니다. 문서는 평가 시나리오를 세 개쯤 먼저 만들고 스킬 없이 돌려본 결과와 비교하며 고쳐 나가라고 권합니다. 익숙해지면 폴더 안에 참고 문서와 스크립트를 함께 넣어보세요. 스크립트는 내용이 문맥에 실리지 않고 실행 결과만 들어오므로, 매번 코드를 새로 짜게 하는 방식보다 안정적입니다. 다만 출처가 불분명한 스킬은 설치하지 마세요. 스킬은 Claude에게 도구를 쓰라고 시키는 지시문이라 소프트웨어를 설치하듯 다뤄야 합니다.

이상으로 글 마치겠습니다.

출처

• Agent Skills 개요 (Claude Platform Docs)
• Extend Claude with skills (Claude Code Docs)
• Skill authoring best practices (Claude Platform Docs)