카탈로그에 등록되지 않는 Zed 스킬을 찾는 방법 (2026년 가이드)

스킬은 이름과 설명이 모델이 보는 카탈로그에 들어가야만 에이전트에 영향을 미칩니다. Zed의 문서에는 파일을 제외시키는 네 가지 조건과, 주의 사항과 함께 진입을 허용하는 한 가지 조건이 명시되어 있습니다.

카탈로그에는 바이트 예산이 있습니다. 이것은 아무도 예상하지 못하는 부분입니다:

"50KB 카탈로그 예산. 모든 스킬 이름과 설명의 총 크기는 50KB로 제한됩니다. 제한을 초과하는 스킬은 UI에 경고와 함께 카탈로그에서 제외됩니다. 설명을 간결하게 유지하세요."

측정 대상이 무엇인지 주의 깊게 보세요. 본문이 아니라 '이름과 설명'입니다. 따라서 다른 스킬의 설명이 너무 장황해서 특정 스킬이 제외될 수 있습니다. 스킬을 새로 추가하면 몇 달 동안 의존해 온 기존 스킬이 쫓겨날 수 있으며, 유일한 신호는 사용자가 보지 못했을 수도 있는 UI의 경고뿐입니다.

중첩은 지원되지 않습니다. Zed는 명확하게 밝히고 있습니다:

"플랫 레이아웃만 지원됩니다. 스킬은 반드시 skills 루트의 직계 자식이어야 합니다. ~/.agents/skills/group/my-skill/과 같은 중첩된 폴더는 탐색되지 않습니다."

도메인별로 그룹화하려는 좋은 본능으로 스킬을 폴더로 정리해 두었다면, 해당 스킬들은 단순히 우선순위가 밀리는 것이 아니라 아예 발견되지 않습니다.

신뢰할 수 없는 작업 트리는 아무것도 제공하지 않습니다. 이것은 새 리포지토리를 시작하는 첫날에 사람들을 당황하게 만듭니다:

"프로젝트 로컬 스킬은 신뢰할 수 있는 작업 트리에서만 로드됩니다. 새로 복제되었거나 신뢰할 수 없는 프로젝트의 스킬은 신뢰를 부여할 때까지 카탈로그 및 슬래시 명령어에서 제외됩니다."

스킬이 포함된 리포지토리를 복제하고 열어도, 아직은 그 중 어떤 것도 존재하지 않습니다. 카탈로그에도 없고, 슬래시 명령어에도 없습니다.

프론트매터 필드로 스킬을 옵트아웃할 수 있습니다. Zed는 이를 기능으로 문서화하고 있으며, 실제로 유용한 기능입니다: "스킬의 프론트매터에 disable-model-invocation: true를 추가하면 에이전트가 이를 자율적으로 선택하는 것을 방지할 수 있습니다." 전적으로 합리적이지만, 6주 전에 설정해 두었다는 사실을 잊어버리기 쉽습니다.

그리고 알아둘 만한 아슬아슬한 상황 하나. 설명에 대해: "1024바이트 미만으로 유지하세요. 설명이 더 긴 스킬도 로드되지만 경고가 표시됩니다." 따라서 설명이 너무 길다고 해서 스킬이 제외되지는 않지만, 필요 이상으로 50KB 예산을 더 많이 소모하게 됩니다. 이것이 바로 설명 문제가 다른 사람의 스킬 제외 문제로 이어지는 방식입니다.

제외는 아니지만 다른 혼란을 설명하는 여섯 번째 동작이 있습니다: "글로벌 스킬과 프로젝트 로컬 스킬의 이름이 같으면 프로젝트 로컬 스킬이 우선합니다." 스킬이 없는 것이 아니라 가려진(shadowed) 것일 수 있습니다.

이 모든 것의 패턴은 에이전트가 지침 파일을 무시하는 이유에서 다룬 내용과 일치합니다. 도구가 아예 로드하지 않은 파일은 모델이 사용하지 않기로 선택한 파일과 똑같이 보이지만, 두 가지는 완전히 다른 방식으로 해결해야 합니다.

더 매력적으로 보이도록 설명 다시 쓰기. 보통 가장 먼저 취하는 조치이지만, 이는 스킬이 카탈로그에 들어가 있고 관련성 판단에서 밀리고 있을 때만 도움이 됩니다. 예산, 중첩, 신뢰 문제로 제외된 상태라면 설명을 개선해도 아무것도 바뀌지 않으며, 오히려 더 길어진 설명이 예산 문제를 악화시킵니다.

Zed 재시작. 콘텐츠 변경 시에는 이해는 가지만 불필요한 행동입니다. Zed는 라이브 리로드를 지원한다고 문서에 명시하고 있습니다: "SKILL.md를 추가, 제거 또는 편집하면 세션을 재시작할 필요 없이 즉시 반영됩니다." 재시작하면 다시 들어올 때 프롬프트를 수락하여 신뢰 문제를 해결할 수 있기 때문에 가끔 작동하는 것처럼 보일 뿐입니다.

스킬을 명시적으로 호출하기. 좋은 진단 방법이며, 이것이 무엇을 증명하는지 주목하세요. 명시적 호출은 작동하지만 자율적 사용이 전혀 일어나지 않는다면, 탐색 문제가 아니라 disable-model-invocation이나 설명 문제를 겪고 있는 것입니다. 슬래시 명령어마저 누락되었다면 신뢰 영역의 문제입니다. Zed는 신뢰할 수 없는 프로젝트 스킬을 "카탈로그 및 슬래시 명령어에서 제외"하기 때문입니다.

스킬을 글로벌 루트로 복사하기. 이 방법은 실제로 해결되는 경우가 많아서 만족스러운 막다른 골목이 되곤 합니다. 글로벌 루트는 신뢰할 수 있고 플랫하기 때문에, 어떤 원인이 작용했는지 배우지 못한 채 두 가지 원인을 동시에 우연히 제거한 것입니다. 다음 프로젝트에서도 똑같은 문제가 발생할 것입니다.

대신 모든 것을 지침(instruction) 파일로 이동하기. 유혹적이지만, 문제를 해결하기보다는 비용 구조를 바꿀 뿐입니다. 항상 로드되는 지침은 모든 메시지에서 컨텍스트 비용을 발생시키며, 이는 스킬이 온디맨드 방식으로 존재하는 이유 자체를 부정합니다. 두 가지의 차이점과 왜 하나가 다른 하나를 대체할 수 없는지는 에이전트 스킬이 메모리가 아닌 이유에서 다루고 있습니다.

다음 단계를 순서대로 수행하세요. 각 단계는 비용이 적게 들고 확실하며, 이전 조건이 작용하고 있다면 이후의 확인은 무의미하므로 순서가 중요합니다.

1단계: 다른 것을 보기 전에 신뢰와 레이아웃부터 해결하기

이 두 가지는 구조적인 문제이며, 예/아니오로 명확히 갈립니다.

작업 트리가 신뢰할 수 있는지 확인하세요. 최근에 이 리포지토리를 복제하고 신뢰를 부여한 적이 없다면, 모든 프로젝트 로컬 스킬이 제외됩니다. 해당 스킬에 대한 슬래시 명령어가 없는 것이 이를 확인해 줍니다.

그다음 플랫하게 만드세요. 사용자 수준 루트와 작업 트리 자체의 스킬 루트를 살펴보고 모든 스킬이 직계 자식인지 확인하세요. 실패하는 경우에 대한 Zed의 예시는 정확합니다: ~/.agents/skills/group/my-skill/과 같은 경로는 탐색되지 않습니다. 그룹화된 폴더를 발견했다면 그것이 원인이며, 해결책은 이름을 바꾸는 것이 아니라 한 단계 위로 이동하는 것입니다.

이 작업을 하는 동안 알아두면 좋은 점: .agents/skills/는 Zed 전용 규칙이 아닙니다. Windsurf, Zencoder, OpenHands 모두 동일한 경로에서 스킬을 읽으며, Factory는 .agents/를 호환성 디렉토리 중 하나로 읽습니다. 다른 도구에서는 허용되었던 그룹화된 레이아웃이 공유 리포지토리와 함께 제공되어 Zed에서 스킬을 자동으로 누락시키는 원인이 될 수 있습니다.

2단계: 스킬별이 아닌 전체 카탈로그 예산 감사하기

이것은 예산이 공유되고 실패 원인이 엉뚱한 파일로 오인되기 때문에 아무도 수행하지 않는 확인 작업입니다.

두 루트에 있는 모든 스킬의 이름과 설명 길이를 합산해 보세요. 이름과 설명에 대한 50KB 제한과 비교하여 총합을 확인해야 합니다. 그런 다음 스킬이 맞지 않을 때 Zed가 UI에 표시한다고 명시한 경고가 있는지 확인하세요. 경고가 있다면 그것이 원인이며, 해결책은 스킬을 삭제하는 것이 아니라 설명을 줄이는 것입니다.

이 작업을 하는 동안 각 설명을 1024바이트 가이드라인 미만으로 유지하세요. Zed는 더 긴 설명도 경고와 함께 로드되도록 허용하지만, 짧은 설명보다 예산을 더 많이 소모하게 되며, 이로 인해 밀려나는 스킬은 정작 여러분이 편집하던 스킬이 아닐 것입니다.

3단계: "카탈로그에 없음"과 "사용하지 않기로 선택함" 구분하기

이제서야 프론트매터와 관련성 질문에 답할 수 있습니다.

disable-model-invocation: true가 설정되어 있는지 확인하세요. 이 옵션이 설정되어 있으면 스킬이 자율 선택에서 의도적으로 제외되며, 명시적으로 요청할 때만 실행됩니다.

글로벌 스킬과의 이름 충돌을 확인하세요. 프로젝트 로컬 스킬이 우선하므로 예상했던 글로벌 스킬이 가려질 수 있습니다.

스킬이 존재하는데도 에이전트가 여전히 사용하지 않는다면 설명 영역의 문제입니다. 여기서 튜닝을 반복할 때 발생하는 비용에 주의하세요. Zed는 "스킬의 name 또는 description을 변경하면 현재 세션의 모델 프롬프트 캐시가 무효화된다"고 문서화하고 있으므로, 세션 중간에 빠른 튜닝을 수행하면 실제 비용이 발생합니다.

구조 조정을 시작하기 전에 염두에 두어야 할 제약 조건이 하나 더 있습니다: "SKILL.md 본문은 500행 미만으로 유지하세요. 상세한 자료는 참조 파일로 이동하고 본문에서 링크를 연결하세요." 긴 본문은 카탈로그와는 별개의 문제이지만, 실행된 스킬이 여전히 유용하지 못하게 만드는 원인이 됩니다.

위의 네 가지 원인은 기계적인 것이며, 이를 해결하고 나면 더 어려운 질문이 남습니다. 이 지식 중 어떤 것이 스킬에 속해야 했는가 하는 점입니다. 재사용 가능한 절차는 스킬에 속합니다. 이 규칙이 존재하는 이유, 거부한 접근 방식, 실제 제약 조건이 무엇인지와 같은 상시 결정 사항은 절차가 아니며, 이를 단일 편집기의 카탈로그에 고정하면 바이트 예산과 신뢰 프롬프트의 제약을 받게 됩니다.

MemoryLake는 이 두 번째 범주를 모든 도구가 읽는 레이어로 보유하므로, 결정 사항이 카탈로그 공간을 두고 스킬과 경쟁하지 않으며 새로 복제된 리포지토리에서도 사라지지 않습니다.

1단계: API 키 생성하기

로그인하고 워크스페이스 설정을 연 다음 API 키를 생성합니다. 이 키는 편집기와 에이전트가 동일한 레이어를 읽는 데 사용하는 자격 증명이므로, 한 번 생성하여 작업하는 각 머신에서 액세스할 수 있도록 유지하세요.

2단계: 첫 번째 메모리 업로드하기

현재 스킬 설명을 채우고 있는 자료들을 이동하세요. 규칙 뒤에 숨겨진 이유, 명백한 접근 방식이 잘못된 제약 조건, 다시 논쟁하고 싶지 않은 결정 사항들입니다. 설명은 더 짧아지고, 카탈로그는 더 작아지며, 동일한 지식을 사용할 수 있게 됩니다.

3단계: AI 및 에이전트 연결하기

Zed와 작업하는 다른 모든 도구를 연결하세요. 상시 결정 사항이 모든 곳에 도달하고, 스킬은 본연의 역할인 에이전트가 필요할 때 가져다 쓸 수 있는 절차로 돌아갑니다.

첫 번째 차이점은 예산이 더 이상 제로섬 게임이 아니라는 점입니다. 추론이 다른 곳에 존재하여 설명이 짧아지면, 스킬을 추가해도 다른 스킬이 쫓겨나지 않으며, UI의 경고를 무시하는 습관을 버릴 수 있습니다.

두 번째는 새로 복제한 리포지토리를 즉시 사용할 수 있다는 점입니다. 신뢰 게이팅은 합리적인 보안 기본값이며, 새로운 기여자가 첫 한 시간 동안 필요한 지식이 신뢰 게이팅 뒤에 숨겨져 있어서는 안 됩니다. 이로 인해 발생하는 공백은 Zed가 프로젝트 컨텍스트를 잊어버릴 때에서 설명한 것과 동일합니다.

세 번째는 조직화하려는 본능이 더 이상 불이익을 받지 않는다는 점입니다. 5개 도메인에 걸쳐 30개의 스킬이 있기 때문에 폴더를 원했던 것입니다. 스킬은 플랫하게 유지하고, 도메인 추론은 레이아웃 제약이 없는 레이어에 두면 탐색 기능을 잃지 않고 구조를 얻을 수 있습니다.

네 번째는 외부 에이전트에서 나타납니다. Zed는 자신이 제어하지 않는 에이전트가 자체 지침 파일을 읽는다는 점을 명확히 밝히고 있으며, 이는 Zed의 외부 에이전트 및 컨텍스트에서 다루었습니다. 편집기 카탈로그 외부의 레이어만이 이들 모두가 공유할 수 있는 유일한 수단입니다.

설명을 문서가 아닌 카탈로그 공간으로 취급하세요. 스킬이 무엇을 하고 언제 사용하는지에 대한 한 문장만 작성하세요. 나머지는 본문이나 참조 파일에 넣으세요.

추가할 때마다 총합을 감사하세요. 제한은 합계에 적용되므로 의미 있는 숫자는 스킬별 크기가 아닙니다.

어색하게 느껴지더라도 레이아웃을 플랫하게 유지하세요. 그룹화 폴더 없이 루트의 직계 자식으로 두세요. 필요한 경우 디렉토리 구조 대신 이름에 그룹화를 반영하세요.

복제 시 신뢰를 신중하게 부여하세요. 신뢰를 부여하기 전까지는 프로젝트 스킬이 카탈로그와 슬래시 명령어 모두에서 누락된다는 점을 기억하세요. 따라서 스킬이 보이지 않는다고 해서 다른 문제가 있다고 단정할 수 없습니다.

콘텐츠를 디버깅하기 전에 가려짐(shadowing)을 확인하세요. 이름이 같은 프로젝트 로컬 스킬이 우선하므로, 내가 읽고 있던 글로벌 스킬이 실제로 작동하는 스킬이 아닐 수 있습니다.

권한 부여 요구 사항을 그대로 두세요. Zed는 신뢰할 수 있는 프로젝트에서도 명시적인 권한 부여 없이는 에이전트가 SKILL.md 파일이나 관련 리소스를 편집할 수 없다고 명시하고 있습니다. 이는 손상된 대화가 향후 대화를 제어하는 스킬을 수정하는 것을 방지하기 위한 보안 조치입니다. 이는 훌륭한 기본값이며, 이를 우회하지 마세요.

스킬에 무엇이 속하는지 결정하세요. 절차는 맞지만, 추론은 아닙니다. 이 분류 질문은 AI 에이전트에게 얼마나 많은 메모리를 주어야 하는가에서 다룬 것과 동일하며, 이를 올바르게 처리하는 것이 카탈로그를 작게 유지하는 방법입니다.

Zed의 스킬 시스템은 문서화가 잘 되어 있으며 제약 조건도 모두 공개되어 있습니다: 이름 및 설명에 대한 50KB 예산, 루트의 직계 자식만 허용, 신뢰할 수 있는 작업 트리만 허용, 옵트아웃 필드. 이를 어렵게 만드는 것은 네 가지 독립적인 원인이 하나의 동일한 증상을 만들어내고, 그중 세 가지는 파일이 완벽하게 정상인 것처럼 보이게 만들기 때문입니다.

따라서 순서대로 해결하세요. 신뢰와 레이아웃은 구조적인 문제이므로 먼저 해결하세요. 예산은 총합이므로 두 번째로 해결하세요. 프론트매터와 관련성은 스킬이 실제로 카탈로그에 들어간 후에만 의미가 있으므로 마지막에 해결하세요. 그런 다음 이 모든 작업의 밑바탕에 깔린 질문을 던져보세요. 에이전트에게 가르치려던 것이 애초에 절차였는지, 아니면 카탈로그 공간을 두고 경쟁해서는 안 되는 결정 사항이었는지 말입니다. 도구가 실제로 무엇을 어떤 순서로 로드하는지 이해하는 것은 전반적으로 가치가 있습니다. 코딩 에이전트가 실제로 읽는 것에서 더 넓은 그림을 다룹니다.