Claude Code 스킬 작성부터 재사용까지 문제 해결법

Claude Code 실전 트러블슈팅

Claude Code에서 만든 스킬이 호출해도 반응이 없다면, 기능이 아니라 파일 구조 문제일 확률이 높습니다.

디렉토리 배치, 프롬프트 작성법, 재사용 설정, 디버깅 팁까지 스킬 관련 문제를 한 번에 정리합니다.

📌 3줄 요약

• 스킬은 .claude/skills/스킬이름/skill.md 경로를 정확히 지켜야 인식됩니다.
• 프롬프트가 길면 뒷부분 규칙이 무시되므로 핵심 5~7개 이내로 유지하고, 나머지는 references/로 분리하세요.
• 여러 프로젝트에서 재사용하려면 절대 경로를 제거하고, 글로벌 스킬과 프로젝트 스킬의 이름 충돌을 점검하세요.

📑 목차

• 1. 스킬 파일 구조를 잘못 만들면 인식되지 않습니다
• 2. 커스텀 스킬 작성 시 흔한 오류와 수정법
• 3. 여러 프로젝트에서 스킬 재사용이 안 될 때 점검 포인트
• 4. 스킬 디버깅과 유지보수 실전 팁

스킬 파일 구조를 잘못 만들면 인식되지 않습니다

Claude Code에서 스킬(Skill)은 반복적으로 쓰는 프롬프트나 작업 흐름을 하나의 파일로 묶어 재사용하는 기능입니다. 직접 만든 스킬이 /skill-name으로 호출했을 때 아무 반응이 없다면, 십중팔구 파일 구조 문제입니다. 스킬 기능 자체를 모르는 것이 아니라 디렉토리 배치 한 칸 차이로 인식이 안 되는 경우가 대부분이라, 처음 접하면 원인을 찾기가 쉽지 않습니다.

스킬은 .claude/skills/스킬이름/ 디렉토리 안에 skill.md 파일이 반드시 존재해야 합니다. 이 경로를 벗어나거나 파일명이 다르면 Claude Code가 스킬을 인식하지 못합니다. 예를 들어 skill.txt나 index.md 같은 이름을 사용하면 구조가 맞더라도 무시됩니다.

⚠️ 주의: 가장 흔한 실수는 .claude/skills/ 바로 아래에 마크다운 파일을 놓는 것입니다.

올바른 구조는 다음과 같습니다.

.claude/
  skills/
    my-skill/          ← 스킬 이름 디렉토리
      skill.md         ← 필수 파일
      references/      ← 참조 파일 디렉토리 (선택)
        rules.md

skill.md 안에는 프론트매터(frontmatter) 없이 바로 프롬프트 내용을 작성하면 됩니다. 파일 인코딩은 UTF-8이어야 하며, BOM이 포함된 파일은 파싱 오류를 일으킬 수 있습니다.

💡 팁: Windows 환경에서 메모장으로 파일을 만들면 BOM이 자동으로 붙는 경우가 있으니, VS Code나 다른 코드 편집기를 사용하는 것이 안전합니다.

 

또 하나 놓치기 쉬운 점은 디렉토리 이름에 공백이나 특수문자를 쓰는 경우입니다. 스킬 디렉토리명은 영문 소문자와 하이픈(-)만 사용하는 것이 안전합니다. 대문자를 포함한 camelCase 이름도 운영체제에 따라 인식 여부가 달라질 수 있으므로 피하는 것이 좋습니다.

💬 제가 직접 스킬을 처음 만들었을 때, .claude/skills/mySkill.md처럼 파일을 바로 넣어서 한참 헤맸습니다. 디렉토리를 하나 더 만들어야 한다는 점이 직관적이지 않지만, 이 구조 덕분에 참조 파일을 함께 묶을 수 있어 결국 편리합니다. 구조를 한번 제대로 잡아두면 이후에는 디렉토리만 복사해서 새 스킬을 빠르게 만들 수 있습니다.

커스텀 스킬 작성 시 흔한 오류와 수정법

구조가 맞는데도 스킬이 의도대로 동작하지 않는다면, skill.md 내용 자체에 문제가 있을 가능성이 높습니다. 스킬 파일은 Claude에게 보내는 시스템 프롬프트 역할을 하기 때문에, 지시가 모호하면 결과도 들쭉날쭉합니다. 특히 "적절하게 처리해줘"처럼 추상적인 표현을 쓰면 매번 다른 결과가 나올 수 있습니다.

🔍 트리거 조건이란?

skill.md 상단에 어떤 상황에서 이 스킬을 사용할지 명시하지 않으면, Claude Code가 자동으로 호출 시점을 판단하지 못합니다. 트리거 조건은 사용자가 어떤 명령을 입력하거나 어떤 상황일 때 이 스킬이 활성화되는지를 구체적으로 적어야 합니다.

# my-formatter 스킬

이 스킬은 사용자가 /my-formatter를 호출하거나
코드 포맷팅을 요청할 때 사용합니다.

## 규칙
- 들여쓰기는 스페이스 2칸으로 통일합니다
- 줄 끝 세미콜론을 제거합니다

두 번째 흔한 실수는 스킬 안에서 존재하지 않는 도구나 파일 경로를 참조하는 것입니다. 예를 들어 references/ 안의 파일을 언급하면서 실제로는 해당 파일을 만들지 않은 경우가 많습니다. 이때 Claude Code는 에러를 명시적으로 보여주지 않고 해당 참조를 조용히 무시하기 때문에, 규칙 일부가 빠진 채로 동작하게 됩니다.

 

세 번째는 스킬 프롬프트가 너무 길거나 복잡한 경우입니다. 하나의 스킬에 여러 작업을 몰아넣으면 Claude가 일부 지시를 누락하는 현상이 발생합니다. 실제로 규칙을 15개 이상 나열하면 앞부분 규칙은 잘 따르지만 뒷부분은 반영되지 않는 경우가 빈번합니다.

💡 팁: 이런 경우 스킬을 기능 단위로 분리하는 것이 효과적입니다. my-skill-lint와 my-skill-format처럼 나누면 각 스킬의 동작이 훨씬 안정적입니다. 분리된 스킬은 필요에 따라 순서대로 호출하거나, 오케스트레이터 스킬에서 조합하여 사용할 수도 있습니다.

💬 제가 써보니 스킬 하나에 규칙을 10개 이상 넣으면 뒷부분 규칙이 무시되는 경향이 있었습니다. 핵심 규칙 5~7개 이내로 유지하고, 세부 사항은 references/ 파일로 분리하는 방식이 가장 안정적이었습니다.

여러 프로젝트에서 스킬 재사용이 안 될 때 점검 포인트

커스텀 스킬의 진짜 가치는 한 프로젝트가 아니라 여러 프로젝트에서 동일한 워크플로우를 재사용할 수 있다는 점입니다. 그런데 A 프로젝트에서 잘 되던 스킬이 B 프로젝트에서는 안 되는 경우가 종종 발생합니다. 이 문제는 대부분 스킬 내부의 환경 의존성 때문에 생기며, 몇 가지 점검 포인트만 확인하면 빠르게 해결할 수 있습니다.

가장 큰 원인은 스킬 내부에 절대 경로나 프로젝트 고유 값이 하드코딩된 경우입니다. /home/user/projectA/src/ 같은 경로 대신 상대 경로나 변수를 사용해야 합니다. 특정 브랜치명이나 리포지토리 URL이 하드코딩된 경우도 마찬가지로 다른 프로젝트에서 오류를 일으킵니다.

## 규칙
- 프로젝트 루트 기준 상대 경로를 사용합니다
  ✗ /home/user/projectA/output/
  ✓ output/

 

🔍 글로벌 스킬이란?

프로젝트의 .claude/skills/ 대신 사용자 홈 디렉토리의 ~/.claude/skills/에 스킬을 배치하면 모든 프로젝트에서 접근할 수 있습니다. 이 방식은 코드 리뷰, 포맷팅, 커밋 메시지 작성처럼 프로젝트에 관계없이 공통으로 쓰는 스킬에 특히 유용합니다.

⚠️ 주의: 글로벌 스킬과 프로젝트 스킬의 이름이 같으면 프로젝트 스킬이 우선 적용됩니다. 이 우선순위를 모르면 "분명 수정했는데 반영이 안 된다"는 혼란에 빠지게 됩니다. 글로벌 스킬을 수정했는데 프로젝트에 같은 이름의 스킬이 남아 있으면 수정 사항이 무시되므로, 이름 충돌이 없는지 먼저 확인하는 습관이 중요합니다.

재사용성을 높이려면 스킬 프롬프트에서 프로젝트 특화 정보를 분리하는 것이 핵심입니다. 공통 로직은 skill.md에, 프로젝트별 설정은 references/ 디렉토리에 넣어 관리하면 됩니다.

💬 제가 여러 프로젝트에 같은 포맷팅 스킬을 적용해본 결과, references/ 파일만 프로젝트별로 교체하는 구조가 가장 유지보수하기 편했습니다. 처음에는 스킬 전체를 복사했는데, 규칙 하나를 바꿀 때마다 모든 프로젝트를 수정해야 하는 문제가 생겼습니다.

스킬 디버깅과 유지보수 실전 팁

스킬을 만들고 나서 시간이 지나면 의도대로 동작하지 않는 경우가 생깁니다. 이때 체계적으로 디버깅하는 방법을 알아두면 시간을 크게 절약할 수 있습니다. 특히 스킬이 여러 개로 늘어난 뒤에는 어떤 스킬에서 문제가 발생했는지 범위를 좁히는 것이 첫 번째 과제입니다.

1

스킬 프롬프트 확인하기 — Claude Code에서 /skill-name을 호출한 뒤 "방금 받은 스킬 프롬프트를 그대로 보여줘"라고 요청하면 Claude가 인식한 내용을 확인할 수 있습니다. 이 방법으로 references/ 파일이 제대로 로드되었는지, 프롬프트 내용이 잘렸는지 등을 한눈에 파악할 수 있습니다.

2

버전 번호 기록하기 — skill.md 상단에 v1.2 — 2026-08-09 수정 같은 한 줄을 추가해두면, 어떤 버전이 적용되고 있는지 즉시 파악됩니다. 여러 프로젝트에 같은 스킬을 배포한 경우, 버전 번호로 어떤 프로젝트가 최신인지 바로 비교할 수 있어서 관리가 훨씬 수월해집니다.

# my-formatter 스킬 (v1.2 — 2026-08-09)

이 스킬은 코드 포맷팅 규칙을 적용합니다.

 

3

참조 파일 존재 여부 점검하기 — 스킬이 참조하는 references/ 파일이 실제로 존재하는지 주기적으로 점검해야 합니다. 프로젝트 구조가 바뀌면서 참조 파일 경로가 깨지는 일이 생각보다 자주 발생합니다. 간단한 점검 방법은 스킬 디렉토리에서 ls references/를 실행해 파일 목록을 확인하는 것입니다. skill.md에 언급된 파일명과 실제 파일명이 일치하는지 대조해보면 누락된 참조를 금방 찾을 수 있습니다.

4

스킬 하나당 하나의 책임 원칙 — "포맷팅 + 린트 + 테스트"를 하나에 넣기보다, 각각 별도 스킬로 만들어 필요할 때 조합하는 방식이 훨씬 안정적입니다. 이렇게 분리하면 특정 스킬만 업데이트하거나 비활성화하는 것도 쉬워지고, 문제가 생겼을 때 원인을 빠르게 특정할 수 있습니다.

💬 제가 운영 중인 블로그 자동화 시스템도 topic-finder, draft-writer, quality-reviewer처럼 역할별로 스킬을 분리해두었습니다. 처음에는 번거로워 보였지만, 한 스킬에 문제가 생겨도 나머지는 정상 동작하기 때문에 디버깅 범위가 좁아져서 훨씬 관리하기 수월합니다.

✍️ 마치며

Claude Code 스킬은 파일 구조만 정확히 맞추면 반복 작업을 크게 줄여주는 강력한 기능입니다. .claude/skills/스킬이름/skill.md 경로를 지키고, 프롬프트는 핵심 규칙 5~7개 이내로 유지하며, 프로젝트 특화 정보는 references/로 분리하세요. 스킬이 늘어나면 하나당 하나의 책임 원칙을 지키고, 버전 번호를 기록하는 습관까지 갖추면 장기적으로 안정적인 워크플로우를 유지할 수 있습니다.

#ClaudeCode #클로드코드스킬 #커스텀스킬만들기 #스킬디버깅 #AI코딩도구 #개발자동화