슬래시 명령어와 Skills

Q: Skill이 자동으로 호출되지 않습니다.

description에 사용자가 말할 단어가 없거나 프론트매터 YAML이 깨진 경우가 대부분입니다. YAML이 깨지면 /이름은 되지만 description이 비어 자동 호출이 안 됩니다. claude --debug로 파싱 오류를 확인합니다.

Q: 너무 자주 호출됩니다.

description을 더 좁히거나, 사람만 부르게 disable-model-invocation: true를 붙입니다. 이 값을 켜면 description 자체가 컨텍스트에서 빠집니다.

매주 같은 절차를 채팅창에 붙여 넣고 있다면 그 절차는 파일이 될 때가 된 것입니다. 우리 초급 과정의 대표 실습 "녹음 파일을 회의록으로 변환"도 지금은 /transcribe 한 줄입니다. 이 글은 그 한 줄을 만드는 두 방법, 슬래시 명령어와 Skills를 다룹니다. 앞 글의 훅이 "특정 시점에 반드시 실행"이라면 이 글은 "필요할 때 꺼내 쓰는 절차"입니다. 다음 글은 「CLAUDE.md 실전 템플릿」입니다.

핵심 요약

슬래시 명령어는 .claude/commands/이름.md 한 파일, Skills는 .claude/skills/이름/SKILL.md 폴더입니다. 둘 다 /이름으로 부를 수 있습니다.
공식 문서 기준으로 사용자 정의 명령어는 Skills에 병합됐습니다. 기존 명령어 파일은 계속 동작하지만 새로 만들 때는 Skills가 권장됩니다.
Skills는 description을 보고 Claude가 스스로 꺼내 쓸 수 있고, 명령어는 부를 때만 실행됩니다.
부작용이 있는 절차(배포, 발송)는 disable-model-invocation: true로 사람만 부르게 잠급니다.

슬래시 명령어: 내가 부를 때 실행

.claude/commands/ 아래 마크다운 파일 하나가 명령어 하나입니다. 파일명이 곧 이름입니다.

<!-- .claude/commands/meeting-notes.md -->
$ARGUMENTS 경로의 녹음 전사본을 읽고 회의록을 작성한다.
순서: 참석자 → 결정 사항 → 액션 아이템(담당·기한) → 미결.
고객 실명은 홍OO 형태로 바꾼다.

/meeting-notes data/0827.txt라고 부르면 $ARGUMENTS 자리에 경로가 들어갑니다. 단순하지만 보조 파일을 함께 둘 수 없고 Claude가 알아서 꺼내 쓰지는 않습니다.

Skills: 필요할 때 스스로 꺼내 쓰는 절차

Skills는 폴더입니다. SKILL.md가 진입점이고 템플릿, 예시, 스크립트를 옆에 둘 수 있습니다.

.claude/skills/meeting-notes/
├── SKILL.md
├── template.md
└── scripts/anonymize.py

---
name: meeting-notes
description: 녹음 전사본을 회의록으로 정리한다. 사용자가 "회의록", "전사본 정리", "미팅 기록"을 말하면 사용.
argument-hint: "[전사본 경로]"
allowed-tools: Read Bash(python3 *)
---

$ARGUMENTS 파일을 읽고 [template.md](template.md) 형식으로 회의록을 쓴다.
실명은 `python3 ${CLAUDE_SKILL_DIR}/scripts/anonymize.py`로 먼저 치환한다.

세션이 시작되면 Skill의 description만 컨텍스트에 실리고 본문은 호출될 때 로드됩니다. 사용자가 "어제 미팅 정리해줘"라고만 해도 description이 맞으면 Claude가 스스로 꺼냅니다. !`git diff HEAD` 같은 동적 주입 구문을 쓰면 명령 결과가 본문에 미리 채워진 채 전달됩니다.

무엇을 언제 쓰나

상황	선택
한 파일로 끝나는 짧은 프롬프트, 내가 부를 때만	명령어(또는 `disable-model-invocation: true`인 Skill)
템플릿·스크립트·예시가 딸린 절차	Skill
Claude가 맥락을 보고 알아서 적용해야 하는 지식	Skill, `user-invocable: false`
배포·발송처럼 타이밍을 내가 정해야 하는 것	Skill, `disable-model-invocation: true`
매 세션 항상 있어야 하는 사실	CLAUDE.md
특정 시점에 무조건 실행	훅

같은 이름이 명령어와 Skill 양쪽에 있으면 Skill이 우선합니다.

Skills 작성 요령

description에 사용자가 실제로 말할 단어를 넣습니다. 자동 호출이 여기서 결정되며 목록에서는 1,536자에서 잘리므로 핵심 용도를 앞에 둡니다.
SKILL.md는 500줄 이하로 두고 상세 참조는 별도 파일로 뺍니다. 로드된 본문은 세션 내내 컨텍스트에 남으므로 한 줄이 곧 반복 비용입니다.
"왜"보다 "무엇을"을 씁니다. 상시 지침처럼 씁니다. Claude Code는 나중 턴에서 파일을 다시 읽지 않습니다.

팀에 배포하기

.claude/skills/를 git에 커밋하면 클론한 팀원 모두에게 같은 /이름이 생깁니다. 프로젝트 Skill의 allowed-tools는 워크스페이스 신뢰 여부와 무관하게 그대로 적용됩니다. 레포에서 받은 Skill은 실행하기 전에 allowed-tools에 어떤 도구가 열려 있는지 반드시 확인하세요. 여러 레포에서 같은 Skill을 쓰려면 ~/.claude/skills/에 두거나 플러그인으로 묶습니다. 같은 이름이 겹치면 관리 정책 > 개인 > 프로젝트 순으로 이깁니다.

정리

반복되는 절차는 파일로 고정합니다. 새로 만든다면 Skills가 기본입니다.
description이 자동 호출을 결정하고, disable-model-invocation이 부작용을 막습니다.
사실은 CLAUDE.md, 절차는 Skill, 강제는 훅입니다.

자주 묻는 질문

기존 .claude/commands 파일은 지워야 하나요?

아닙니다. 그대로 동작하며 같은 프론트매터도 지원합니다. 보조 파일이 필요해지거나 Claude가 스스로 꺼내 쓰게 하고 싶을 때 폴더로 옮기면 됩니다.

Skill이 자동으로 호출되지 않습니다.

description에 사용자가 말할 단어가 없거나 프론트매터 YAML이 깨진 경우가 대부분입니다. YAML이 깨지면 /이름은 되지만 description이 비어 자동 호출이 안 됩니다. claude --debug로 파싱 오류를 확인합니다.

너무 자주 호출됩니다.

description을 더 좁히거나, 사람만 부르게 disable-model-invocation: true를 붙입니다. 이 값을 켜면 description 자체가 컨텍스트에서 빠집니다.