Skills

https://code.claude.com/docs/ko/skills

Claude를 skills로 확장하기 - Claude Code Docs

 

🤖 Claude Code Skills

— “AI에게 일하는 방식을 가르친다”는 것의 진짜 의미

 

🧠 Skills란 무엇인가?

Claude Code에서의 Skills는 단순한 함수나 기능이 아닙니다.

👉 “특정 작업을 수행할 때 Claude가 참고하는 작업 매뉴얼”입니다.

조금 더 본질적으로 말하면:

💡 “이 프로젝트에서 이 작업은 이렇게 해”를 정의한 맥락적 규칙 집합

즉, 소프트웨어 개발회사의 신입 개발자에게 주는 온보딩 문서를
👉 AI에게 준다고 생각하시면 정확합니다.

 

🏗️ Claude Code에서 Skills가 동작하는 방식

Claude Code는 프로젝트를 열면 자동으로 다음 경로를 인식합니다:

.claude/skills/

그리고 작업 요청을 받으면:

1. 🔍 요청 내용을 분석하고
2. 🎯 관련된 스킬을 자동으로 매칭
3. 📚 해당 스킬을 참고해서 코드 생성

⚙️ 실제 동작 예시

개발자: "주문 취소 API endpoint 추가해줘"

 

Claude Code 내부에서는 이렇게 흘러갑니다:

"endpoint 추가"
  → rtk-query-api 스킬 트리거

"주문"
  → mock-architecture 스킬 트리거

→ 두 스킬을 조합해서 코드 생성

 

✅ 핵심 포인트:

❗ 개발자는 “스킬 적용해줘”라고 말할 필요가 없습니다
👉 그냥 평소처럼 작업 지시만 하면 됩니다

 

📁 기본 디렉토리 구조

your-project/
├── .claude/
│   └── skills/
│       ├── 01-dev-standards.skill
│       ├── 02-auth-security.skill
│       ├── 03-rtk-query-api.skill
│       ├── 04-mock-architecture.skill
│       ├── 05-styling.skill
│       ├── 06-app-structure.skill
│       └── 07-auto-doc-sync.skill
├── src/
├── docs/
└── ...

 

📌 .claude/ 폴더는
👉 Claude 관련 설정을 모아두는 사실상의 표준 위치입니다.

 

🛠️ Skills 작성 흐름 (실전 프로세스)

1️⃣ 반복 작업을 발견한다

"이거 계속 반복하는데?"

 

2️⃣ SKILL.md 작성

해당 작업의 규칙, 예제, 방식 정리

 

3️⃣ Claude Code에서 사용

실제로 돌려보며 개선

🔥 가장 많이 쓰는 방식 (현실적인 패턴)

👉 “작업하다가 스킬로 굳히기”

작업 중 →
"이 패턴 계속 쓰겠는데?" →
"이걸 스킬로 만들어줘" →
Claude가 기존 작업 기반으로 SKILL.md 생성

💡 이 방식이 가장 자연스럽고 효율적입니다.

 

⚠️ 현실적인 주의사항 (중요)

1. 스킬 트리거는 “description 품질”에 달려있다

• ❌ 너무 추상적이면 → 트리거 안 됨
• ❌ 너무 넓으면 → 과도하게 트리거됨

👉 반드시 테스트 필요

 

2. 트리거가 안 되면 이렇게 해결

"auth-security 스킬 참고해서 OAuth2 콜백 구현해줘"

👉 스킬 이름을 직접 언급하면 100% 트리거됩니다

 

3. 결국 사람의 역할은 남는다

Claude가 초안을 잘 만들어주지만:

✔ 스킬 분리 단위 설계
✔ 트리거 문구 튜닝
✔ 예제의 현실 적합성 검증

👉 이건 반드시 사람이 판단해야 합니다

 

🧪 초보자를 위한 가장 현실적인 접근법

처음부터 스킬을 잘게 나누려 하면 거의 실패합니다 😅

대신 이 흐름을 추천드립니다:

 

✅ Step 1. CLAUDE.md 작성

👉 그냥 README 쓰듯이

• 프로젝트 규칙
• 코딩 스타일
• 아키텍처
• API 패턴

💡 완벽하게 쓸 필요 없음 → 생각 dump

 

✅ Step 2. Claude에게 스킬 생성 요청

"이 CLAUDE.md 기반으로 스킬 만들어줘"

👉 Claude가 자동으로:

• 스킬 분리
• 구조 설계
• 예제 생성

✅ Step 3. CLAUDE.md 슬림화

👉 스킬로 분리되면서 자연스럽게 정리됨

 

✅ Step 4. 실제 사용하면서 개선

👉 여기서 진짜 품질이 올라갑니다

 

🧩 핵심 인사이트

❗ Skills의 본질

❌ 기능(Function)이 아니다

 

✅ “작업 방식(How to work)”을 정의하는 것

❗ 좋은 스킬의 특징

• 🎯 트리거가 명확하다
• 📚 예제가 현실적이다
• 🔁 재사용성이 높다
• ⚖️ 범위가 적절하다 (너무 크지도 작지도 않음)

❗ 가장 중요한 한 줄

💡 “Claude를 잘 쓰는 방법 = Claude에게 일을 잘 가르치는 것”

 

🚀 마무리

Claude Code의 Skills는 단순한 자동화 도구가 아닙니다.

👉 AI와 협업하는 방식 자체를 설계하는 레이어입니다.

처음에는 어색하지만:

• 하나씩 스킬을 만들고
• 실제로 써보고
• 계속 다듬다 보면

어느 순간 👇

🔥 “AI가 우리 팀의 개발 스타일로 일한다”

라는 경험을 하게 됩니다.