클로드 코드 스킬 만드는 법 2026 — SKILL.md 작성 공식 가이드

스킬은 "이럴 때 이렇게 해줘"라는 지침을 파일 하나에 저장해 두고, 클로드가 필요하다고 판단할 때 알아서 읽어 쓰는 기능입니다. 공식 문서는 스킬을 재사용 가능한 파일 기반 자원으로, 범용 에이전트를 전문가로 바꿔 주는 작업 절차와 맥락, 모범 사례라고 설명합니다. 만드는 데 필요한 것은 폴더 하나와 텍스트 파일 하나뿐입니다.

같은 설명을 반복하고 있다면 그건 규칙이 아니라 절차입니다. 절차는 규칙 파일에 넣기엔 길고, 매번 말로 설명하기엔 깁니다. 그 중간을 메우는 것이 스킬입니다.

스킬은 폴더 하나이고, 그 안에 SKILL.md 파일이 들어갑니다. 파일은 맨 위 설명(프런트매터)과 본문 두 부분으로 나뉩니다. 프런트매터는 대시 세 개로 둘러싼 부분이며, 파일 첫 줄이 대시 세 개여야 인식됩니다.

가장 중요한 항목은 description입니다. 공식 문서는 description이 클로드가 이 스킬을 실행할지 판단할 때 요청과 대조하는 대상이므로, 스킬이 무엇을 하는지와 언제 쓰는지를 모두 담아야 한다고 설명합니다. 설명을 잘 쓰는 것이 스킬의 절반입니다.

두는 곳은 범위에 따라 나뉩니다. 개인용은 사용자 폴더의 스킬 폴더에 두어 이 컴퓨터의 모든 프로젝트에서 읽히고, 프로젝트용은 저장소 안의 스킬 폴더에 두어 그 저장소에서만 읽히며 커밋하면 팀과 공유됩니다. 플러그인에 담아 배포할 수도 있습니다. 공식 문서는 파일 기반이라 업로드가 필요 없다고 못 박습니다.

폴더를 만들고, 그 안에 SKILL.md를 만들어 맨 위에 설명을 씁니다. 본문에는 평소 말로 시키던 절차를 그대로 적습니다. 새 대화를 열고 관련된 요청을 해서 확인하며, 확실히 부르고 싶으면 슬래시 명령으로 직접 부를 수도 있습니다.

첫 스킬이 안 불리는 경우는 대개 본문이 아니라 설명 한 줄이 원인입니다. "무엇을 하는지"만 적고 "언제 쓰는지"를 적지 않으면 클로드가 판단할 수 없습니다. 언제 쓰는지를 넣고 나면 대개 바로 불립니다.

스킬은 만들어 두면 자동으로 늘 돌아가는 것이 아닙니다. 클로드가 설명을 보고 관련이 있다고 판단할 때 부릅니다. 확실하게 통제하려면 자동 호출을 차단하는 설정으로 수동 호출만 남기거나, 특정 파일을 다룰 때만 불리게 범위를 좁힐 수 있습니다.

스킬 본문이 항상 대화에 실려 있는 것도 아닙니다. 이름과 설명만 항상 올라가 있고, 본문은 실제로 불릴 때, 함께 넣어 둔 참고 파일과 스크립트는 실제로 참조될 때 읽힙니다. 관련해서 스킬 설명 목록은 모델 컨텍스트 창의 1%를 예산으로 쓰며, 넘치면 덜 쓰는 스킬부터 설명이 잘립니다.

어디서나 똑같이 돌아가지도 않습니다. 공식 문서는 커스텀 스킬이 표면 간에 동기화되지 않는다고 명시합니다. 웹에 올린 것과 코드 도구의 파일은 별개이며, 한쪽을 고쳤다고 다른 쪽이 따라 바뀌지 않습니다. 여러 곳에서 같은 스킬을 따로 고치다 보면 어느 쪽이 최신인지 헷갈리기 쉬우므로, 원본 폴더를 하나만 두고 나머지는 그 폴더를 가리키게 정리하는 편이 안전합니다.

스킬을 만들 때 가장 많이 놓치는 것은 본문이 아니라 description 한 줄입니다. "블로그 글을 쓴다" 정도로만 적어 두면 클로드가 언제 불러야 할지 판단할 근거가 없습니다. 무엇을 하는지와 더불어 어떤 상황·어떤 요청에서 써야 하는지를 구체적으로 적어야 실제로 불립니다. 또 하나 놓치기 쉬운 지점은 남이 만든 스킬을 받을 때입니다. 스킬은 절차를 담고 있고 그 절차 안에는 명령 실행이 들어갈 수 있으므로, 기능이 좋아 보인다고 바로 쓰지 말고 출처부터 확인하는 습관이 필요합니다. 직접 만들었거나 신뢰할 수 있는 출처의 스킬만 쓰는 것이 안전합니다.

설명은 몇 자까지 쓸 수 있나요?

클로드 코드 문서는 description과 when_to_use를 합쳐 1,536자까지라고 안내합니다. API·웹용 스킬 규격 문서는 이름 64자, 설명 1,024자로 다르게 적혀 있으므로, 쓰는 환경에 맞는 문서를 확인하는 편이 안전합니다.

스킬을 몇 개까지 만들 수 있나요?

개수 상한은 공식 문서에서 확인되지 않았습니다. 다만 설명 목록에 예산이 있으므로 안 쓰는 스킬을 쌓아 두는 것은 이득이 없습니다.

규칙 파일과 뭐가 다른가요?

규칙 파일은 항상 읽히는 짧은 원칙이고, 스킬은 필요할 때만 열리는 절차서입니다. 길어지는 절차를 규칙 파일에 넣으면 둘 다 나빠집니다.

같은 부탁을 세 번 했다면 그때 파일로 만드는 것이 기준입니다. 설명 한 줄을 잘 쓰는 것이 그 파일의 절반이며, 최신 글자 수 규격은 공식 문서에서 확인하는 것이 가장 안전합니다.

• Anthropic — Claude Code Skills (https://code.claude.com/docs/en/skills, 확인일 2026-09-18)
• Anthropic — Agent Skills overview (https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview, 확인일 2026-09-18)