AI 아버지

AI 해결 노트 · 2026-09-28 · 공식 문서 확인 2026-09-28 · English version

클로드 코드 스킬 사용법: 설치 후 인식 안 될 때 확인할 것

어디에서 막혔는지 먼저 구분하기

스킬을 저장했는데 클로드가 평소처럼 답한다면, 파일 전체를 다시 쓰기 전에 증상을 구분해 보세요. 파일을 찾지 못한 경우, 찾았지만 선택하지 않은 경우, 선택한 뒤 지시를 놓친 경우는 확인할 곳이 다릅니다.

이 글은 2026년 9월 28일 확인한 공식 문서를 바탕으로 작성한 참고 안내입니다. 이번 글을 위해 Claude Code를 실제 PC에서 실행해 재현하지는 않았습니다. 아래 입력문과 확인 기준은 독자가 따라 해 볼 수 있도록 만든 예시이며, 실제 실행 결과를 옮긴 것이 아닙니다.

현재 증상먼저 볼 곳남겨 둘 내용
스킬을 사용할 수 없는 것 같음파일 위치와 세션 환경파일 전체 경로, 로컬·클라우드 여부
직접 부르면 되는데 일반 요청에서는 실행되지 않음호출 설정과 description입력한 문장과 선택된 스킬
수정 전 내용이나 다른 점검표가 나옴같은 이름의 파일실제로 수정한 파일의 위치
스킬은 불렀지만 요구사항을 빠뜨림본문 지시와 제공한 자료빠진 항목 하나와 해당 답변

원본을 보관하고 한 번에 한 항목만 바꾸는 편이 좋습니다. 경로, 이름, 설명을 모두 고친 뒤 잘되면 무엇이 원인이었는지 알기 어렵습니다. 같은 입력문으로 수정 전후를 비교하세요.

SKILL.md 파일과 저장 위치 확인

프로젝트 경로는 .claude/skills/invoice-review/SKILL.md, 개인용 경로는 ~/.claude/skills/invoice-review/SKILL.md입니다. Cowork·클라우드 세션은 이 로컬 개인용 파일을 불러오지 않습니다. 공식 문서의 저장 위치를 참고하세요.

편집기에서 실제 파일명을 보고 확장자까지 포함한 전체 경로를 적어 보세요. 파일을 저장한 저장소와 현재 연 저장소가 같은지도 확인합니다. 폴더 이름만 기억하면 복사본이나 다른 작업 폴더를 고치기 쉽습니다.

Agent Skills 규격은 SKILL.md를 담은 폴더와 YAML 머리말, 그 뒤의 Markdown 지시문을 정의합니다. 공통 형식에서는 name과 description이 필수입니다. 이름은 폴더와 같게 쓰고 영문 소문자·숫자·하이픈을 사용하면 됩니다. 특정 도구에서 일부 항목을 생략할 수 있어도, 여러 도구에서 쓸 파일이라면 둘 다 적어 두세요.

아래는 이 글을 위해 만든 최소 예시입니다. 대화에 붙여 넣은 청구서 텍스트만 검토하므로 별도 스크립트나 외부 연결, 실제 청구서 파일을 준비할 필요가 없습니다. 코드 블록 전체를 위의 프로젝트 경로에 저장합니다.

---
name: invoice-review
description: 대화에 붙여 넣은 청구서의 번호, 공급자, 발행일, 통화, 합계가 빠졌는지 확인합니다. 내부 검토 전 청구서 필수 항목 확인을 요청할 때 사용합니다. 일반적인 글쓰기에는 사용하지 않습니다.
---

## 할 일

현재 대화에 제공된 청구서 텍스트만 검토합니다.
청구서 내용이 없으면 먼저 붙여 넣어 달라고 요청합니다.

## 확인 순서

청구서 번호, 공급자, 발행일, 통화, 합계의 다섯 항목을 나열합니다.
각 항목에 제공된 값을 적고, 없으면 "누락"으로 표시합니다.
없는 값을 만들거나 모호한 기호만으로 통화를 추정하지 않습니다.
마지막에 추가 확인이 필요한 누락 항목을 적습니다.
지급 승인이 끝났다고 표현하지 않습니다.

여기서 확인하는 것은 다섯 항목이 적혀 있는지뿐입니다. 청구서의 진위나 지급 가능 여부, 회사 회계 규정 충족 여부까지 판단하는 예제가 아닙니다. 실제 업무로 넓히기 전에는 어떤 결과를 받아야 하는지부터 정해야 합니다.

직접 호출과 자동 호출 설정 확인

YAML 설정직접 호출자동 호출
기본값가능허용
disable-model-invocation: true가능차단
user-invocable: false메뉴 숨김, /name 불가허용

다른 설정은 기본값이라는 전제입니다. 자동 선택 여부는 요청에 따라 달라집니다. 공식 호출 제어 설명을 참고하세요.

이 예시는 두 설정을 모두 생략하고 확인하면 됩니다. 인식이 안 된다는 이유로 도구 실행 권한부터 추가하지 마세요. 먼저 원하는 지시문을 불러오는지 확인하고, 그 뒤에 결과를 살펴보면 원인을 좁힐 수 있습니다.

이름 충돌과 설명을 따로 살펴보기

공식 확장 기능 안내에 따르면 스킬 설명은 작업에 맞는 스킬을 선택하는 데 쓰입니다. 설명이 지나치게 넓거나 서로 겹치면 선택이 어려워질 수 있습니다. /invoice-review로 직접 부르면 자동 선택과 본문 지시를 나누어 확인하기 좋습니다.

이 예시의 설명에는 자료의 형태인 ‘붙여 넣은 청구서’와 작업인 ‘필수 항목 확인’이 들어갑니다. ‘회사 업무를 도와준다’처럼 넓게 쓰는 것보다 범위를 판단하기 쉽습니다. 원하지 않는 작업도 구체적으로 적었습니다. 회의 알림문을 부탁했을 때 청구서 점검표가 나올 필요는 없습니다.

프로젝트 파일을 바꿨는데 이전 지시가 보이면 같은 이름의 개인용 파일부터 살펴보세요. 같은 스킬 이름의 우선순위는 조직 관리용, 개인용, 프로젝트용 순서입니다. 플러그인 스킬에는 /플러그인이름:스킬이름처럼 이름 공간이 붙습니다. 이 규칙도 확장 기능 안내에서 설명합니다.

독자가 해 볼 두 가지 확인 예시

앞 대화의 지시 때문에 우연히 원하는 답이 나오지 않도록, 비교하는 요청은 각각 새 대화에서 확인하는 편이 좋습니다.

예시 1: 스킬을 직접 지정하기

/invoice-review
청구서 번호: INV-104
공급자: 예시스튜디오
발행일: 2026-09-28
합계: 120

다섯 항목을 다루고 통화를 ‘누락’으로 표시하는지 확인하세요. 원화로 임의 결정하거나 지급해도 된다고 답하면 이 예시의 지시를 충족하지 못한 것입니다. 표가 깔끔하게 나왔다는 것만으로 성공으로 보지는 않습니다.

예시 2: 관련 요청과 무관한 요청 비교하기

새 대화에서 슬래시 명령 없이 같은 가상 청구서를 주고 필수 항목을 확인해 달라고 요청합니다. 다른 새 대화에서는 회의 안내 문장 하나를 써 달라고 해 보세요. 청구서 요청에서 해당 스킬이 선택됐는지, 회의 안내에 불필요한 점검표가 붙는지 기록합니다. 답변이 그럴듯하다는 이유만으로 스킬이 선택됐다고 단정하지 마세요.

계속 안 될 때 남길 기록

Claude Code 버전, 로컬·클라우드 여부, 파일 경로, 요청문, 바꾼 설정, 실제 답변을 한곳에 모아 두세요. ‘스킬이 안 된다’는 설명보다 이 기록으로 도움을 요청하는 편이 원인을 찾기 쉽습니다. 공식 권장 사용법도 구체적인 맥락과 확인 가능한 결과 기준을 권합니다.

이 안내가 자동 선택이나 결과의 정확성을 보장하지는 않습니다. 작은 예시를 통해 다음에 살펴볼 곳이 파일 로딩인지, 이름인지, 지시문인지 구분하는 데 활용하세요. Claude Code를 업데이트한 뒤에는 현재 문서와 다시 대조하는 것이 좋습니다.

출처와 확인 범위