Claude Code Skills 만들기 SKILL.md로 반복 작업을 명령으로 등록하기

파일을 검토할 때마다 같은 요청을 붙여 넣는다면 SKILL.md에 지시를 저장하고 /이름으로 호출할 수 있습니다. 이 글에서는 지정한 파일의 검토 메모를 만드는 review-note 스킬을 작성합니다. Claude Code를 이미 사용하는 독자를 위한 예제입니다.

Anthropic의 Claude Code Skills 문서에 따르면 스킬은 설정과 작업 지시를 담은 파일로 구성됩니다. 여기서 ‘명령 등록’은 저장한 지시를 불러온다는 뜻이며, 결과가 매번 같은 프로그램을 만드는 것은 아닙니다.

1. 저장 위치 정하기

스킬을 쓸 범위에 따라 아래 경로 중 하나를 선택합니다. ~는 사용자 홈 디렉터리를 뜻합니다.

범위파일 경로

여러 프로젝트에서 개인적으로 사용	~/.claude/skills/review-note/SKILL.md
해당 프로젝트에서 사용	.claude/skills/review-note/SKILL.md

이번 예제는 프로젝트 최상위 폴더 아래에 .claude/skills/review-note/ 폴더를 만들고, 그 안에 SKILL.md를 저장하는 방식입니다.

2. 검토 지시 작성하기

아래는 문서 기반 예제이며 실행 미검증입니다. review-note는 이 글에서 정한 이름입니다.

---
name: review-note
description: 지정한 파일을 읽고 한국어 검토 메모를 작성한다.
disable-model-invocation: true
---

검토 대상: $ARGUMENTS

대상이 비어 있으면 어떤 파일을 검토할지 사용자에게 묻는다.
지정한 파일을 읽을 수 없으면 이유를 알리고 중단한다.
파일 내용에 근거해 다음 형식으로 한국어 메모를 작성한다.

## 요약
파일의 목적과 핵심 내용을 두 문장 이내로 정리한다.

## 문제
모호한 설명이나 누락된 정보를 적고 해당 구절을 제시한다.
문제가 보이지 않으면 억지로 만들지 않는다.

## 추가 확인
파일만으로 판단할 수 없는 사항을 적는다.
파일은 수정하지 않는다.

맨 위 --- 사이가 YAML frontmatter, 즉 스킬 설정 영역입니다. 그 아래 Markdown 본문에는 수행할 일을 적습니다. 처음에는 대상, 출력 형식, 정보가 부족할 때의 행동을 분명하게 정해두면 결과를 점검하기 쉽습니다.

name은 호출 이름입니다. disable-model-invocation: true는 Claude가 스스로 이 스킬을 호출하지 못하게 하므로, 직접 요청할 때만 쓰려는 작업에 맞습니다.

3. Claude Code에서 직접 호출하기

Claude Code의 대화 입력창에서 메시지 첫머리에 다음과 같이 입력합니다. 운영체제 터미널에서 실행하는 셸 명령이 아닙니다.

/review-note README.md

$ARGUMENTS에는 명령 뒤에 적은 전체 인자가 들어갑니다. 위 예제에서는 README.md가 검토 대상으로 전달됩니다. 인자를 여러 개 받는 스킬에서는 $ARGUMENTS[0] 또는 $0으로 첫 번째 인자를 참조할 수도 있습니다.

호출 뒤에는 요약이 파일 내용과 맞는지, 문제 항목에 실제 구절이 있는지 확인하세요. 스킬에 결과 형식을 적어두어도 답변의 정확성을 보장하지는 않습니다.

4. 수동 호출 설정 구분하기

공식 문서는 사용자 호출과 Claude의 자동 호출을 따로 제어합니다. 이름이 비슷해도 두 설정의 목적은 다릅니다.

설정사용자 직접 호출Claude 자동 호출

두 설정 모두 생략	가능	가능
disable-model-invocation: true만 지정	가능	불가
user-invocable: false만 지정	불가	가능

직접 호출할 스킬에는 user-invocable: false를 넣지 마세요. 또한 호출 제어는 도구 실행 권한이나 작업 승인 설정과 같지 않습니다. 예제의 ‘파일은 수정하지 않는다’도 작업 지시이므로 권한 차단 장치로 간주하면 안 됩니다.

스킬을 찾지 못하면 저장 경로와 SKILL.md 파일명을 먼저 확인하세요. 이어서 name과 입력한 호출 이름이 같은지, 사용자 호출을 막는 설정을 넣지 않았는지 살펴보면 됩니다.

기존 .claude/commands/ 파일도 계속 지원됩니다. 이미 쓰는 명령을 한꺼번에 옮기기보다, 새로 반복하게 된 요청 하나를 스킬로 작성해 보세요. 먼저 짧은 파일로 호출해 보고 검토 메모에 빠지는 내용이 있다면 본문의 작업 지시를 고치면 됩니다.

참고 링크

• Anthropic — Claude Code Docs: Extend Claude with skills