클로드 코드 스킬 만드는 법 2026 — SKILL.md 작성 공식 가이드
AI에게 같은 지시를 세 번째 반복하고 있다면, 절차를 저장해 두는 클로드 코드 스킬의 구조와 SKILL.md 작성법을 정리했습니다.
스킬은 반복해서 시키는 절차를 SKILL.md 파일 하나에 저장해 두고 클로드가 필요할 때 읽어 쓰게 하는 기능입니다. 같은 부탁을 세 번 했다면 만들 때이고, 설명 한 줄을 잘 쓰는 것이 스킬의 절반입니다.
이 대화에서 내가 세 번 이상 반복해서 시킨 절차가 있는지 찾아 줘. 있으면 그중 하나를 골라 SKILL.md 초안을 만들어 줘. - 파일 첫 줄은 대시 세 개로 시작하는 프런트매터 - description에는 "무엇을 하는지"와 "언제 쓰는지"를 모두 담기 - 본문에는 내가 평소 말로 시키던 절차를 순서대로 적기 어느 폴더에 두면 되는지도 알려 줘.
AI에게 같은 지시를 세 번째 타이핑하고 있다면 이 글을 읽어야 합니다. 그건 규칙이 아니라 절차이고, 절차는 스킬로 만들어 두면 반복을 없앨 수 있습니다. 공식 문서 기준으로 스킬이 무엇이고 어떻게 만드는지 정리했습니다.
스킬이란 무엇인가
스킬은 "이럴 때 이렇게 해줘"라는 지침을 파일 하나에 저장해 두고, 클로드가 필요하다고 판단할 때 알아서 읽어 쓰는 기능입니다. 공식 문서는 스킬을 재사용 가능한 파일 기반 자원으로, 범용 에이전트를 전문가로 바꿔 주는 작업 절차와 맥락, 모범 사례라고 설명합니다. 만드는 데 필요한 것은 폴더 하나와 텍스트 파일 하나뿐입니다.
같은 설명을 반복하고 있다면 그건 규칙이 아니라 절차입니다. 절차는 규칙 파일에 넣기엔 길고, 매번 말로 설명하기엔 깁니다. 그 중간을 메우는 것이 스킬입니다.
폴더를 만들고 둘 곳을 정한다
스킬은 폴더 하나이고, 그 안에 SKILL.md 파일이 들어갑니다. 두는 곳은 범위에 따라 나뉩니다. 개인용은 사용자 폴더의 스킬 폴더에 두어 이 컴퓨터의 모든 프로젝트에서 읽히고, 프로젝트용은 저장소 안의 스킬 폴더에 두어 그 저장소에서만 읽히며 커밋하면 팀과 공유됩니다.
플러그인에 담아 배포할 수도 있습니다. 공식 문서는 파일 기반이라 업로드가 필요 없다고 못 박습니다.
SKILL.md의 설명부터 쓴다
파일은 맨 위 설명(프런트매터)과 본문 두 부분으로 나뉩니다. 프런트매터는 대시 세 개로 둘러싼 부분이며, 파일 첫 줄이 대시 세 개여야 인식됩니다.
가장 중요한 항목은 description입니다. 공식 문서는 description이 클로드가 이 스킬을 실행할지 판단할 때 요청과 대조하는 대상이므로, 스킬이 무엇을 하는지와 언제 쓰는지를 모두 담아야 한다고 설명합니다. 설명을 잘 쓰는 것이 스킬의 절반입니다.
본문에는 평소 말로 시키던 절차를 그대로 적습니다.
새 대화에서 불리는지 확인한다
새 대화를 열고 관련된 요청을 해서 확인하며, 확실히 부르고 싶으면 슬래시 명령으로 직접 부를 수도 있습니다.
첫 스킬이 안 불리는 경우는 대개 본문이 아니라 설명 한 줄이 원인입니다. "무엇을 하는지"만 적고 "언제 쓰는지"를 적지 않으면 클로드가 판단할 수 없습니다. 서브에이전트를 만들 때도 설명 한 줄이 위임을 좌우하는 점은 같습니다. 언제 쓰는지를 넣고 나면 대개 바로 불립니다.
운영자 한마디
스킬을 만들 때 가장 많이 놓치는 것은 본문이 아니라 description 한 줄입니다. "블로그 글을 쓴다" 정도로만 적어 두면 클로드가 언제 불러야 할지 판단할 근거가 없습니다. 무엇을 하는지와 더불어 어떤 상황·어떤 요청에서 써야 하는지를 구체적으로 적어야 실제로 불립니다.
또 하나 놓치기 쉬운 지점은 남이 만든 스킬을 받을 때입니다. 스킬은 절차를 담고 있고 그 절차 안에는 명령 실행이 들어갈 수 있으므로, 기능이 좋아 보인다고 바로 쓰지 말고 출처부터 확인하는 습관이 필요합니다. 직접 만들었거나 신뢰할 수 있는 출처의 스킬만 쓰는 것이 안전합니다.
자주 하는 실수
스킬은 클로드가 설명을 보고 관련이 있다고 판단할 때 부릅니다. 확실하게 통제하려면 자동 호출을 차단하는 설정으로 수동 호출만 남기거나, 특정 파일을 다룰 때만 불리게 범위를 좁힐 수 있습니다.
이름과 설명만 항상 올라가 있고, 본문은 실제로 불릴 때, 함께 넣어 둔 참고 파일과 스크립트는 실제로 참조될 때 읽힙니다. 스킬 설명 목록은 모델 컨텍스트 창의 1%를 예산으로 쓰며, 넘치면 덜 쓰는 스킬부터 설명이 잘립니다.
공식 문서는 커스텀 스킬이 표면 간에 동기화되지 않는다고 명시합니다. 웹에 올린 것과 코드 도구의 파일은 별개이므로, 원본 폴더를 하나만 두고 나머지는 그 폴더를 가리키게 정리하는 편이 안전합니다.
자주 묻는 질문
설명은 몇 자까지 쓸 수 있나요?
클로드 코드 문서는 description과 when_to_use를 합쳐 1,536자까지라고 안내합니다. API·웹용 스킬 규격 문서는 이름 64자, 설명 1,024자로 다르게 적혀 있으므로, 쓰는 환경에 맞는 문서를 확인하는 편이 안전합니다.
스킬을 몇 개까지 만들 수 있나요?
개수 상한은 공식 문서에서 확인되지 않았습니다. 다만 설명 목록에 예산이 있으므로 안 쓰는 스킬을 쌓아 두는 것은 이득이 없습니다.
규칙 파일과 뭐가 다른가요?
규칙 파일은 항상 읽히는 짧은 원칙이고, 스킬은 필요할 때만 열리는 절차서입니다. 길어지는 절차를 규칙 파일에 넣으면 둘 다 나빠집니다.
정리
같은 부탁을 세 번 했다면 그때 파일로 만드는 것이 기준입니다. 설명 한 줄을 잘 쓰는 것이 그 파일의 절반이며, 최신 글자 수 규격은 공식 문서에서 확인하는 것이 가장 안전합니다.