Skills(스킬)는 Claude Code에 "이 일은 이렇게 해라"를 파일 하나로 미리 적어 두는 기능입니다. 매번 채팅에 긴 지시를 다시 쓰는 대신, 폴더에 넣어 둔 지침을 필요할 때 불러 씁니다. 원장님이 직원에게 주는 업무 매뉴얼을 AI에게 주는 것이라고 보시면 됩니다.

스킬은 어디에 두나

스킬은 SKILL.md라는 마크다운 파일 하나로 만듭니다. 파일을 두는 위치에 따라 적용 범위가 달라집니다.

폴더 이름이 곧 호출 이름입니다. .claude/skills/review-reply/SKILL.md를 만들면 /review-reply로 부릅니다.

파일 구조: 머리말 + 본문

SKILL.md 맨 위에는 프론트매터(--- 사이의 설정)를 적고, 그 아래에 실제 지침을 씁니다. 자주 쓰는 설정은 다음과 같습니다.

• name: 표시 이름(생략하면 폴더 이름)
• description: 이 스킬이 무엇을 하는지 한 줄. Claude가 "지금 이 스킬을 쓸 때인가"를 판단하는 근거라서 가장 중요합니다.
• disable-model-invocation: true: 사람이 /이름으로 부를 때만 실행(AI가 알아서 켜지 않음)
• allowed-tools: 이 스킬이 미리 허용받는 도구(예: 읽기·검색만)
• arguments: 이름 붙은 인자. 본문에서 $ARGUMENTS나 $0, $1로 받습니다.

작성 예시: 구글 리뷰 답변 초안 스킬

---
name: review-reply
description: 구글 리뷰 원문을 받아 병원 톤에 맞는 답변 초안을 쓴다. 리뷰 답변 요청이 오면 사용.
disable-model-invocation: true
---

아래 리뷰에 대한 답변 초안을 3문장 이내로 작성한다.
- 존댓말, 의료 효과 단정 표현 금지
- 불만 리뷰는 사과 -> 확인 요청 -> 연락처 안내 순서
- 이모지와 과장 표현은 쓰지 않는다

리뷰 원문: $ARGUMENTS

이 파일을 .claude/skills/review-reply/SKILL.md에 두고 채팅창에 /review-reply 대기 시간이 너무 길었어요라고 치면, 스킬 본문이 지시문으로 들어가고 리뷰 원문이 $ARGUMENTS 자리에 채워집니다.

호출 방식 3가지

• 직접 호출: /스킬이름 인자. 여러 개를 이어 부를 수도 있습니다.
• 자동 호출: description을 보고 Claude가 상황에 맞는 스킬을 스스로 불러 씁니다(disable-model-invocation이 없을 때).
• 명시 로드 규칙: 팀에서 "이 유형의 작업은 반드시 이 스킬을 먼저 읽고 시작한다"고 정해 두는 운용 방식입니다. 자동 호출에만 기대면 빠뜨리는 일이 생겨서, 저희는 작업 유형별로 스킬을 명시해 불러 쓰게 하고 있습니다.

언제 스킬로 만들면 좋은가

• 같은 지시를 세 번 이상 반복해서 쓰고 있을 때
• 순서를 틀리면 사고가 나는 절차(배포, 백업, 검증)가 있을 때
• "지난번에 겪은 함정"을 다음 작업자(사람이든 AI든)에게 물려줘야 할 때

한 번 쓰고 끝날 지시는 채팅으로 충분합니다.

사례: 원스링크 팀의 스킬 11종

저희는 여러 병원 홈페이지를 한 작업실에서 운영하면서, 작업 유형별로 스킬을 나눠 두었습니다. 내부 정보는 빼고 "무슨 단위로 쪼갰는지"만 소개합니다.

핵심은 각 스킬 안에 절차뿐 아니라 "여기서 자주 틀린다"는 함정 목록이 같이 들어 있다는 점입니다. 사고가 나면 교훈을 스킬 파일에 한 줄 추가하고, 다음 작업부터는 같은 실수를 반복하지 않습니다. 병원이 사고 사례를 매뉴얼에 반영하는 것과 같은 원리입니다.

참고 링크

• Claude Code 공식 문서: Skills
• Claude Code 공식 문서: Plugins(스킬을 묶어 배포)
• Claude Code 공식 문서: Memory(CLAUDE.md)