CPN 한국어 자습서 · 러닝패스 1 / 4 — Agent Skills
6장 · 마지막 레슨
Introduction to agent skills · Troubleshooting skills
스킬이 생각대로 안 동작해도 괜찮습니다. 문제는 보통 네 갈래 중 하나로 정리되고, 고치는 방법도 대부분 간단합니다. 안 불려오고, 안 보이고, 엉뚱하게 불리고, 실행 중 멈추는 — 이 네 가지를 증상별로 짚어 갑니다. 코스 1의 마지막 레슨입니다.
이 장에서 배우는 것What you'll learn
약 15분검증기로 디버깅 전에 구조 문제부터 잡기
안 불려오거나 안 보이는 흔한 문제 진단·해결
Enterprise·Personal·Project·Plugins 우선순위 충돌 풀기
의존성·권한·경로 등 런타임 에러 잡기
이 자습서를 보는 법
영어 영상을 먼저 본 뒤, 여기서 한국어로 따라 읽고 손으로 익히는 교재입니다. 점선 친 단어는 올리거나 탭하면 뜻이 나오고, 아래쪽엔 직접 눌러 보는 진단·검증 위젯이 있습니다. 읽은 만큼 ‘완료’를 누르면 위 진도 바가 찹니다.
스킬이 안 동작하면 막막해 보이지만, 증상은 대개 다음 네 가지 중 하나입니다.
다행인 건, 고치는 방법이 대부분 정해져 있다는 것입니다. 아래에서 증상별로 하나씩 짚어 봅니다.
먼저 영상을 보세요. 영어가 어렵다면 아래 한국어를 같이 읽으면 됩니다. 자동 번역과 달리, 낯선 용어를 풀어서 옮겼습니다.
영상 대본 — 영어 영상을 보며 같이 읽으세요 (타임스탬프 기준).
uv로 설치하는 게 가장 빠릅니다.SKILL.md는 ‘이름 붙은 폴더’ 안에 있어야 하고(skills 바로 아래 ✗), 파일명은 정확히 SKILL.md — SKILL은 대문자, md는 소문자입니다.claude --debug를 실행해 로딩 에러를 보세요. 내 스킬 이름이 언급된 메시지를 찾으면 그 자리에서 해결되기도 합니다.code-review와 Personal code-review가 둘 다 있으면, Enterprise가 항상 이깁니다.문제 해결의 첫 단추는 증상을 바르게 분류하는 것입니다. 위에서 본 네 갈래 — 발동·로드·충돌·런타임 — 가 그대로 진단명입니다. 겪고 있는 증상을 고르면, 가장 흔한 원인과 점검 순서가 나옵니다.
겪고 있는 증상을 고르면, 가장 흔한 원인과 점검 순서가 나옵니다.
점검 순서
디버깅을 시작하기 전에, 검증기스킬 구조에 문제가 없는지 자동으로 검사해 주는 도구.를 먼저 돌려 보세요. 구조 문제는 디버깅으로 헤매는 대신 검증기가 먼저 잡아 줍니다. 운영체제마다 설치 방법은 다르지만, uv로 설치하는 게 가장 빠릅니다. 설치한 뒤엔 스킬 폴더로 이동하거나, 아무 위치에서나 검증 명령을 실행하면 됩니다. (정확한 설치·실행 명령은 코스 화면을 따르세요.)
검증기 실행 예시 — 구조가 올바르면 ✓, 어긋나면 ⚠로 알려 줍니다.
~/.claude/skills $ # 검증기 실행 (설치는 uv 권장) ● Checking skill structure… ✓ code-review/SKILL.md — valid ✓ release-notes/SKILL.md — valid ⚠ data-export — SKILL.md가 이름 붙은 폴더 안에 없음 — → 문제 1건 발견. 위 항목을 고치고 다시 실행하세요.
검증기를 설치한 뒤, 스킬 폴더를 가리키며 실행해 보세요. 운영체제마다 설치 명령은 코스를 따르면 됩니다.
디버깅 전에 한 번만 돌려도 파일 위치·이름 같은 구조 문제는 바로 걸립니다.
검증기는 PC(Claude Code) 전용입니다. 모바일에서는 아래 ‘구조 검증기’ 위젯으로 흐름을 익혀 두고, PC에서 직접 실행해 보세요.
스킬이 ‘쓸 수 있는 스킬’ 목록에도 안 뜬다면, 구조가 규칙과 어긋나 Claude가 스킬 자체를 못 읽는 경우입니다. 단골 원인은 딱 둘입니다.
SKILL.md는 ‘이름 붙은 폴더’ 안에 있어야 합니다. skills 바로 아래에 파일만 두면 안 됩니다.SKILL.md — SKILL은 대문자, md는 소문자입니다. skill.md나 Skill.MD는 안 읽힙니다.아래에서 파일의 위치와 이름을 바꿔 가며 검증기를 돌려 보세요. 둘 다 맞아야 Claude가 읽어 들입니다.
스킬 파일의 위치와 이름을 바꿔 가며 [검증 실행]을 눌러 보세요. 규칙에 맞아야 Claude가 읽어 들입니다.
팁. 가장 흔한 두 실수가 여기 다 있습니다 — 폴더 없이 skills 바로 아래 두기, 그리고 파일명 대소문자.
로딩이 안 되는 게 확실하다면 claude --debug를 실행해 로딩 에러를 보세요. 내 스킬 이름이 언급된 줄을 찾으면, 그 자리에서 원인이 드러나는 경우가 많습니다.
lewis ~ % claude --debug Claude Code · Debug mode enabled [skills] scanning .claude/skills/ … [skills] ✓ loaded: code-review [skills] ⚠ skipped: data-export (SKILL.md가 이름 붙은 폴더 안에 없음)
이 두 문제는 뿌리가 같습니다 — 둘 다 ‘설명(description)’으로 풉니다. Claude는 글자가 아니라 의미시맨틱 매칭. 글자가 똑같지 않아도 뜻이 겹치면 연결됩니다.로 스킬을 고르기 때문입니다.
요청이 설명의 ‘뜻’과 충분히 겹치지 않은 겁니다. 평소 쓰는 말투의 키워드를 설명에 더 넣으세요. 예: “PR 리뷰” 외에 “코드 변경 점검”, “수정 사항 확인”처럼요. “이거 빠르게 해줘”, “왜 느리지?” 같은 변형으로 테스트하고, 안 걸리는 변형의 단어를 설명에 추가합니다.
여러 스킬의 설명이 너무 비슷한 겁니다. 서로 다르게, 더 구체적으로 다듬으세요. 각 스킬이 ‘무엇을·언제’를 분명히 말하게 하면, 제때 골라지기도 하고 비슷한 이름의 다른 스킬과 충돌하기도 어려워집니다.
요약하면, 발동이 어긋날 땐 거의 항상 설명이 답입니다. 표현이 곧 발동 정확도입니다.
설명을 잘 고쳤는데도 내 스킬이 무시된다면, 이름이 같은 더 높은 순위의 스킬이 있을 수 있습니다. 같은 이름의 스킬이 여러 곳에 있으면, 순위는 Enterprise → Personal → Project → Plugins 순으로 정해지고, 위쪽이 이깁니다.
예를 들어 Enterprise에 code-review가 있고 내 Personal에도 code-review가 있으면, Enterprise가 항상 이깁니다. 내 것은 ‘가려져’ 안 불립니다. 아래에서 어디에 같은 이름이 있는지 켜고 끄며, 누가 실행되는지 확인해 보세요.
같은 이름의 스킬이 여러 곳에 있으면, 순위가 높은 쪽이 이깁니다. 어디에 ‘code-review’가 있는지 켜고 끄며 누가 실행되는지 보세요. Personal은 ‘내 스킬’이라 항상 켜져 있습니다.
해결책. 가장 확실한 건 내 스킬 이름을 더 고유하게 바꾸는 것입니다. Enterprise 스킬은 관리자 영역(managed-settings.json)이라 내가 직접 바꿀 수 없습니다.
충돌은 결국 ‘누가 이기는가’입니다. 위쪽(Enterprise)을 못 바꿀 땐, 내 쪽 이름을 고유하게 바꾸면 충돌 자체가 사라집니다.
플러그인 스킬이 안 보일 때. 설치는 했는데 스킬이 목록에 없다면, 순서대로 시도합니다.
런타임 에러. 스킬은 로드스킬 내용을 컨텍스트로 불러오는 단계. 실행(런타임) 전 단계입니다.됐는데 실행 도중 실패한다면, 단골 원인은 셋입니다.
chmod +x)./)를 — 윈도우에서도 — 씁니다.claude --debug로 로딩 에러를 확인한다.정답을 먼저 떠올려 본 뒤 골라 보세요. 맞히면 설명이 나옵니다.
Q1스킬이 ‘쓸 수 있는 스킬’ 목록에 아예 안 뜹니다. 가장 먼저 확인할 것은?
목록에 안 뜨는 건 ‘로드’ 문제입니다. SKILL.md가 이름 붙은 폴더 안에 있는지, 파일명이 정확한지부터 보고 claude --debug로 확인합니다. 설명 키워드는 ‘발동’ 문제의 해법입니다.
Q2Enterprise와 Personal에 똑같이 code-review 스킬이 있습니다. 어떻게 되나요?
순위는 Enterprise > Personal > Project > Plugins라, 같은 이름이면 Enterprise가 항상 이깁니다. 가장 확실한 해결은 내 스킬 이름을 더 고유하게 바꾸는 것입니다.
Q3스킬은 로드됐는데 실행 도중 멈춥니다(런타임 에러). 점검 대상이 아닌 것은?
런타임 에러는 의존성(패키지 설치), 권한(chmod +x), 경로(정방향 슬래시)를 봅니다. 설명이 짧은 건 ‘발동’ 단계의 문제이지 실행 단계의 원인이 아닙니다.
여기까지가 코스 1의 마지막 레슨입니다. 스킬을 만들고, 설정하고, 공유하고, 문제를 푸는 흐름을 모두 다뤘습니다. 이제 내 워크플로에 맞는 스킬을 직접 만들 차례입니다.
좋은 스킬은 진짜 반복되는 일에서 나옵니다 — 매번 똑같이 설명하게 되는 지침이 있다면, 그게 첫 스킬의 후보입니다. 거기서 시작하세요.
러닝패스는 다음 코스로 이어집니다. 공식 코스(영어)는 Anthropic Academy에서 계속 학습할 수 있습니다.
여러 스킬 폴더의 배치를 훑어, SKILL.md가 이름 붙은 폴더 안에 제대로 놓였는지 규칙대로 점검합니다.
// 스킬 구조 점검기 — 여러 스킬 폴더의 배치를 훑어, 6장에서 배운 규칙대로
// SKILL.md가 이름 붙은 폴더 안에 놓였는지, 폴더 이름이 스킬 이름과 같은지 점검한다.
// 입력: skills/ 아래에 놓인 스킬 목록.
// name = SKILL.md 맨 위 라벨의 이름 · path = SKILL.md 가 실제 놓인 위치(skills/ 기준)
const skills = [
{ name: "code-review", path: "code-review/SKILL.md" },
{ name: "release-notes", path: "release-notes/SKILL.md" },
{ name: "data-export", path: "SKILL.md" }, // skills/ 바로 아래 — 이름 붙은 폴더 없음
];
function check(skill) {
const parts = skill.path.split("/");
// SKILL.md 는 이름 붙은 폴더 안에 있어야 한다(skills/ 바로 아래는 안 됨)
if (parts.length < 2 || parts[parts.length - 1] !== "SKILL.md") {
return "SKILL.md가 이름 붙은 폴더 안에 없음";
}
// 폴더 이름은 스킬 이름과 같아야 한다
const folder = parts[parts.length - 2];
if (folder !== skill.name) {
return "폴더 이름(" + folder + ")이 스킬 이름(" + skill.name + ")과 다름";
}
return null; // valid
}
console.log("● Checking skill structure…");
let problems = 0;
skills.forEach(function (skill) {
const issue = check(skill);
if (issue) {
problems++;
console.log(" ⚠ " + skill.name + " — " + issue);
} else {
console.log(" ✓ " + skill.path + " — valid");
}
});
console.log("—");
console.log(problems
? "→ 문제 " + problems + "건 발견. 위 항목을 고치고 다시 실행하세요."
: "→ 문제 없음. 구조가 표준과 일치합니다.");