짧은 답변
- 1이름으로 호출하세요:
/skill-name또는$skill-name. 실행된다면 설치는 정상입니다. - 2찾을 수 없나요? 폴더를 확인하세요.
SKILL.md는<skills folder>/<name>/바로 안에 있어야 합니다. - 3그래도 안 되나요? 아래에서 지금 겪고 있는 증상을 찾아보세요.
30초 만에 문제 찾기
왼쪽에서 지금 보이는 증상을 찾은 다음, 오른쪽의 해결 방법으로 이동하세요.
이름으로 호출해도 실패함
에이전트가 찾는 위치에 없습니다. Skill이 보이지 않음을 참고하세요.
이름으로는 실행되지만 일반 요청으로는 실행되지 않음
description이나 설정을 확인하세요. Skill이 트리거되지 않음을 참고하세요.
다른 Skill이 실행됨
두 description이 겹칩니다. 다른 Skill이 실행됨을 참고하세요.
시작했다가 멈춤
필요한 무언가가 빠져 있습니다. 중간에 실패를 참고하세요.
이전 버전이 실행됨
사본이 하나 더 있거나 세션이 오래되었습니다. 이전 버전을 참고하세요.
Claude Code, Codex, Cursor에서 Skill이 보이지 않을 때
Skill이 /skills나 Customize → Skills에 없다면 에이전트가 불러오지 못한 것입니다. 대부분 폴더 위치가 잘못되었거나 한 단계 더 깊이 들어가 있습니다.
| 예상 원인 | 해결 방법 |
|---|---|
Skillry CLI로 Claude Code용으로 설치하면서 --agent claude-code를 빠뜨림 | 플래그를 붙여 다시 설치하세요. 플래그가 없으면 CLI는 ~/.agents/skills/를 사용합니다 |
| ZIP 때문에 폴더가 한 단계 더 생김 | 안쪽 폴더를 한 단계 위로 옮기세요. Claude Code는 정확히 skills/<name>/SKILL.md 구조가 필요합니다 |
--- 줄 사이 frontmatter의 실수 | 수정하세요. Codex와 Cursor는 name과 description이 필요하고, Cursor에서는 name이 폴더 이름과 같아야 합니다 |
| 에이전트가 아직 인식하지 못함 | Claude Code: /reload-skills. Codex: 저장소 안에서 다시 시작. Cursor: 새 채팅을 열거나 창을 다시 불러오기 |
ChatGPT 데스크톱 앱의 Codex: $로 아무것도 찾을 수 없음 | 보고된 버그입니다(openai/codex#28505). /skills를 확인하고, 다시 시작하거나, ~/.codex/skills/에 사본을 두어 보세요(아직 직접 테스트하지는 않았습니다) |
에이전트별로 읽는 모든 폴더는 Skill 위치에서 확인하세요.
Skill은 보이지만 자동으로 트리거되지 않을 때
에이전트는 Skill의 description을 읽고 사용할지 결정합니다. 이름으로 호출할 때만 Skill이 실행된다면, description이 요청 방식과 맞지 않거나 어떤 설정이 막고 있는 것입니다.
- Skill 페이지의 예시 프롬프트를 사용해 보세요. description과 맞도록 작성되어 있습니다.
paths를 확인하세요. 자동 사용을 일치하는 파일로 제한합니다.- Skill을 많이 설치했나요? 에이전트는 모두를 담기 위해 description을 줄이거나 생략하므로, 주된 용도를 맨 앞에 두세요. 트리거를 참고하세요.
다른 Skill이 대신 실행될 때
설치된 두 Skill이 같은 작업을 설명하면 서로 경쟁하고, 에이전트는 요청에 더 가깝게 읽히는 쪽을 고릅니다. 보통 비슷한 작업용 Skill이 두 개 있거나, 같은 Skill이 두 번 설치된 경우입니다.
| 원인 | 해결 방법 |
|---|---|
| 비슷한 Skill이 계속 선택됨 | 원하는 Skill을 이름으로 호출하세요. Claude Code와 Cursor에서는 /skill-name, Codex에서는 $skill-name입니다. 이름으로 호출하면 항상 그 Skill이 실행됩니다. |
| 직접 만든 Skill끼리 겹침 | 입력, 대상, 결과물 기준으로 각 description을 좁혀 하나의 작업만 맡게 하세요. 트리거를 참고하세요. |
| 같은 이름이 두 번 설치됨 | Claude Code는 Enterprise, 개인, 프로젝트 순으로 사용합니다. Codex는 둘 다 표시할 수 있습니다. 사본을 하나만 남기세요. |
| 요청하지 않았는데 특정 Skill이 계속 시작됨 | 언제 사용하는지 description을 더 구체적으로 써서 관련 없는 요청과 일치하지 않게 하세요. 그런 다음 원하는 Skill을 이름으로 호출하세요. 트리거를 참고하세요. |
시작했다가 중간에 실패할 때
거의 항상 의존성이 빠진 경우입니다. Node.js 버전이 맞지 않거나 Python, FFmpeg, FAL key가 없는 경우죠. Skill 페이지에 필요한 항목이 나와 있으니 먼저 확인하세요.
계속 이전 버전이 실행될 때
Skill을 업데이트했는데 에이전트가 여전히 예전처럼 동작한다면 다음 중 하나가 원인입니다.
SKILL.md만 교체했습니다.--force로 다시 설치하거나 폴더 전체를 교체하세요.- 같은 이름의 다른 사본이 다른 곳에 설치되어 있습니다. 삭제하세요.
- Claude Code에서 이미 실행된 Skill은 해당 대화가 끝날 때까지 그대로 유지됩니다. 수정 사항을 반영하려면 새 대화를 시작하세요.
백업과 롤백은 관리와 업데이트를 참고하세요.
내 컴퓨터에서는 되지만 클라우드에서는 안 될 때
클라우드 세션은 다른 컴퓨터에서 실행되므로, 내 컴퓨터에만 있는 Skill은 따로 설정하지 않으면 함께 가지 않습니다.
| 에이전트 | 해결 방법 |
|---|---|
| Claude Code | 클라우드 세션: .claude/skills/에 커밋하거나 claude.ai에서 켜세요. Cowork: claude.ai에서 켜세요. |
| Codex | 독립형 Skill은 웹이나 모바일의 ChatGPT에 전달되지 않습니다. 플러그인에 담아 배포하세요. |
| Cursor | ~/.cursor/skills/에 두고 Settings → Agents → Context and Tools → Sync Skills for Cloud Agents를 켜세요. |
Skillry CLI 오류 메시지
Skillry CLI가 출력한 메시지를 찾은 다음, 오른쪽 열의 안내대로 하세요.
| 표시되는 메시지 | 해야 할 일 |
|---|---|
| “Not logged in.” 또는 “Session expired.” | npx --yes skillry-cli@latest login을 실행하세요 |
| “…already exists. Re-run with --force to replace it safely.” | --force를 추가하세요. 기존 사본은 백업됩니다 |
| “This Skill requires a paid plan.” | Skill 가격이나 내 요금제를 확인하세요 |
| “--agent and --target cannot be used together.” | 둘 중 하나만 사용하세요 |
| “Secure session storage is currently supported on macOS and Windows only.” | Linux에서는 설치 프롬프트나 ZIP 다운로드를 사용하세요 |
자주 묻는 질문
Claude Code Skill이 로드되지 않는 이유는 무엇인가요?
대개 ~/.claude/skills/가 아니라 ~/.agents/skills/에 있거나, 폴더가 한 단계 더 있습니다. 경로를 고치고, 새 폴더라면 /reload-skills를 실행하세요.
Skill이 API key를 요구하는 이유는 무엇인가요?
유료 서비스를 사용하기 때문이며, Skill 페이지의 외부 비용 항목에 나와 있습니다. 해당 서비스가 안내하는 방식으로 key를 설정하고, 절대 채팅에 붙여 넣지 마세요.
설치가 잘 되었는지 어떻게 알 수 있나요?
/skills(Cursor는 Customize → Skills)에 표시되고, 이름으로 호출했을 때 실행되면 됩니다.
출처
이 가이드가 도움이 되었나요?