Claude Code 스킬, 왜 자꾸 이상하게 동작할까?

요즘 Claude Code 쓰다 보면 “이거 왜 이렇게 말 안 듣지?” 싶은 순간 한 번쯤 있었을 거야.
근데 이건 모델 문제라기보다, 대부분 스킬을 만드는 방식 자체가 잘못된 경우가 많아.

결론부터 말하면, 스킬은 프롬프트가 아니라 하나의 시스템처럼 만들어야 한다는 거야.

 

[Source: ChatGPT. 생성]

 

스킬은 그냥 문서가 아니라 “폴더”야

많은 사람들이 착각하는 게 있어. 스킬 = SKILL.md 하나??? 근데 실제 구조는 이게 아니야.
스킬은 기본적으로 폴더 단위 패키지야.

• instructions (SKILL.md)
• reference 문서
• 예제
• 스크립트

이걸 묶어서 하나의 단위로 쓰는 거지. 실제로 Claude 공식 문서에서도 스킬은 “instructions, scripts, resources를 묶은 폴더”라고 설명해. 즉, 프롬프트 하나 잘 쓰는 문제가 아니라 지식 구조를 설계하는 문제야.

 

왜 SKILL.md 하나로 만들면 망하냐

이거 진짜 핵심이야. Claude는 모든 내용을 다 읽고 쓰는 게 아니라 필요한 것만 골라서 불러오는 구조야.

이걸 “점진적 로딩”이라고 보면 돼.

• 길게 다 때려 넣으면 → 오히려 성능 떨어지고
• 쪼개서 넣으면 → 필요한 것만 정확히 사용함

실제로 스킬은 필요할 때만 로딩되도록 설계돼 있어. 그래서 구조는 이렇게 가는 게 맞아.

/skill
 ├─ SKILL.md (요약 + 트리거)
 ├─ reference.md
 ├─ examples.md
 ├─ scripts/
 └─ gotchas.md

 

이건 그냥 정리 습관이 아니라 성능 자체를 좌우하는 구조야.

 

좋은 스킬은 “하나만 한다”

이것도 되게 중요한 포인트야. 스킬을 만들 때 욕심이 생기거든.

• 이것도 하고
• 저것도 하고
• 다 처리하게 만들고 싶고

근데 이렇게 하면 무조건 망해. 왜냐면 Claude 입장에서 “지금 뭘 해야 하는지” 판단이 흐려지거든.

그래서 원칙은 하나야. "스킬 하나 = 역할 하나"

• PR 리뷰 스킬
• 배포 확인 스킬
• 테스트 생성 스킬

이렇게 쪼개야 제대로 동작해.

 

진짜 핵심: Gotchas가 성능을 만든다

이건 진짜 실무에서 바로 체감되는 부분이야. 보통 사람들은 “정답”만 적어놓거든. 근데 중요한 건 오히려 반대야.

• 항상 이 API 순서 틀림
• 이 파일 건드리면 에러 남
• 이 조건 빠지면 장애 발생

이걸 계속 쌓으면 어떻게 되냐면 스킬이 점점 똑똑해지는 게 아니라 실수 안 하는 구조로 진화해. 결국 Gotchas는 단순 메모가 아니라
조직의 실패 데이터베이스야.

 

Description이 사실상 “자동 실행 조건”이야

이건 진짜 많이 놓치는 포인트야. 스킬에서 제일 중요한 건 이름이 아니라 description이야.

왜냐면 Claude는 이걸 보고 “이거 써야겠다” 판단하거든.

예를 들어

• ❌ "deploy skill" → 언제 쓰는지 모름
• ✅ "PR merge 이후 배포 상태 확인 시 사용" → 바로 트리거됨

즉, description은 설명이 아니라 실행 조건 정의야.

 

On-Demand Hook = 상태 전환 버튼

이건 조금 더 고급 개념인데 진짜 유용해.

• /careful → 위험 작업 차단
• /review → 코드 리뷰 모드

이런 식으로 상황에 따라 Claude 행동을 바꾸는 거야. 이걸 잘 쓰면 단순 스킬 →“상태 기반 에이전트”로 바뀐다

 

이걸 실제 프로젝트에 적용하면

여기서부터가 진짜 중요한데 이 구조는 그냥 Claude 잘 쓰는 팁이 아니라 서비스 설계 방식 자체를 바꿔버려.

1. ERP / 업무 시스템

기존 ERP는 기능 중심이야. 근데 이걸 스킬 구조로 바꾸면

• 스킬 = 업무 단위
• gotchas = 장애 로그
• description = 실행 조건

결과적으로 👉 ERP가 “에이전트 OS”처럼 동작하게 돼

2. 팀 협업 (Git 기반)

스킬 폴더를 그대로 Git에 올리면

• 조직 규칙 공유되고
• 실수 케이스 누적되고
• 자동화 재사용 가능해지고

결국 회사 자체가 하나의 AI 학습 시스템이 된다.

3. 콘텐츠 / 블로그 자동화

이건 진짜 바로 써먹을 수 있어.

• SEO 글쓰기 스킬
• 뉴스 요약 스킬
• 카피라이팅 스킬

이렇게 나누면 👉 콘텐츠 생산이 “반자동 시스템”으로 변경

 

정리해보면

Claude Code 스킬은 잘 쓰면 진짜 강력한데 대부분은 이렇게 쓰고 있어.

• 프롬프트처럼 만든다 → 실패
• 한 파일에 몰아넣는다 → 실패
• 규칙만 적는다 → 실패

반대로 잘 되는 구조는 이거야.

• 폴더로 설계한다
• 역할을 쪼갠다
• 실패를 기록한다
• 조건을 명확히 쓴다

결국 핵심은 하나야. 스킬은 기능이 아니라 “조직의 경험을 구조화한 시스템”이야

이 관점으로 바꾸는 순간 Claude는 그냥 도구가 아니라 진짜 “에이전트”처럼 움직이기 시작해

이게 이번 영상에서 가장 중요한 포인트였어.