1. 문제를 네 단계로 나누기

“Skill이 잘 안 된다”에는 서로 다른 문제가 섞여 있습니다. 등록에 실패한 것인지, 등록했지만 선택되지 않는지, 선택했지만 실행하지 못하는지, 실행했지만 결과가 틀린지 나누어 봅니다.

1.1 등록과 선택 문제

전체 실습 ZIP을 올렸다면 개별 Skill ZIP으로 바꿉니다. SKILL.md.txt가 아닌지도 봅니다. 등록된 Skill이 꺼져 있으면 켜고 새 대화에서 다시 확인하세요. 조직 정책 때문에 업로드 항목이 없을 수 있다는 점은 Claude 공식 도움말을 참고합니다.

설치는 되었지만 선택되지 않는다면 같은 요청에 Skill 이름을 넣어 실행해봅니다. 이름을 지정하면 되는데 자연어 요청에서만 빠진다면 설명문이 요청 상황을 충분히 담고 있는지 봅니다. 기능이 비슷한 Skill을 잠시 끄고 비교하면 선택 충돌을 찾기 쉽습니다.

1.2 실행 환경 문제

계산 Skill이 Python 파일을 읽기만 하고 결과를 추정했다면 실행한 것이 아닙니다. 파일 실행 도구가 켜져 있는지, 스크립트 경로가 맞는지, 입력 파일을 읽을 수 있는지 확인해야 합니다. 도구가 없는 환경에서는 로컬 명령으로 진행하고 그 사실을 기록합니다.

경로 오류는 Skill 폴더 기준 상대 경로와 samples 폴더 기준 상대 경로를 혼동할 때 자주 생깁니다. SKILL.md에 적힌 명령은 Skill 폴더 기준이고, 이 책 본문의 명령은 samples 폴더 기준입니다. 현재 위치를 확인한 뒤 실제 입력 경로로 바꿉니다.

1.3 실행 성공과 결과 오류

종료 코드가 0이어도 규칙을 잘못 구현했으면 내용이 틀립니다. 보고서가 12명을 실제 참여자로 썼다면 설치 과정을 되풀이할 이유가 없습니다. 참여 정의와 출석 집계부터 봐야 합니다.

여러 지침을 한꺼번에 바꾸지 말고 실패한 한 조건을 재현할 작은 입력을 만드세요. 수료율 분모 문제라면 두 명 중 한 명만 출석한 작은 표가 전체 출석부보다 원인을 찾기 쉽습니다.

1.4 도움을 요청할 때 남길 기록

제품과 버전, Skill 이름과 버전, 실행한 요청, 입력 파일명, 예상 결과, 실제 오류를 남깁니다. 실제 회사 자료 전체를 붙일 필요는 없습니다. 민감한 내용을 뺀 최소 입력에서도 같은 문제가 나는지 확인한 뒤 공유하세요.

완료 기준은 “다시 설치했더니 됐다”보다 구체적입니다. 등록, 선택, 실행, 내용 가운데 어느 단계의 문제였는지와 무엇 하나를 고쳤는지 설명할 수 있어야 합니다.