클로드 코드 플러그인 배포 — 세 가지 경로와 이름을 바꾸면 안 되는 이유

플러그인을 고쳐서 올렸는데 사용자가 갱신 명령을 돌려도 「이미 최신 판」이라고만 나온다면, 정의 파일의 판 번호를 올리지 않은 겁니다. 배포할 때 흔히 걸리는 함정은 코드보다 이름과 번호 쪽에 있습니다.

클로드 코드 플러그인 문서가 개편되면서 만든 플러그인을 공개하고 배포하는 쪽이 따로 정리됐습니다. 장터 없이 플러그인을 쓰는 법과 마켓플레이스 명령을 사용자 쪽에서 다뤘다면, 이번 문서는 만드는 사람 쪽입니다. 어떤 경로로 나눠 줄지, 올리기 전에 무엇을 확인할지, 판을 올리고 이름을 바꾸고 내릴 때 무엇이 깨지는지가 정리돼 있습니다.

짧게 정리하면

• 배포 경로는 폴더나 압축 파일로 건네기, 저장소에 마켓플레이스 파일을 두는 내 마켓플레이스, 클로드 웹과 코워크에서 고르는 앤트로픽 디렉터리 셋입니다.
• 정의 파일에 판 번호를 적었다면 올릴 때마다 번호도 올려야 하고, 깃 기반 마켓플레이스라면 번호를 빼고 커밋 해시로 판을 구분하게 둘 수도 있습니다.
• 플러그인 이름은 사용자 설치 기록의 열쇠라 바꾸면 기존 설치가 끊기므로, 보이는 이름은 표시 이름 칸으로 바꾸고 불가피하면 마켓플레이스의 이름 변경 목록을 씁니다.

클로드 코드 공식 문서의 플러그인 공개와 배포 쪽 전체를 대조했습니다. 명령과 필드 이름은 본문 표기 원칙에 따라 우리말로 풀어 적었습니다.

세 가지 배포 경로

누가 설치해야 하느냐에 따라 경로가 갈립니다. 문서의 비교표를 옮겼습니다.

플러그인 공개와 배포 문서 기준, 경로별 비교

경로	누가 설치하나	필요한 것	자동 갱신
마켓플레이스 없이	폴더나 압축 파일을 받은 사람	플러그인 폴더	없음, 받은 사본을 씀
내 마켓플레이스	저장소에 접근할 수 있는 누구나, 비공개 저장소도 가능	플러그인을 나열한 마켓플레이스 파일이 있는 저장소나 호스트	꺼져 있음
앤트로픽 디렉터리	클로드 웹이나 코워크에서 추가한 사람, 계정 동기화로 클로드 코드에도 불러옴	플러그인을 담은 깃허브 저장소, 제출할 유료 요금제	올린 판이 공개된 뒤 적용

내 마켓플레이스는 저장소에 마켓플레이스 파일 하나를 넣는 순간 공개된 셈이고, 따로 제출 양식이 없습니다. 비공개 저장소라면 클론할 수 있는 사람만 설치하므로 마켓플레이스도 비공개가 됩니다. 사용자는 마켓플레이스를 한 번 추가하고 플러그인을 설치하면 되고, 2.1.275판부터는 세션 안에서 설치 명령에 마켓플레이스를 함께 지정해 한 번에 할 수 있습니다. 자동 갱신은 사용자 쪽에서 마켓플레이스별로 켜는 설정이라, 내 마켓플레이스는 기본적으로 사용자가 갱신 명령을 돌려야 새 판을 받습니다.

디렉터리 제출에는 유료 클로드 요금제가 필요합니다. 프로와 맥스는 자기 계정으로, 팀과 엔터프라이즈는 소유자가 제출하며, 엔터프라이즈에서는 소유자가 사용자 지정 역할로 다른 구성원에게 권한을 줄 수 있습니다. 디렉터리로 설치된 플러그인은 클로드 코드에 동기화 플러그인으로 불러와집니다. 참고로 앤트로픽 공식 마켓플레이스는 디렉터리 포털로는 제출을 받지 않는다고 문서에 적혀 있습니다.

올리기 전에 확인하는 순서

문서는 첫 출시 전과 이후 매 출시 전에 다음을 확인하라고 합니다. 이름을 영구적인 것으로 정하고, 판 번호를 어떻게 매길지 정하고, 엄격 모드로 검증하고, 로컬 마켓플레이스에서 실제로 설치해 보고, 사용자에게 보일 정보를 채우고, 평가 묶음이 있다면 돌려 보는 순서입니다.

플러그인 공개와 배포 문서 기준, 출시 전 확인

단계	확인할 것
이름	소문자와 줄표로 이은 형식, 검증기가 다른 형식에 경고, 바꾸지 않을 이름으로
판 번호	적었다면 매번 올리기, 깃 기반이면 빼고 커밋 해시로 구분하게 두기
검증	엄격 모드는 모르는 필드·빠진 판 번호 같은 경고에도 실패, 판 번호를 뺐다면 엄격 모드 제외
로컬 설치	로컬 마켓플레이스를 추가해 설치하고 세션에서 불러와지는지
보이는 정보	설명·작성자·홈페이지·저장소 칸과 안내 파일, 홈페이지는 주소 형식이어야 함
평가	평가 묶음이 있다면 돌려서 변경으로 생긴 퇴행 확인

마지막 줄은 플러그인 평가 명령을 정리한 글과 이어집니다. 디렉터리에 제출할 생각이라면 로컬 검증이 깨끗해도 포털이 따로 적용하는 규칙이 있어 통과가 보장되지 않고, 일부 구성 요소는 클로드 코드에서만 불러와져 웹이나 코워크 사용자는 받지 못한다는 점도 문서가 짚습니다.

공개한 플러그인의 이름은 바꾸면 안 됩니다. 사용자의 설치는 이름과 마켓플레이스를 이은 값으로 기록되기 때문에, 이름을 바꾸면 기존 사용자에게는 다른 플러그인이 되고 이미 깔아 둔 플러그인을 잃습니다. 보이는 이름만 바꾸고 싶다면 정의 파일의 표시 이름 칸을 쓰면 됩니다. 정말 바꿔야 한다면 마켓플레이스 파일의 이름 변경 목록에 적어 두어야 기존 설치가 옮겨 가고, 마켓플레이스에서 플러그인을 찾을 수 없다는 오류로 끊기지 않습니다.

판 올리기와 태그

내 마켓플레이스로 배포하면서 정의 파일에 판 번호를 적었다면, 새 판은 번호를 올려 올리면 됩니다. 그러면 갱신 명령을 돌리거나 자동 갱신을 켠 사용자가 새 판을 받습니다. 번호를 올리지 않고 커밋만 올리면 갱신 명령이 이미 최신 판이라고 알리고 사용자는 옛 사본을 계속 씁니다. 디렉터리에 올린 플러그인의 갱신은 클로드 웹 쪽 문서의 절차를 따릅니다.

깃 태그는 다른 플러그인이 내 플러그인에 버전 범위를 걸 때만 필요합니다. 그 범위가 태그로 해석되기 때문입니다. 그렇지 않다면 태그는 없어도 됩니다. 태그 명령과 범위 해석은 플러그인 의존성 글에 정리해 뒀습니다.

명령줄 도구나 개발 도구 모음을 만드는 쪽이라면, 설치 프로그램이나 설치 후 안내 문구에서 마켓플레이스 추가와 플러그인 설치 두 명령을 실행하거나 보여 주라고 문서가 권합니다. 마켓플레이스 없이 나눠 줄 때는 받는 사람이 한 세션만 쓰려면 시작 옵션으로 폴더나 압축 파일을 지정하고, 매 세션 쓰려면 정의 파일이 든 폴더를 사용자 폴더의 스킬 폴더 아래로 옮기면 됩니다.

사내 저장소의 압축 파일로 배포한다면 다운로드 인증을 따로 챙겨야 합니다. 마켓플레이스 항목에 헤더 도우미 명령을 두면 사용자가 그 플러그인 하나를 설치·갱신할 때마다 명령을 보고 수락해야 하고, 한꺼번에 설치나 자동 갱신에서는 거절됩니다. 압축 파일 인증 헤더와 헤더 도우미가 도는 조건을 정리했으니, 배포 경로를 고를 때 함께 보세요.

자주 묻는 질문

마켓플레이스 파일은 플러그인 저장소에 둬도 되나요

됩니다. 정의 파일 옆에 마켓플레이스 파일을 두고 출처를 저장소 최상위로 지정한 항목 하나를 적으면 됩니다. 항목 이름은 정의 파일의 이름과 같게 둡니다.

내 마켓플레이스 사용자에게 자동으로 새 판이 가나요

기본으로는 아닙니다. 내 마켓플레이스의 자동 갱신은 꺼져 있어서, 사용자가 갱신 명령을 돌리거나 그 마켓플레이스의 자동 갱신을 켜야 받습니다.

디렉터리에 올리면 공식 마켓플레이스에도 들어가나요

아닙니다. 공식 마켓플레이스는 디렉터리 포털로 제출을 받지 않고, 앤트로픽 협력 담당자가 있다면 그쪽에 문의하라고 문서가 안내합니다.

검증에서 경로 경고가 납니다

구성 요소 경로가 현재 폴더 표시로 시작하지 않으면 검증이 알려 줍니다. 훅 명령과 서버 설정 안에서는 플러그인 최상위 경로 변수를 붙여 파일을 가리키라고 문서가 안내합니다.

이 문서에서 가장 오래 남을 조언은 이름을 영구적인 것으로 정하라는 한 줄입니다. 코드는 판을 올려 고칠 수 있지만, 이름은 사용자 기기의 설치 기록에 박혀 있어서 바꾸는 순간 사람들이 플러그인을 잃습니다. 처음 공개할 때 이름 정하는 데 시간을 조금 더 쓰고, 판 번호는 적을지 뺄지 한 가지 방식을 정해 끝까지 지키는 게 가장 싼 예방으로 보입니다.

확인한 곳: 클로드 코드 공식 문서의 플러그인 공개와 배포(배포 경로 비교, 출시 준비, 마켓플레이스 없이 공유, 내 마켓플레이스, 앤트로픽 디렉터리 제출, 판 올리기·태그·이름 변경과 삭제, 의존성). 2026년 9월 28일 기준입니다.