파일을 만들었는데 Claude Code에서 Skill이 보이지 않거나, 요청한 작업에 자동으로 적용되지 않나요?
가장 빠른 해결은 SKILL.md를 지원 경로에 놓고, 설명과 작업 지침을 분명히 쓴 뒤 실제 요청으로 인식과 호출을 확인하는 것입니다. 경로와 메타데이터, 호출 방식은 바뀔 수 있으므로 작업 전에 공식 Skills 문서를 확인해야 합니다.
이 안내는 Claude Code에서 반복 작업을 재사용하려는 개발자를 위한 내용입니다.
프로젝트 구성원과 Skill을 공유하거나 개인 작업에만 적용하려는 경우에 적합합니다.
AI 작업 흐름을 만들고 호출 결과까지 확인해야 하는 기술 담당자도 따라 할 수 있습니다.
Claude Code 사용자 지정 Skills 만들기의 완료 기준
>Claude Code 사용자 지정 Skills는 파일을 저장하는 것만으로 완료된 것이 아닙니다. 다음 세 가지가 확인되어야 합니다.
- 의도한 작업과 경계를 설명하는
SKILL.md가 있습니다. - 파일이 프로젝트 또는 사용자 범위의 지원 디렉터리에 있습니다.
- 명시적으로 호출하거나 자동 매칭을 시험해 지침이 결과에 반영되는지 확인했습니다.
Claude Code의 Skills는 작업 지침을 담은 파일로, 일반적인 프로젝트 설명이나 항상 적용할 규칙과는 쓰임이 다릅니다. 프로젝트 공통 지침과 Skill의 역할을 구분하려면 공식 메모리 문서도 함께 살펴보세요.
목적에 맞는 디렉터리와 파일 만들기
>Claude Code Skills 디렉터리는 어디에 두나요?
프로젝트에서 함께 관리하려면 저장소 안의 .claude/skills/<skill-name>/SKILL.md를 사용합니다. 개인 작업에 적용하려면 사용자 홈 아래의 ~/.claude/skills/<skill-name>/SKILL.md를 사용합니다. 경로와 로딩 규칙은 Claude Code 공식 안내에 명시된 현재 내용을 기준으로 확인하세요.
각 Skill은 전용 디렉터리 안에 SKILL.md를 둡니다. 여러 Skill을 한 폴더에 파일만 나열하는 구조로 만들지 마세요. 이름에 공백이나 밑줄을 넣지 말고, 디렉터리 이름과 메타데이터의 이름이 서로 다르지 않도록 맞추는 편이 안전합니다. 이름 형식은 Agent Skills 규격과 공식 안내를 기준으로 검토합니다.
판단 기준은 공유 범위입니다. 저장소에서 팀이 같이 개선할 작업이면 프로젝트 경로를 선택하고, 다른 저장소에서도 개인적으로 쓸 작업이면 사용자 경로를 선택합니다. 같은 이름의 Skill을 두 범위에 중복 배치하면 어느 지침을 시험하고 있는지 헷갈릴 수 있으니, 검증 중에는 한 경로만 남기는 편이 좋습니다.
SKILL.md 작성과 설정 검증
>SKILL.md에는 무엇을 적어야 하나요?
앞부분의 YAML 메타데이터에는 Skill의 name과 description을 두고, 본문에는 수행할 작업, 적용 조건, 처리 순서를 씁니다. 특히 description은 어떤 요청에서 Skill을 써야 하는지 모델이 판단하는 데 중요합니다. 형식은 Agent Skills 규격에 맞추고, 공식 작성 예시는 Skill 생성 예제에서 참고할 수 있습니다.
---
name: review-test
description: 변경된 코드의 테스트를 점검하고 누락된 검증 항목을 정리합니다. 테스트 검토 요청에 사용합니다.
---
# 테스트 검토
1. 변경된 파일과 관련 테스트를 확인합니다.
2. 실행할 테스트 명령과 예상 결과를 제시합니다.
3. 실행하지 않은 검증은 완료한 것처럼 표현하지 않습니다.
이 예시는 형식을 설명하기 위한 것입니다. 실제 프로젝트의 테스트 명령이나 실행 결과를 보장하지 않습니다. 지침은 “테스트를 잘 확인한다”처럼 넓게 쓰기보다 대상, 순서, 완료 조건, 하지 말아야 할 행동을 분리해 적으세요. 그러면 자동 매칭의 단서와 호출 후 평가 기준을 함께 마련할 수 있습니다.
디렉터리 설정 뒤 확인할 항목
저장 후에는 파일명 대소문자, 경로 깊이, YAML 구분 기호, 메타데이터 들여쓰기를 살펴봅니다. 설정이나 권한이 호출을 제한하는 환경이라면 공식 설정 문서에서 적용 중인 규칙도 확인합니다.
다음 순서로 검증하면 수정 원인을 좁히기 쉽습니다.
- 현재 저장소가 의도한 프로젝트인지 확인합니다.
- 프로젝트용인지 사용자용인지 정하고 다른 위치의 같은 이름 Skill을 잠시 치웁니다.
- 전용 디렉터리 아래 파일 이름이 정확히
SKILL.md인지 확인합니다. name과description이 YAML 형식으로 읽히는지, 폴더 이름과 모순되지 않는지 점검합니다.- 세션을 다시 열어 Skill을 인식하는지 살펴봅니다.
- 명시 호출과 일반 요청을 각각 시험하고, 출력이 본문 지침을 따르는지 비교합니다.
작업 범위에 따라 선택은 다음과 같이 나뉩니다.
- 팀 저장소에서 함께 수정하고 검토해야 한다면 프로젝트 경로를 선택합니다.
- 여러 프로젝트에서 개인적으로 재사용할 목적이라면 사용자 경로를 선택합니다.
- 공유 범위가 불분명하다면 우선 프로젝트 경로에 만들고, 팀이 재사용할 필요가 없다고 확인되면 사용자 경로로 옮깁니다.
실제 호출과 결과 확인
>Claude Code는 Skill을 어떻게 찾아 호출하나요?
사용자는 /skill-name 형태로 명시 호출할 수 있습니다. 자동 호출은 요청과 description이 맞을 때 기대할 수 있지만, 표현이 모호하거나 설명이 넓으면 다른 작업으로 판단될 수 있습니다. 두 방식을 혼동하지 않도록 우선 명시 호출로 파일과 지침을 확인한 뒤, 자연어 요청으로 자동 매칭을 별도 시험하세요. 지원되는 동작과 제한은 공식 Skills 문서에서 확인할 수 있습니다.
관찰 가능한 시험을 만들려면 본문에 “검토 결과의 첫 줄에 SKILL_CHECK를 표시하고, 실행하지 않은 테스트는 실행하지 않았다고 적는다”처럼 확인 가능한 조건을 넣습니다. 먼저 /review-test로 호출해 조건이 지켜지는지 확인하고, 이어 “변경 사항을 검토하고 테스트 누락을 알려줘”처럼 설명에 부합하는 요청을 합니다. 결과에 표시 문구가 없거나 실행하지 않은 테스트를 완료했다고 쓰면, 호출 성공으로 간주하지 말고 지침과 실제 실행 여부를 다시 확인합니다.
인식 실패와 호출 편차의 점검
Skill이 목록에 나타나지 않으면 경로와 파일 이름부터 확인합니다. 인식은 되지만 자동으로 선택되지 않으면 description에 요청의 종류와 사용 조건이 구체적으로 담겼는지 살핍니다. 호출은 되지만 결과가 지침에서 벗어나면 본문을 짧은 순서형 작업으로 나누고, 완료 조건과 금지 행동을 명시합니다.
| 구성 선택 | 적용 범위 | 적합한 경우 | 점검 우선순위 |
|---|---|---|---|
| 프로젝트 경로 | 해당 프로젝트 | 팀 공유와 저장소 단위 관리 | 저장소 루트와 파일 위치 |
| 사용자 경로 | 개인 작업 공간 | 여러 프로젝트에서 개인 재사용 | 홈 경로와 사용자 세션 |
| 명시 호출 | 사용자가 선택한 요청 | 첫 동작 검증과 정확한 지정 | Skill 이름과 본문 준수 |
| 자동 매칭 | 요청과 설명의 적합성에 좌우 | 반복 작업을 자연어로 요청 | 설명의 구체성과 요청 표현 |
현재 터미널에 표시된 결과만으로 모든 팀원의 환경에서도 같게 작동한다고 단정할 수는 없습니다. 프로젝트 경로를 선택했다면 다른 구성원도 같은 저장소와 설정으로 시험하고, 사용자 경로라면 개인 범위에서만 사용할 수 있음을 기록하세요. 파일을 고친 뒤에는 같은 시험 요청을 다시 실행해 인식 여부와 출력 조건을 함께 확인해야 합니다.
개발 환경에 따른 마지막 선택
>Skill의 동작을 먼저 검증하는 단계라면 현재 작업 환경에서 반복 작업 하나를 골라 작성과 호출까지 마치는 것이 우선입니다. 로컬 환경에서 작업하면 기존 저장소와 도구를 그대로 쓸 수 있지만, 개인 기기의 상태에 의존하고 다른 장소에서 접근하기 어렵거나 개발 환경을 별도로 맞춰야 할 수 있습니다. 원격 Mac 환경은 임시 접근이 필요할 때 장비 구매보다 편리한 선택지가 될 수 있지만, 네트워크 상태와 원격 접속 방식이 변수이며 장시간 고정 부하나 물리 장치 연결이 필수인 작업에는 맞지 않을 수 있습니다.
실제 원격 개발 환경이 필요해지면 Zilmac의 클라우드 맥 대여 안내에서 제공 범위와 전달 방식을 확인하세요. 원격 접속이나 지원 범위를 따져야 한다면 Zilmac의 맥 지원 안내도 함께 살펴보고 현재 작업 흐름에 맞는지 판단할 수 있습니다. Skill을 시험하는 목적만으로 환경을 바꿀 필요는 없습니다. 다만 여러 위치에서 동일한 프로젝트 환경을 써야 한다면, 구매·로컬 운영과 대여 환경의 관리 부담을 비교해 선택하는 편이 합리적입니다.
개발 환경을 원격 맥으로 확장해 보세요
Zilmac의 애플 M4 전용 원격 맥에서 전체 맥 운영체제를 사용해 개발 작업을 이어갈 수 있습니다.
명령줄 접속과 원격 데스크톱을 지원해 익숙한 방식으로 빌드하고 결과를 확인할 수 있습니다. — 요금제 옵션 보기