Claude Code 플러그인 마켓플레이스 — 설치할 때 내 PC에서 명령이 돌고, 세션마다 다시 돕니다

플러그인을 팀에 배포하려면 마켓플레이스를 하나 만들어 두면 됩니다. 대부분은 깃 저장소나 압축 파일을 가리키는 평범한 방식인데, 그중 하나가 유독 달랐습니다 — 설치하는 사람 컴퓨터에서 셸 명령을 실행해 그 결과로 나온 폴더를 플러그인으로 씁니다. 게다가 설치할 때 한 번으로 끝이 아니라 세션마다 백그라운드로 다시 돕니다. 위험해 보이죠. 그래서 문서가 명령 문자열에 이상한 제약을 걸어뒀는데, 그 이유가 이 글의 핵심입니다.

📌 30초 요약

• 플러그인 소스 중 하나는 내 컴퓨터에서 셸 명령을 실행합니다. 나머지는 그냥 파일을 가져옵니다.
• 설치할 때 실행하고, 세션이 시작될 때마다 백그라운드로 한 번 더 돕니다.
• 명령은 500자 이내, 인쇄 가능한 문자만, 공백 네 칸 이상 연속 금지입니다. 이유가 명확합니다.
• 사용자가 명령 전문을 보고 수락해야 돌아갑니다. 수락 안 된 명령은 아예 실행 안 됩니다.
• 명령을 바꾸면 재실행이 멈춥니다. 사용자가 새 명령을 다시 검토해야 재개됩니다.
• 회사는 이 방식을 통째로 막을 수 있습니다. 어떤 설정에서는 기본이 차단입니다.

소스가 여러 종류인데 하나만 다릅니다

마켓플레이스는 어디서 플러그인을 가져올지를 항목마다 적습니다. 상대 경로, 깃허브 저장소, 일반 깃 저장소, 저장소의 하위 폴더, 패키지, 압축 파일 — 여기까지는 전부 파일을 가져오는 방식입니다. 그런데 마지막 하나는 파일을 가리키지 않고 명령을 가리킵니다.

// 마켓플레이스 항목 — 명령이 출력한 폴더를 플러그인으로 씀
{
  "name": "my-plugin",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path"
  }
}

쓰임새는 분명합니다 — 지금 선택된 개발 환경에 맞춰 플러그인을 만들어내는 도구가 있을 때요. 명령은 사용자 홈 디렉터리에서 플랫폼 셸로 실행되고, 한 줄만 출력하고 정상 종료해야 합니다. 그 한 줄이 완성된 플러그인이 들어 있는 폴더의 절대 경로이고, 실행할 때마다 경로가 달라져도 됩니다.

📏 명령 문자열에 걸린 세 가지 제약, 그리고 그 이유

명령에는 조건이 붙습니다 — 인쇄 가능한 아스키 문자만, 최대 500자, 그리고 공백이 네 칸 이상 연속되면 안 됩니다. 앞의 둘은 그러려니 싶은데 세 번째가 이상하죠. 문서가 이유를 붙여놨습니다 — "사용자가 수락할 명령 전체를 검토할 수 있도록"입니다.

풀어보면 이렇습니다. 공백을 길게 넣으면 뒤에 붙은 진짜 내용이 화면 밖으로 밀려납니다. 앞부분만 보고 수락하면 뒤에 뭐가 붙었는지 모른 채 승인하는 거죠. 길이 제한도 같은 목적입니다. 저는 이 조항을 보고 링크로 세션을 여는 기능이 떠올랐습니다 — 거기서도 1,000자를 넘는 프롬프트에는 글자 수를 표시하고 전문을 스크롤해 보라고 하는데, 이유가 똑같았습니다. 같은 회사가 두 기능에서 같은 위험을 같은 방식으로 막고 있습니다 — "사람이 승인한다"는 절차가 실제로 다 읽고 승인하는 것이어야 의미가 있으니까요.

수락한 명령만, 그리고 바뀌면 멈춥니다

문서 표현이 정확합니다 — "사용자 컴퓨터에서 당신의 명령을 실행하므로, 모든 실행을 사용자의 명시적 수락에 묶는다." 실제 규칙이 셋입니다.

상황	어떻게 되나
처음 설치할 때	명령 문자열을 그대로 보여주고, 수락한 명령을 기록해 둠
그 외 모든 경로	이미 수락한 명령만 실행. 없으면 거부하고 검토 방법을 안내
배포자가 명령을 바꾸면	재실행이 멈추고 쓰던 버전 유지. 다시 수락해야 재개

셋째 줄이 좋았습니다. 배포자가 명령을 슬쩍 바꿔도 자동으로 따라가지 않습니다. 사용자는 쓰던 버전을 그대로 쓰고, 오류 목록에 새 명령이 표시된 채 직접 검토하고 갱신 명령을 실행할 때까지 기다립니다. 모드를 바꿔도 마찬가지고요. 즉 한 번 수락하면 영원히 위임되는 구조가 아닙니다. 사람 없이 돌리는 설치 스크립트에서는 수락 옵션을 명시적으로 붙여야 진행됩니다.

언제 다시 도는가

"세션마다 다시 돈다"가 이 방식의 특징입니다. 이유는 그 도구의 상태가 바뀌면 플러그인도 바뀌어야 하기 때문이고요. 정확히는 세 시점입니다 — 설치·갱신할 때, 세션이 시작되고 잠시 뒤 백그라운드로 한 번, 그리고 켤 때 설치된 버전이 캐시에 없으면.

결과가 달라졌으면 새 버전으로 설치하고 돌고 있는 세션에 바로 반영합니다. 여기서 배려가 하나 보입니다 — 그 자리에서 갈아끼우면 세션의 프롬프트 캐시가 무효화될 상황이면, 바로 안 바꾸고 사용자에게 다시 불러오라고 안내합니다. 캐시 비용까지 경고해 주고요. 편의보다 비용을 먼저 알리는 처리라 눈에 띄었습니다. 백그라운드 실행이 싫으면 불필요한 통신을 끄는 환경변수로 막을 수 있는데, 이때도 내가 직접 설치·갱신하는 건 그대로 실행됩니다.

복사할지 연결할지

모드	동작	제약
복사 (기본)	폴더를 캐시로 복사. 내용 해시로 버전을 매김	256메가바이트, 2만 항목 초과 시 거부
연결	복사 없이 그 자리 파일을 씀. 크기 제한 없음	윈도우 미지원. 폴더를 계속 유지해야 함

연결 모드에는 조건이 더 붙습니다. 밖을 가리키는 링크가 최상위에 있으면 설치가 실패하고, 패키지 의존성 설치도 건너뛰므로 필요한 것을 미리 넣어둔 폴더를 출력해야 합니다. 버전 판정 방식도 다른데 — 복사 모드는 내용을 해시하고, 연결 모드는 경로와 최상위 항목만 봅니다. 그래서 연결 모드에서 새 내용을 알리려면 다른 경로를 출력해야 합니다. 안에 든 파일만 바꾸면 갱신으로 인식되지 않습니다. 거부되는 경로도 있습니다 — 최상위에 플러그인 내용이 없거나, Claude Code를 시작한 폴더나 그 상위이거나, 윈도우 네트워크 경로일 때입니다.

🏢 회사는 이 방식을 통째로 막을 수 있습니다

관리자용 설정이 따로 있습니다. 명령 소스를 조직 전체에서 차단하는 항목이고, 사용자가 되돌릴 수 없습니다. 여기에 하나 더 있는데 — "관리되는 훅만 허용" 설정을 켜두면 명령 소스는 기본으로 차단됩니다. 훅 정책 하나가 플러그인 설치 방식까지 같이 막는 셈이죠. 회사 계정에서 이 방식의 플러그인이 설치가 안 된다면 두 설정 중 하나를 의심해 보세요. 그리고 알아둘 게 하나 — 명령 소스 플러그인은 다른 플러그인의 의존성으로는 절대 설치되지 않습니다. 반드시 사용자가 직접 설치해야 합니다. "딸려 들어오는" 경로를 아예 없앤 것으로 읽힙니다.

🧾 정직하게 — 이 글의 한계

• 마켓플레이스를 직접 만들어 배포해 보지 않았습니다. 공식 문서를 정리한 것이라, 수락 화면이 실제로 어떻게 보이는지는 제가 확인한 게 아닙니다.
• 버전 경계가 있습니다. 이 소스 방식은 특정 버전부터 지원되고, 그 아래에서는 설치가 실패하거나 마켓플레이스 전체가 로드되지 않습니다.
• "제약이 있으니 안전하다"는 뜻은 아닙니다. 500자 안에도 위험한 명령은 얼마든지 담깁니다. 제약은 읽을 수 있게 만드는 장치이지 내용을 검사하는 장치가 아닙니다.
• 설정 항목 이름은 우리말로 풀었습니다. 실제로 적용하실 때는 원문 표기를 확인하세요.

🗺️ AI 지출 전체 지도

플러그인이 늘면 매 세션 컨텍스트에 올라가는 양도 같이 늡니다. 편의 기능 하나하나가 요청마다 붙는 고정 비용이 되고요. 구독과 종량제 선택부터 캐시, 모델 조합, 상한 걸기까지 지금까지 확인한 것들을 일곱 단계 지도 한 장으로 묶어뒀습니다.

자주 묻는 것

Q. 그냥 깃허브 저장소로 배포하면 안 되나요?

대부분은 그게 맞습니다. 소스 종류가 여럿인데 깃허브·일반 깃·하위 폴더·패키지·압축 파일·상대 경로는 전부 파일을 가져오는 방식이고, 명령 실행이 필요 없습니다. 명령 소스는 내용이 사용자 환경에 따라 달라져야 할 때를 위한 것입니다 — 문서가 든 예가 지금 선택된 개발 환경에 맞춰 플러그인을 만들어내는 도구고요. 그런 요구가 없다면 굳이 사용자에게 명령 수락을 요구할 이유가 없습니다. 플러그인을 설치해 쓰는 쪽만 해봤다면, 배포하는 쪽은 이렇게 갈래가 많습니다.

Q. 명령이 오래 걸리면 어떻게 되나요?

제한 시간을 넘기면 중단되고 설치·갱신이 실패합니다. 기본은 60초, 최대 600초까지 늘릴 수 있습니다. 세션마다 백그라운드로 도는 걸 생각하면 길게 잡는 게 좋기만 한 건 아닙니다 — 매번 그만큼 뭔가가 돌고 있다는 뜻이니까요. 그리고 명령이 정상 종료하지 않거나 한 줄이 아닌 걸 출력하면 역시 실패합니다.

Q. 마켓플레이스가 플러그인 구성을 바꿀 수도 있나요?

됩니다. 기본은 플러그인 자체 정의가 권위고 마켓플레이스 항목은 거기에 추가만 얹습니다. 그런데 이걸 뒤집는 설정이 있어서, 켜면 마켓플레이스 항목이 전체 정의가 되고 플러그인 쪽이 구성을 선언하면 충돌로 로드가 실패합니다. 문서가 용도를 밝히는데 — 마켓플레이스 운영자가 원본을 자기 방식대로 재구성하거나 골라 내놓고 싶을 때입니다. 남의 플러그인을 사내용으로 다듬어 배포하는 상황이 여기 해당하겠죠.

📊 배포한 뒤, 상대 대시보드에는 이름이 안 남습니다 (8월 17일 추가)

이 글은 플러그인을 만들어 배포하는 쪽 이야기였습니다. 그 뒤를 하나 덧붙이자면 — 쓰는 조직이 사용량을 측정하고 있을 때 내 플러그인이 어떻게 보이는가입니다. 공식 문서를 보니 비용 지표에 플러그인 이름과 마켓플레이스 이름이 꼬리표로 붙는데, 공식 마켓플레이스에서 설치된 것만 이름이 그대로 적히고 나머지는 전부 "서드파티"로 대체됩니다. 사내 마켓플레이스를 만들어 배포했다면 담당자 대시보드에 내 플러그인 이름이 아니라 뭉뚱그려진 값이 찍힌다는 뜻이죠. 배포자 입장에서는 "우리 플러그인이 비용을 얼마나 쓰는지"를 이름으로 증명하기 어려워지는 대목입니다. 그렇다고 안 잡히는 건 아닙니다 — 가려지는 건 이름이지 금액이 아니라서, 서드파티 전체 합계로는 여전히 보입니다. 규칙이 항목마다 어떻게 갈리는지는 사용량 측정을 정리한 글에 표로 담았습니다.

✨ 오늘 확인한 것 정리

플러그인 소스 중 하나는 내 컴퓨터에서 셸 명령을 실행하고, 세션마다 백그라운드로 다시 돕니다. 그래서 명령은 500자 이내에 공백 네 칸 이상 연속 금지인데, 이유가 "사용자가 전체를 검토할 수 있도록"입니다 — 승인 절차가 형식이 되지 않게 막는 장치죠. 배포자가 명령을 바꾸면 재실행이 멈추고 다시 수락을 받아야 하고, 회사는 이 방식 전체를 차단할 수 있습니다.

※ 확인 경로(2026년 8월 17일 기준): code.claude.com/docs/en/plugin-marketplaces. 설정 항목 이름과 우리말 표현은 제가 옮긴 것입니다.

※ 이 소스 방식은 특정 버전 이상에서만 동작하며, 그 아래에서는 설치나 마켓플레이스 로드 자체가 실패할 수 있습니다.