클로드 코드 스킬 만들기, 초보자 5분 가이드
같은 지시를 세 번째 타이핑하고 있는 분께 맞는 글입니다. 폴더, SKILL.md, 설명 한 줄까지 스킬을 만드는 3단계와 안 불릴 때 확인할 것을 정리했습니다.
스킬은 폴더 하나와 SKILL.md 파일 하나면 만들 수 있고, 가장 단순한 스킬은 5분 안팎이 걸립니다. 걸리는 시간을 줄이는 것은 절차보다 "언제 쓰는지"를 담은 설명 한 줄입니다.
내가 최근 자주 반복한 요청 하나를 골라 클로드 코드 스킬로 만들어 줘. - 폴더 위치는 ~/.claude/skills/<스킬이름>/ 로 - SKILL.md 맨 위에 --- 로 감싼 description 작성 - description에는 「무엇을 하는지」와 「언제 쓰는지」를 둘 다 적기 - 본문에는 평소 말로 시키던 절차를 그대로 적기 만든 뒤 /스킬이름 으로 호출해 보는 방법도 알려 줘.
스킬은 "이럴 때 이렇게 해줘"라는 지침을 파일 하나에 저장해 두고, Claude가 필요하다고 판단할 때 알아서 읽어 쓰는 기능입니다. 공식 문서는 스킬을 "재사용 가능한 파일 기반 자원으로, 범용 에이전트를 전문가로 바꿔 주는 작업 절차와 맥락"이라고 설명합니다.
만드는 데 필요한 것은 폴더 하나와 텍스트 파일 하나뿐입니다.
스킬이 필요한 순간
같은 지시를 세 번째 타이핑하고 있다면 그 순간이 스킬이 필요한 때입니다. 짧은 규칙이면 규칙 파일(CLAUDE.md)에 넣으면 되지만, 여러 단계를 거치는 절차라면 규칙 파일이 너무 길어집니다. 그 중간을 메우는 것이 스킬입니다.
저도 처음엔 "이걸 굳이 파일로 만들 필요가 있나" 싶었습니다. 그런데 같은 형식의 요청을 반복해서 설명하다 보니, 설명하는 시간이 스킬 하나 만드는 시간보다 더 걸린다는 걸 깨달았습니다.
폴더를 만듭니다
개인용은 ~/.claude/skills/<스킬이름>/, 프로젝트에서만 쓰려면 .claude/skills/<스킬이름>/에 둡니다. 공식 문서는 이 방식을 두고 "파일시스템 기반이라 업로드가 필요 없다"고 설명합니다.
# 개인용 (모든 프로젝트)
mkdir -p ~/.claude/skills/내스킬
# 이 프로젝트에서만
mkdir -p .claude/skills/내스킬SKILL.md 파일을 만듭니다
맨 위에 ---로 둘러싼 설명(description)을 적고, 그 아래 본문에 평소 말로 시키던 절차를 그대로 적습니다.
---
description: 무엇을 하는지, 그리고 언제 쓰는지
---
# 여기부터 절차
평소 말로 시키던 순서를 그대로 적는다.설명(description) 한 줄을 다듬습니다
공식 문서는 이 항목이 "Claude가 이 스킬을 실행할지 판단할 때 요청과 대조하는 대상"이라고 설명합니다. 무엇을 하는지와 언제 쓰는지를 둘 다 적어야 합니다.
새 대화를 열고 관련된 요청을 하면 스킬이 자동으로 불립니다. 확실히 부르고 싶으면 /스킬이름으로 직접 호출하면 됩니다.
실제로 걸린 시간
가장 단순한 스킬(지침 10줄 안팎)을 기준으로 재 보면, 폴더 만들기부터 첫 호출 확인까지 5분 안팎이 맞았습니다. 다만 이건 "이미 절차가 머릿속에 있는" 상태에서의 시간입니다.
그러니 5분이라는 시간은 설명 한 줄을 제대로 쓴다는 조건이 붙습니다.
항상 실행되는 것은 아닙니다
만들어 두면 늘 자동으로 돌아간다고 생각하기 쉬운데, 아닙니다. Claude가 설명을 보고 관련이 있다고 판단할 때만 부릅니다.
확실하게 통제하고 싶으면 disable-model-invocation으로 자동 호출을 막고 수동 호출만 남길 수 있습니다.
자주 하는 실수
저는 처음 만든 스킬이 한동안 안 불려서 헤맸습니다. 원인은 본문이 아니라 설명 한 줄이었습니다. "블로그 글을 쓴다" 정도로만 적었더니 Claude가 언제 써야 할지 판단할 수 없었던 것입니다. 언제 쓰는지를 넣고 나서야 걸리는 시간이 5분 안쪽으로 줄었습니다.
자주 묻는 질문
정말 5분이면 되나요?
지침이 짧고 단순한 스킬이라면 그렇습니다. 여러 단계·여러 파일을 참조하는 스킬은 시간이 더 걸립니다. 5분은 "설명 한 줄을 미리 정리해 둔 경우"의 체감 시간입니다.
스킬과 규칙 파일(CLAUDE.md)은 뭐가 다른가요?
규칙 파일은 세션 시작 시 항상 읽히는 짧은 원칙이고, 스킬은 필요할 때만 열리는 절차서입니다. 매번 참고할 짧은 규칙은 규칙 파일에, 반복되는 긴 절차는 스킬에 넣으면 됩니다.
만들고 나서 안 불리면 어떻게 하나요?
가장 먼저 설명(description) 문장을 확인합니다. "무엇을 하는지"만 있고 "언제 쓰는지"가 빠져 있으면 대부분 이 문제입니다.
정리
스킬 만들기 자체는 어렵지 않습니다. 시간을 정말 5분으로 줄이는 건 절차가 아니라 설명 한 줄입니다.