Claude Skill이 트리거되지 않는 이유와 해결 방법

짧은 답변

Skill을 이름으로 호출해서 작동한다면 설치는 된 것입니다. 자동으로 실행되는지는 에이전트가 먼저 읽고 줄일 수도 있는 description에 달려 있습니다. 실패 원인이 다르므로 두 가지를 따로 테스트하세요.

에이전트별 Skill 선택 방식

각 에이전트는 먼저 Skill 이름과 description 목록을 읽고, Skill을 고른 뒤에야 전체 지침을 로드합니다. 이 목록은 각 SKILL.md(많은 사람이 skills.md로 검색하는 파일)의 front matter에서 가져오며, 크기 제한이 있습니다.

에이전트	먼저 읽는 것	공간이 부족할 때
Claude Code	이름과 description, 설정된 경우 `when_to_use`. 각각 최대 1,536자	목록에는 컨텍스트 창의 약 1%가 할당되며, 가장 적게 쓰인 description부터 빠집니다
Codex	이름, description, 파일 경로	목록에는 컨텍스트 창의 약 2%가 할당되며, description부터 줄어듭니다
Cursor	이름과 description	문서화되어 있지 않음

Skill을 많이 설치하면 길거나 모호한 description은 에이전트가 검토하기도 전에 잘리거나 빠질 수 있습니다. 그래서 첫 문장이 가장 중요합니다.

동료가 작업을 부탁하듯이 description을 쓰고, 주된 용도를 첫 문장에 넣으세요.

에이전트는 요청을 이 단어들과 대조하므로, “랜딩 페이지”, “런칭 페이지”, “피치 덱”처럼 사람들이 실제로 입력하는 단어를 쓰세요. 결과물을 먼저 쓰고, 그다음 언제 쓰는지 적으세요.

선택됨

무엇을 만들고 언제 쓰는지

묻힘

일반적

이 순서대로 테스트하세요. 첫 단계에서 설치 문제를 배제하므로, 그 뒤에 실패하는 것은 description 문제입니다.

대개 두 description이 겹치거나 같은 Skill이 두 번 설치된 경우입니다.

원하는 Skill을 이름으로 호출하세요. 이름 호출이 항상 우선합니다.
겹치는 description을 입력, 대상, 결과물 기준으로 좁혀 각 Skill의 역할을 분명히 하세요.
같은 이름이 두 곳에 있을 때: Claude Code는 Enterprise, 개인, 프로젝트 순으로 우선합니다. Codex는 둘 다 표시할 수 있습니다. 사본을 하나만 남기세요.

먼저 이름으로 호출해 보세요. 실패하면 에이전트가 찾는 위치에 Skill이 설치되지 않은 것이고, 일반 요청만 실패한다면 실제로 입력하는 단어로 description을 다시 쓰세요.

모든 Skill의 이름과 description을 읽은 뒤 요청과 가장 잘 맞는 것을 로드합니다. /skill-name을 입력하면 이 매칭을 건너뛰고 지정한 Skill을 실행합니다.

Skill이 무엇을 만들고 언제 쓰는지를 쓰고, 주된 용도는 첫 문장에 넣으세요. description이 잘릴 수 있으므로 “랜딩 페이지”, “피치 덱”처럼 사람들이 실제로 입력하는 단어를 사용하세요.

SKILL.md이며, Skill 폴더마다 하나씩 있습니다. front matter에 에이전트가 Skill을 고를 때 읽는 이름과 description이 들어 있습니다.

이 가이드가 도움이 되었나요?