Claude Code Skills 완전정복 — SKILL.md로 나만의 작업 절차서 만들기

 

같은 작업을 매번 "이렇게 저렇게 해줘"라고 설명하기 지치셨나요? Claude Code의 Skills는 AI에게 "이 상황엔 이 절차로"라는 전문 매뉴얼을 미리 쥐여주는 기능이에요. 필요할 때 Claude가 알아서 꺼내 씁니다. SKILL.md 파일 하나로 나만의 스킬을 만드는 법을 정리합니다. (서브에이전트와 짝이니 서브에이전트 /147도 함께)

📌 30초 요약

✓ Skills = SKILL.md + 스크립트·리소스를 담은 폴더
✓ 저장: .claude/skills/ · 핵심은 description(자동 발동 열쇠)
✓ Progressive disclosure — 수십 개 깔아도 안 무거움
💡 슬래시 명령은 직접 호출, Skills는 상황 인식해 스스로 발동

Skills가 뭔가요?

스킬은 지침·스크립트·리소스를 담은 폴더예요. 그 안의 SKILL.md가 핵심으로, YAML 머리말(name·description) + 마크다운 본문(작업 지침)으로 이뤄집니다. Claude가 지금 상황에 이 스킬이 맞다 싶으면 그 절차서를 읽고 그대로 수행해요.

💡 쉽게 말해 "우리 팀은 배포를 이 순서로 한다", "보고서는 이 양식으로" 같은 반복 노하우를 문서로 박제해 AI에게 물려주는 거예요.

핵심 원리 — Progressive Disclosure

Skills가 강력한 이유. Claude는 평소엔 각 스킬의 이름·설명만(스킬당 약 100토큰) 훑어봐요. 그러다 관련 작업이 오면 그때 전체 지침을 로드하고, 번들된 스크립트·문서는 실제로 필요할 때만 읽어요.

덕분에 수십 개 스킬을 깔아둬도 무관한 작업 성능엔 영향이 없고, 방대한 API 문서·데이터셋을 스킬에 넣어도 안 쓰면 컨텍스트를 안 잡아먹습니다. "필요할 때만 펼친다" — 이게 Skills의 심장이에요.

만드는 법

.claude/skills/ 아래에 스킬 이름과 같은 폴더를 만들고, 그 안에 SKILL.md를 넣으면 끝. (폴더명 = frontmatter의 name과 일치해야 해요.)

.claude/skills/pr-summary/SKILL.md

---
name: pr-summary
description: PR 설명을 작성할 때 사용. 변경 요약·테스트 방법·리스크를 정해진 양식으로 정리한다.
---

# PR 요약 작성 규칙

아래 순서로 PR 본문을 작성하라.
1. 한 줄 요약 (무엇을 왜)
2. 주요 변경 사항 (파일별 불릿)
3. 테스트 방법 (재현 단계)
4. 리스크 / 롤백 방법

이제 PR 설명을 부탁하면, Claude가 description을 보고 이 스킬이 맞다고 판단해 자동으로 이 양식대로 써줘요. 별도 명령 없이도요.

💡 description이 전부 — "언제 쓰는지"를 구체적으로 적어야 Claude가 정확히 발동해요. "PR 설명 작성할 때"처럼 상황을 명시하세요. (스킬 만드는 걸 도와주는 skill-creator 스킬도 있어요.)

스크립트·리소스도 함께

스킬 폴더엔 SKILL.md 말고도 스크립트·템플릿·참고 문서를 같이 넣을 수 있어요. 매번 비슷한 헬퍼 코드를 새로 짜고 있다면, 그걸 스킬에 번들해 두면 다음부터 바퀴를 다시 발명하지 않아도 됩니다. progressive disclosure 덕에 안 쓰면 로드도 안 되니 부담이 없어요.

Skills vs 나머지 확장들

Claude Code 확장 기능이 헷갈리기 쉬운데, 역할이 다 달라요.

기능	역할	한마디로
Skills	필요할 때 꺼내는 전문 절차서	온디맨드 노하우
CLAUDE.md	항상 적용되는 상시 규칙	기본 룰북
Hooks	특정 시점 자동 실행(포맷 등)	자동 부수효과
서브에이전트	격리된 곳에서 일 대신 처리	위임 일꾼
MCP	외부 도구·데이터 연결	외부 연결

건강한 세팅은 이들을 조합해요 — 상시 규칙은 CLAUDE.md, 전문 절차는 Skills, 자동 처리는 Hooks, 위임은 서브에이전트, 외부 도구는 MCP. (Skill vs MCP가 더 궁금하면 /94)

핵심 한 줄

반복 노하우를 SKILL.md에 박제
필요할 때 알아서 발동

수십 개 깔아도 안 무거운 게 progressive disclosure의 힘

⚠️ 이건 알아두세요

발동이 안 되면 대개 description이 모호한 탓이에요. "언제 쓰는지"를 구체적으로 적으세요. 또 서브에이전트는 스킬을 자동 상속하지 않아, 필요하면 그 에이전트의 frontmatter skills 필드에 명시해야 합니다(내장 Explorer·Plan 등은 스킬을 못 씀).

자주 묻는 질문 (FAQ)

Q. 슬래시 명령이랑 뭐가 다르죠?

슬래시 명령은 내가 직접 타이핑해야 실행돼요. Skills는 Claude가 상황을 인식해 스스로 꺼내 씁니다. "발동 조건"을 description에 맡기는 셈이죠.

Q. 스킬을 많이 만들면 느려지나요?

아니요. progressive disclosure 덕에 평소엔 이름·설명만 보고, 쓸 때만 전체를 로드해요. 수십 개도 부담 없어요.

Q. 남이 만든 스킬을 가져다 쓸 수 있나요?

네. 스킬은 그냥 폴더라 공유·설치가 쉬워요. Anthropic 공식 저장소와 커뮤니티에 좋은 스킬이 많습니다.

마치며

Skills는 "매번 설명하던 노하우"를 한 번만 적어 AI에게 물려주는 기능이에요. 자주 하는 작업일수록 효과가 커요.

오늘 자주 반복하는 작업 하나를 골라 SKILL.md로 만들어 보세요. CLAUDE.md /76 · Hooks /112 · 서브에이전트 /147까지 함께 쓰면, Claude Code가 나에게 완전히 맞춰진 도구가 됩니다 🚀

---

🔗 공식 문서·저장소 — Claude Code Skills 문서 · anthropics/skills (공식 스킬 모음)

※ 본 글은 Claude Code·Anthropic Agent Skills 공식 문서를 바탕으로 작성했습니다. frontmatter 필드·저장 경로 등 세부 사양은 버전에 따라 달라질 수 있어요.