Claude Code skills: 스킬의 구조, SKILL.md, 에이전트가 스킬을 불러오는 시점

Claude Code에서 스킬이란 무엇인가

스킬(skill)은 특정 유형의 작업에 대한 지침을 담은 SKILL.md 파일이 들어 있는 폴더입니다. 예를 들어 프로젝트를 배포하는 방법, 코드 리뷰를 하는 방법, 릴리스를 내는 방법이 있습니다. 에이전트는 세션이 시작될 때부터 스킬이 있다는 것을 알고 있지만, 작업이 실제로 그것을 필요로 할 때만 전체 내용을 읽습니다.

Claude Code 스킬은 CLAUDE.md를 오래 관리해 본 사람이라면 익숙한 문제를 해결합니다. 지침 파일은 점점 커집니다. 배포 절차가 80줄이라면 일주일에 한 번 필요하지만, 그 80줄은 오타를 고치는 세션에서도 컨텍스트를 차지합니다. 스킬은 이런 절차를 상시 컨텍스트 밖으로 빼내고, 필요할 때만 불러옵니다.

스킬의 구성 요소

가장 작은 스킬은 폴더 하나와 파일 하나로 이루어집니다. 프로젝트 스킬은 저장소 안에 두고, 개인 스킬은 사용자의 홈 디렉터리에 둡니다.

.claude/skills/deploy/SKILL.md      # 프로젝트 스킬, git으로 팀과 공유
~/.claude/skills/review/SKILL.md    # 개인 스킬, 모든 프로젝트에서 사용

SKILL.md 옆에는 템플릿, 스크립트, 참고 자료 같은 보조 파일을 둘 수 있습니다. 에이전트는 주요 텍스트가 그 파일을 가리키고 실제로 필요할 때만 파일을 엽니다.

.claude/skills/deploy/
├── SKILL.md           # 주요 지침
├── checklist.md       # 상세 체크리스트, 링크를 따라 읽음
└── rollback.sh        # 롤백 스크립트

Frontmatter: name과 description

파일은 --- 줄 사이의 YAML 블록으로 시작합니다. 여기서 가장 중요한 필드는 두 개입니다. name은 스킬의 짧은 이름이고, description은 스킬이 무엇을 하는지, 언제 써야 하는지를 설명합니다.

---
name: deploy
description: 호스팅에 사이트를 FTP로 배포합니다. 변경 사항을 서버에 올리거나, 서버와의 차이를 확인하거나, 배포를 되돌릴 때 사용합니다.
---

# 배포

1. 먼저 시험 실행: `./deploy.sh -n`.
2. 파일 목록 확인: 비밀 정보나 테스트 스크립트가 없어야 합니다.
3. 업로드: `./deploy.sh`.
4. 변경된 페이지를 열어 200 응답이 오는지 확인합니다.

롤백은 이 폴더의 rollback.sh를 참고하세요.

frontmatter 아래는 일반 Markdown입니다. 단계, 명령, 제약, 옆 파일로의 링크를 적습니다. 이 작업을 처음 맡는 새 동료에게 주는 안내문처럼 작성하세요.

에이전트가 스킬을 불러오는 시점

세션 초반에는 각 스킬의 이름과 설명만 컨텍스트에 들어갑니다. 스킬당 몇 줄이므로 수십 개도 보관할 수 있습니다. 사용자의 요청이나 현재 단계가 설명과 맞으면 에이전트는 스킬을 호출하고, 그때 비로소 SKILL.md 전체가 컨텍스트에 들어옵니다.

여기서 실용적인 규칙이 나옵니다. 스킬은 설명을 보고 작동합니다. 에이전트는 스킬을 열기로 정하기 전까지 본문을 보지 못합니다. description에 "보조 스킬"이라고만 적혀 있다면 에이전트는 언제 필요한지 알 수 없습니다. "호스팅에 배포합니다. 변경 사항을 서버에 올리거나 배포를 되돌릴 때 사용합니다"라고 적혀 있으면 알 수 있습니다.

자동 선택 외에도 스킬을 이름으로 직접 호출할 수 있습니다. 슬래시와 함께 /deploy처럼 입력하면 됩니다. 어떤 절차가 필요한지 정확히 알고 있고, 에이전트가 요청과 설명을 알아서 맞춰 주기를 기다리고 싶지 않을 때 편리합니다.

스킬이 잘 불러와지도록 description 쓰기

• 무엇을 하는지 — 동사로 한 문장에: "사이트 배포", "커밋 전 변경 사항 리뷰".
• 언제 쓰는지 — 사용자가 실제로 하는 말을 나열하세요: "서버에 올려 줘", "배포해", "되돌려 줘".
• 언제 쓰지 않는지 — 옆에 있는 다른 스킬과 헷갈릴 때 적습니다: "봇 배포가 아니라 사이트 배포 전용".
• "유용한 스킬", "작업에 도움이 됨" 같은 일반적인 말은 쓰지 마세요. 아무 신호도 주지 않습니다.

점진적 공개

스킬은 점진적 공개(progressive disclosure) 원칙에 따라 만들어집니다. 정보는 층으로 나뉘고, 각 층은 필요할 때만 불러옵니다.

긴 지침 파일 대신 짧은 목차를 두는 방식과 같은 아이디어입니다. 짧은 지도는 항상 보이고, 자세한 내용은 링크를 따라갑니다. 차이는 스킬이 이런 불러오기를 정식 메커니즘으로 만든다는 점입니다. 에이전트가 알아서 필요한 문서를 열기를 기대하지 않아도 됩니다. 덧붙여, 3층의 스크립트는 코드를 컨텍스트에 통째로 올리지 않고 그냥 실행할 수 있습니다.

Skills, CLAUDE.md, 슬래시 명령의 차이

세 가지 방식 모두 에이전트에게 지침을 전달하지만, 시점과 컨텍스트 비용이 다릅니다.

선택 기준은 단순합니다. 거의 모든 작업에서 필요한 지침이라면 CLAUDE.md에 둡니다. 특정 유형의 작업에서만 필요하다면 스킬입니다. 매번 같은 긴 요청을 직접 입력하고 있다면 슬래시 명령이나 수동으로 호출하는 스킬의 후보입니다.

절대 어기면 안 되는 규칙은 스킬에 넣지 마세요. 스킬이 불러와지지 않을 수도 있기 때문입니다. "비밀 정보를 절대 커밋하지 마라" 같은 규칙은 항상 적용되어야 합니다. 이런 불변 조건은 CLAUDE.md에 두고, 가능하면 훅, 접근 권한, CI 검사로 뒷받침하세요.

Claude Code 스킬을 만드는 방법: 단계별 안내

1. 반복되는 절차를 찾으세요. 좋은 신호는 에이전트에게 같은 내용을 세 번 설명했거나, CLAUDE.md의 한 섹션이 열 개 작업 중 한 개에서만 필요한 경우입니다.
2. 폴더를 만드세요. .claude/skills/<이름>/을 만들고 안에 SKILL.md를 둡니다.
3. frontmatter를 작성하세요. name과 description을 적고, 언제 이 스킬을 써야 하는지 분명히 씁니다.
4. 단계를 설명하세요. 구체적인 명령과 완료 기준을 적습니다. 무엇을 확인해야 하고 어떤 결과를 성공으로 볼지 정합니다.
5. 긴 내용은 옆 파일로 옮기세요. 주요 텍스트에서 그 파일을 가리킵니다.
6. CLAUDE.md의 중복을 지우세요. "배포는 deploy 스킬을 보세요" 같은 한 줄 안내만 남깁니다.
7. 확인하세요. 새 세션에서 스킬 이름을 말하지 않고 작업을 자연어로 요청해 봅니다. 에이전트가 스킬을 알아서 부르는지 봅니다. 부르지 않는다면 설명을 다시 쓰세요.

스킬 예시

배포 스킬

전형적인 후보입니다. 절차는 드물고 길며, 실수하면 비용이 큽니다. 스킬에는 단계 순서(먼저 시험 실행, 그다음 업로드), 올리면 안 되는 것, 결과를 확인하는 방법, 되돌리는 방법을 적습니다. 에이전트는 코드를 고칠 때마다 이것을 기억할 필요가 없고, 서버 이야기가 나왔을 때만 떠올리면 됩니다.

리뷰 스킬

---
name: review
description: 커밋 전에 현재 변경 사항을 리뷰합니다. diff 확인, 수정 사항의 오류 찾기, 커밋 준비를 요청받을 때 사용합니다.
---

# 변경 사항 리뷰

1. diff 가져오기: `git diff`와 `git diff --staged`.
2. 변경된 각 파일을 다음 항목으로 확인합니다.
   - 사용자 입력은 출력할 때 이스케이프되는가;
   - SQL 쿼리는 매개변수화되었는가;
   - 디버그 출력이나 임시 파일이 남아 있지 않은가.
3. 프로젝트의 테스트와 린터를 실행합니다(명령은 CLAUDE.md에 있습니다).
4. 보고: 문제를 파일과 줄 번호와 함께 심각도 순으로 나열합니다.
   문제가 없다면 그렇게 쓰고, 지어낸 지적은 넣지 마세요.

이런 스킬은 "전체적으로 괜찮은지 봐 줘"라는 요청을 매번 같은 항목으로 이루어진 재현 가능한 검사로 바꿉니다.

세션 종료 스킬

또 하나의 유용한 유형은 작업을 마칠 때 하는 의식입니다. 로컬 환경을 중지하고, 임시 파일을 지우고, 진행 기록에 무엇을 했고 무엇이 남았는지 적고, 자세한 설명과 함께 커밋합니다. 세션 간 컨텍스트가 사라지는 문제를 직접 해결합니다. 다음 세션은 추측이 아니라 저장소의 최신 상태에서 시작합니다.

흔한 실수

• 모호한 설명. 스킬은 있는데 에이전트가 부르지 않습니다. description을 구체적인 트리거가 담기게 다시 쓰면 해결됩니다.
• 스킬이 소설처럼 긴 경우. 오래된 400줄짜리 섹션을 통째로 SKILL.md에 옮겼습니다. 컨텍스트 부풀림 문제가 나중에 다시 나타납니다. 주요 본문은 짧게, 상세 내용은 옆 파일에 두세요.
• CLAUDE.md와 중복. 같은 절차가 두 곳에 적혀 있으면 시간이 지나며 어긋납니다. 원본은 하나여야 합니다.
• 겹치는 스킬. 설명이 비슷한 스킬 두 개가 있으면 에이전트는 무작위로 고릅니다. "사용할 때 / 사용하지 않을 때"를 명확히 나누세요.
• 낡은 명령. 스크립트 이름을 바꿨는데 스킬은 옛 이름을 가리킵니다. 스킬은 프로젝트 코드의 일부입니다. 절차를 바꿀 때 같은 커밋에서 스킬도 고치세요.

언제 섹션을 스킬로 옮길지 판단하는 법

주기적으로 CLAUDE.md를 살펴보며 각 섹션에 대해 물어보세요. 일반적인 작업의 몇 퍼센트에서 정말 필요한가? 거의 항상 필요하다면 제자리에 두세요. 열 개 중 한 개의 작업에서만 필요하다면 스킬의 후보입니다.

두 번째 신호는 길이입니다. 한 화면에 들어가지 않는 섹션은 거의 확실히 규칙이 아니라 절차를 설명하고 있습니다. 절차는 실행하는 순간에 통째로 읽는 편이 좋고, 세션 내내 배경에 쥐고 있을 필요는 없습니다.

세 번째 신호는 반복되는 설명입니다. 같은 작업에 대해 같은 보충 설명을 계속 적고 있다면, 한 번만 스킬에 적으세요. 일주일 뒤 손으로 고치는 횟수가 줄었는지 보면 스킬이 제 역할을 하는지 알 수 있습니다.

요약

Claude Code 스킬은 절차를 프로젝트 옆에 보관하면서도 매 세션마다 컨텍스트를 낭비하지 않게 해 줍니다. 스킬의 설명은 항상 보이고, 본문은 필요할 때 불러오고, 보조 파일은 그보다 더 나중에 불러옵니다. CLAUDE.md에는 프로젝트 지도와 엄격한 규칙을 두고, 배포, 리뷰, 릴리스처럼 특정 유형의 작업은 스킬로 옮기세요. 지침 파일의 구조와 점진적 공개 원칙은 harness engineering 과정에서 실습과 함께 다룹니다.