필요할 때만 꺼내 쓰는 매뉴얼 | Skills

Overview

CLAUDE.md에는 모든 세션에 필요한 프로젝트 기준을 두고, Rules에는 특정 파일이나 경로에서만 필요한 규칙을 나누는 방법을 배웠습니다.

하지만 지침이 필요한 순간이 파일 경로가 아니라 요청한 작업에 따라 결정되는 경우도 있습니다. 이번 Lesson에서는 이런 작업 절차를 필요한 순간에만 불러오는 Skills를 살펴봅니다.

학습 목표

• CLAUDE.md·Rules·Skills가 각각 어떤 조건에서 필요한지 구분합니다.
• Skill의 Progressive Disclosure 구조를 설명합니다.
• 반복 작업 절차를 Skill로 분리할지 판단합니다.

배포 절차는 어디에 둘까?

Claude에게 “배포해줘”라고 요청한다고 해보겠습니다. 배포 전에는 변경 사항을 확인하고 테스트와 빌드를 실행해야 합니다. 배포한 뒤에는 서비스가 정상적으로 열리는지도 확인해야 합니다.

이 절차를 CLAUDE.md에 넣으면 배포하지 않는 세션에서도 매번 읽습니다.

Rules로 옮기고 src/** 같은 경로를 지정해도 맞지 않습니다. 기능을 개발하며 Claude가 src/ 파일을 읽을 때마다, 배포 여부와 관계없이 배포 절차가 함께 불려오기 때문입니다.

배포 절차가 필요한 조건은 파일 위치가 아니라 배포라는 작업을 요청했는가입니다. 코드 리뷰와 커밋도 마찬가지입니다. 어떤 파일을 다루든, 해당 작업을 요청했을 때만 정해진 절차가 필요합니다.

이처럼 특정 작업에 맞는 절차를 필요한 순간에 불러오는 도구가 Skill입니다.

Skill: 작업을 요청할 때 꺼내는 매뉴얼

Skill은 필요할 때 불러오는 지침과 선택적 보조 파일을 묶어 둔 폴더입니다. 이번 Lesson에서는 그중 코드 리뷰, 커밋, 배포처럼 여러 단계를 반복하는 작업 절차를 다룹니다. 이런 절차를 CLAUDE.md에 쌓지 않고 별도 Skill로 분리합니다.

커밋 절차를 Skill로 만들 때 최소 구조는 다음과 같습니다.

SKILL.md의 frontmatter에는 Skill을 찾을 때 사용하는 name과 description을 두길 권장합니다. 두 필드는 생략할 수도 있지만, 그 경우 폴더 이름과 본문 첫 문단에 의존하므로 자동 선택 조건을 명확하게 관리하기 어렵습니다.

---
name: commit
description: 변경사항을 Conventional Commit 형식으로 커밋합니다. 코드 변경 후 커밋 요청 시 사용합니다.
---

description은 하는 일뿐 아니라 언제 사용할지를 알려줍니다. 사용자가 "변경사항 커밋해줘"라고 요청하면 Claude가 이 설명을 보고 commit Skill이 필요한지 판단합니다.

Progressive Disclosure: 필요한 만큼만 읽기

Skill은 지침을 한 번에 모두 넣지 않고 세 단계로 나눠 읽습니다.

1단계: 이름과 설명

Claude는 사용할 수 있는 Skill의 이름과 설명을 보고 어떤 작업에 쓸 수 있는지 파악합니다. 명시한 frontmatter가 없다면 폴더 이름과 본문 첫 문단이 대신 사용됩니다. 이 단계에서는 SKILL.md 본문 전체와 보조 파일을 읽지 않습니다.

- commit: 변경사항을 Conventional Commit 형식으로 커밋
- code-review: PR을 팀의 보안·성능·테스트 기준으로 검토
- deploy-checklist: Production 배포와 롤백 절차 수행

2단계: SKILL.md 본문

사용자가 관련 작업을 요청하고 Claude가 Skill을 선택하면 SKILL.md 본문을 읽습니다. 지금 수행할 절차와 판단 기준만 현재 Context에 들어옵니다.

3단계: 필요한 보조 파일

작업이 커지면 Skill 폴더에 참고 자료·템플릿·스크립트를 추가할 수 있습니다.

SKILL.md에는 보조 파일이 필요한 조건을 적습니다.

## 추가 자료

- 커밋 타입이 애매하면 `references/conventional-commit-types.md`를 읽습니다.
- 메시지를 작성할 때 `templates/commit-message.md`를 사용합니다.
- staged 파일 구성이 복잡하면 `scripts/inspect-staged-files.sh`를 실행합니다.

Claude는 실제 조건이 맞을 때만 해당 파일을 추가로 읽거나 실행합니다. Skill 폴더가 커져도 지금 작업과 관계없는 자료까지 처음부터 Context에 넣을 필요가 없습니다.

CLAUDE.md·Rules·Skills 선택하기

저장 위치가 애매할 때는 지침이 필요한 순간을 묻습니다.

• 프로젝트를 열 때마다 필요한가? CLAUDE.md에 둡니다.
• 특정 파일이나 경로를 다룰 때 필요한가? Rules에 두고 paths를 지정합니다.
• 특정 작업을 요청했을 때 필요한가? Skill로 만듭니다.

예를 들어 "버튼은 Shadcn 컴포넌트를 사용한다"는 UI 파일을 수정할 때 필요한 Rules입니다. "변경 파일을 확인하고 테스트한 뒤 Conventional Commit으로 커밋한다"는 파일 경로와 관계없이 커밋 요청에서 필요한 Skill입니다.

Rules와 Skill은 함께 적용될 수도 있습니다. commit Skill이 작업 절차를 정하고, 커밋에 포함된 UI 파일을 수정할 때는 Shadcn Rules가 파일별 기준을 제공합니다.

핵심 포인트 정리

1. 적용 조건: 모든 세션은 CLAUDE.md, 특정 경로는 Rules, 특정 작업은 Skills로 구분합니다.
2. Progressive Disclosure: 이름과 설명으로 Skill을 찾고, 선택한 Skill의 본문과 필요한 보조 파일만 단계적으로 읽습니다.
3. 작업 절차의 분리: 커밋·코드 리뷰·배포처럼 파일 경로와 무관하게 반복하는 절차는 Skill로 만듭니다.

FAQ

이어서 배울 내용

이제 반복하던 커밋 절차를 첫 Skill로 만듭니다. 다음 Lesson에서는 절차와 호출 조건을 Skill Creator에 설명해 .claude/skills/commit/SKILL.md를 만들고, 생성 결과와 자연어 자동 호출을 직접 확인합니다.

• 반복 절차와 호출 조건 정리하기
• Skill Creator로 SKILL.md 만들고 검토하기
• 자연어 요청으로 자동 호출 확인하기