Claude Code 스킬 처음 만들기 — SKILL.md 한 개로 반복 업무 맡기기

KAITABASE가 공식 문서와 원문을 직접 읽고 새로 쓴 가이드입니다.

이 가이드로 할 수 있는 것

스킬은 SKILL.md 파일 하나에 지시를 적어 두면 Claude Code가 필요할 때 꺼내 쓰는 기능입니다. 공식 문서는 같은 지시 · 체크리스트 · 여러 단계 절차를 대화창에 계속 붙여 넣고 있거나, CLAUDE.md의 한 부분이 "사실"이 아니라 "절차"로 커졌을 때 스킬을 만들라고 권합니다.

CLAUDE.md와 가장 다른 점은 읽히는 시점입니다. 평소에는 스킬 이름과 설명(description)만 맥락에 올라가고, 본문은 불렀을 때만 읽힙니다. 그래서 긴 절차를 넣어도 평소 비용이 거의 늘지 않습니다.

이 가이드에서는 "이번 주 커밋으로 주간 보고 초안 쓰기" 스킬을 만듭니다.

빠른 시작

프로젝트 루트에서 폴더를 만들고 SKILL.md 를 저장합니다.

mkdir .claude\skills\weekly-report
notepad .claude\skills\weekly-report\SKILL.md

파일 검사(직접 실행한 결과):

1234> claude plugin validate .claude/skills
Validating components in: ...\proj\.claude\skills

✔ Validation passed

그다음 Claude Code에서 /weekly-report 를 입력하면 실행됩니다(공식 문서 기준).

STEP 1. 어디에 만들지 정하기

목표: 스킬을 쓸 범위를 정합니다. · 예상 시간: 2분

처음에는 프로젝트 위치를 권합니다. 저장소 안에만 있어서 시험하다 지워도 다른 프로젝트에 영향이 없습니다. 예전 방식인 .claude/commands/이름.md 도 그대로 동작하며, 공식 문서는 새로 만들 때는 스킬을 쓰라고 권합니다.

막히면 폴더 이름을 synced 나 anthropic-skills 로 지으면 불러오지 않습니다. 둘 다 예약된 이름입니다.

STEP 2. SKILL.md 쓰기

목표: 언제 쓰는지(description)와 무엇을 하는지(본문)를 적습니다. · 예상 시간: 8분

파일 맨 첫 줄이 --- 여야 앞부분 설정(frontmatter)으로 읽힙니다.

12345678910111213141516---
name: weekly-report
description: 이번 주 커밋 기록으로 주간 업무 보고 초안을 씁니다. 사용자가 주간 보고, 이번 주 한 일 정리, 주간 회고를 요청할 때 사용합니다.
disable-model-invocation: true
allowed-tools: Bash(git log *)
---

## 이번 주 커밋

!`git log --since="7 days ago" --pretty=format:"%h %ad %s" --date=short`

## 할 일

1. 위 커밋을 기능 · 버그 수정 · 기타로 나눕니다.
2. 각 묶음을 한 줄씩 요약합니다.
3. 다음 주 할 일은 추측하지 말고 "(작성자가 채움)"으로 남깁니다.

각 줄의 뜻(공식 문서 기준):

• name: / 메뉴에 보이는 명령 이름입니다. 없으면 폴더 이름을 씁니다.
• description: Claude가 이 스킬을 언제 쓸지 판단하는 글입니다. 핵심 용도를 앞에 둡니다. when_to_use 와 합쳐 1,536자에서 잘립니다.
• disable-model-invocation: true: Claude가 스스로 부르지 못하고 내가 /weekly-report 로만 부릅니다. 배포 · 메시지 전송처럼 부작용이 있는 일에 씁니다.
• allowed-tools: 이 스킬을 부른 그 턴에 한해, 적힌 도구를 승인 없이 쓰게 합니다. 다음 메시지를 보내면 풀립니다.
• !`명령`: Claude가 읽기 전에 명령을 실행해 그 출력으로 바꿔 끼웁니다(동적 맥락 주입).

확인 같은 저장소에서 ! 줄의 명령을 직접 실행해 출력이 나오는지 봅니다. 이 가이드의 시험 저장소에서는 이렇게 나왔습니다.

415cd49 2026-10-22 주간 보고 스킬 추가
e1ab539 2026-10-22 로그인 화면 오류 수정

막히면 공식 문서에 따르면 주입 명령은 실행 중에 승인 창을 띄우지 않습니다. 권한 규칙이 허용하지 않으면(자동 모드가 아닐 때) 스킬 호출 전체가 Shell command permission check failed 로 중단됩니다. 그래서 위 예시는 allowed-tools: Bash(git log *) 로 그 명령을 미리 허용했습니다. 명령이 0이 아닌 종료 코드로 끝나도 호출 전체가 중단되므로, 실패가 정상인 명령에는 || true 를 붙입니다.

STEP 3. 파일 검사하기

목표: 형식 오류를 미리 찾습니다. · 예상 시간: 2분

claude plugin validate .claude/skills

공식 문서는 앞부분 설정이 해석되지 않는 SKILL.md 를 찾을 때 이 명령을 쓰라고 안내합니다(v2.1.233 이상). 직접 실행하니 정상 스킬은 ✔ Validation passed 가 나왔습니다.

막히면 시험 삼아 description: [unclosed 처럼 일부러 YAML을 깨뜨린 스킬을 넣어 봤는데, 2.1.307에서는 이것도 ✔ Validation passed 로 나왔습니다. 검사를 통과했어도 자동 호출이 안 되면 claude --debug 로 해석 오류를 확인합니다. 공식 문서는 YAML이 깨지면 본문은 불러오되 설정은 비운 채로 불러온다고 설명합니다. 이 경우 /이름 으로는 부를 수 있어도 description으로 자동 호출되지는 않습니다.

STEP 4. 불러 보기

목표: 스킬이 실제로 동작하는지 봅니다. · 예상 시간: 5분 · 공식 문서 기준(직접 실행 안 함)

1. 저장소 폴더에서 claude 를 실행합니다.
2. 메시지 맨 앞에 /weekly-report 를 입력합니다.
3. 커밋 목록이 반영된 주간 보고 초안이 나오는지 봅니다.

세션을 연 채로 SKILL.md 를 고치면, Claude Code가 스킬 폴더를 지켜보고 있어 재시작 없이 반영합니다. 세션을 연 뒤에 처음 만든 최상위 스킬 폴더는 /reload-skills 로 불러옵니다.

확인 /skills 로 목록을 열어 weekly-report 가 있는지 봅니다.

막히면 메시지 중간에 /weekly-report 를 쓰면 바로 실행되지 않고 "써도 된다는 허락"으로만 취급됩니다. 바로 실행하려면 메시지 맨 앞에 씁니다.

되돌리기 .claude/skills/weekly-report 폴더를 지우면 현재 세션 목록에서도 빠집니다.

STEP 5. 자동 호출 스킬로 바꾸기 (선택)

목표: 내가 부르지 않아도 Claude가 알맞을 때 쓰게 합니다. · 예상 시간: 5분

disable-model-invocation: true 줄을 지우면 Claude가 description을 보고 스스로 부를 수 있습니다. 공식 문서의 점검 순서는 다음과 같습니다.

1. description에 사용자가 실제로 말할 단어가 들어 있는지 봅니다("주간 보고", "이번 주 한 일").
2. What skills are available? 라고 물어 목록에 있는지 봅니다.
3. 너무 자주 불리면 description을 더 좁히거나 다시 disable-model-invocation: true 를 붙입니다.

잘못 쓰는 예 · 바르게 쓰는 예

바로 쓰는 프롬프트 · 템플릿

스킬 뼈대:

123456789101112131415---
name: <짧은-이름>
description: <무엇을 하는지 한 문장>. <사용자가 이런 말을 할 때> 사용합니다.
disable-model-invocation: true
---

## 입력
$ARGUMENTS

## 할 일
1. ...
2. ...

## 지킬 것
- 확인하지 못한 내용은 "확인 필요"로 남긴다

$ARGUMENTS 에는 /이름 뒤에 쓴 글이 들어갑니다. 첫 번째 인자만 쓰려면 $0, 두 번째는 $1 입니다.

반복 지시를 스킬로 바꿔 달라고 맡길 때:

최근 대화에서 내가 세 번 이상 반복해 붙여 넣은 지시를 찾아 주세요.
각각을 .claude/skills/<이름>/SKILL.md 형식의 초안으로 보여 주되,
description은 내가 실제로 쓴 표현을 넣어 주세요. 파일은 아직 만들지 마세요.

주의할 점

• 권한: allowed-tools 는 작업 폴더를 신뢰하지 않은 상태에서도 적용된다고 공식 문서가 경고합니다. 남의 저장소를 열기 전에 .claude/skills 의 allowed-tools 를 확인합니다.
• 명령 실행: !`명령` 은 스킬을 부를 때 내 컴퓨터에서 실제로 실행됩니다. 관리자는 disableSkillShellExecution 설정으로 끌 수 있습니다.
• 맥락 비용: 한 번 불린 스킬 본문은 이후 대화 내내 맥락에 남습니다. 본문은 짧게, 긴 참고 자료는 같은 폴더의 별도 파일로 두고 필요할 때 읽게 합니다.
• 다른 곳으로 올릴 때: claude.ai 업로드 · Skills API에서는 앞부분 설정을 name, description, license, compatibility, metadata, allowed-tools 여섯 개만 쓸 수 있고, 그 밖의 필드가 있으면 오류가 납니다.
• 라이선스: 이 가이드는 Anthropic 공식 문서를 우리 말로 다시 정리한 것입니다.

공식 자료

• Extend Claude with skills — https://code.claude.com/docs/en/skills
• Agent Skills 공개 표준 — https://agentskills.io/specification
• Skill authoring best practices — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
• Commands 목록(/skills, /reload-skills) — https://code.claude.com/docs/en/commands

더 보기

이 가이드는 KAITABASE가 공식 문서와 원문을 직접 읽고 실행해 본 뒤 새로 쓴 자료입니다. 같은 주제의 다른 글은 KAITABASE에서 이어서 볼 수 있습니다.

• AI 코딩 자료 모음 — https://kaitabase.vercel.app/?area=coding
• KAITABASE 전체 자료 — https://kaitabase.vercel.app