플러그인으로 서브에이전트 배포하기 — /plugin install부터 마켓플레이스까지

GitHub 저장소를 플러그인 구조로 만들면 /plugin install 한 줄로 설치할 수 있다. 더 나아가 Anthropic의 공식 마켓플레이스에 제출하면 전 세계 Claude Code 사용자가 이름만으로 설치하는 것도 가능하다. 이 글은 로컬 설치부터 마켓플레이스 배포까지 전체 흐름을 다룬다.

플러그인 배포의 세 단계

플러그인을 만들면 대개 이 세 단계를 차례로 거친다. 처음에는 로컬 디렉토리를 그대로 설치해 수정-실행 사이클을 빠르게 돌린다. 동작이 검증되면 GitHub에 올려 팀원·외부에 URL을 공유하고, 충분히 안정화된 뒤에만 마지막 단계인 마켓플레이스 제출을 고민한다. 각 단계에서 코드의 모양은 바뀌지 않고 설치 출처만 달라진다는 점이 핵심이다 — 사용자 입장에서는 어떤 단계든 /plugin install 한 명령으로 통일되어 있어 배포 경로를 갈아타기가 쉽다.

플러그인 최소 구조 — 두 파일이면 충분

플러그인을 기능하게 만드는 최소 단위는 두 개 파일이다. .claude-plugin/plugin.json이 이름·버전·설명 같은 메타데이터를 담아 Claude Code가 "이게 플러그인이구나"를 식별하게 해 주고, agents/<name>.md 한 장이 서브에이전트의 시스템 프롬프트·도구 권한·트리거 조건을 정의한다. 폴더 이름(.claude-plugin, agents)과 파일 위치는 규약이므로 정확히 맞춰야 인식된다. 반대로 그 안의 내용은 자유롭게 작성할 수 있어, 빈 프로젝트에서 5분 안에 첫 플러그인을 띄울 수 있다.

플러그인 완전 구조 — 선택 구성요소를 더하면

필수 두 파일 외에 선택 구성요소를 더하면 플러그인이 풍부해진다. .mcp.json은 외부 MCP 서버 정의를 묶어 에이전트가 GitHub·DB·브라우저 같은 도구를 호출할 수 있게 한다. commands/는 슬래시 커맨드 형태로 사용자 인터페이스를 추가해, 사용자가 /my-cmd로 직접 진입점을 부를 수 있게 만든다. skills/는 절차 중심 작업(예: TDD 워크플로우, 빌드 스크립트)을 등록하는 자리다. README.md는 형식상 선택이지만 마켓플레이스 페이지의 본문으로 그대로 노출되므로 사실상 필수에 가깝다. 처음에는 최소 구조로 시작해 필요해질 때 하나씩 추가하는 방식을 권한다.

1단계: 로컬 경로로 설치 — 개발 중 테스트

로컬 경로 설치의 동작 모델을 이해해야 반복 개발이 자연스럽다. /plugin install ~/dev/my-plugin을 실행하면 Claude Code는 해당 경로를 ~/.claude/plugins/cache/ 아래로 복사한다. 즉, 원본 디렉토리와 캐시는 별개여서 원본을 수정해도 캐시에는 반영되지 않는다. 그래서 수정 → 테스트 사이클마다 uninstall → install을 반복해야 한다. 번거로워 보이지만 이 격리 덕분에 검증되지 않은 변경이 활성 플러그인에 즉시 흘러들어 가지 않는다. 사이클을 자주 돌린다면 짧은 셸 alias나 makefile target으로 묶어두면 편하다.

2단계: GitHub URL로 설치

GitHub에 푸시한 뒤에는 저장소 URL 하나면 누구나 설치할 수 있다. 핵심 결정은 버전 태그를 고정할지다. URL 뒤에 @v1.0.0 같은 태그를 붙이면 Claude Code가 정확히 그 커밋을 받기 때문에, 운영 환경이 의도치 않은 main 브랜치 변경에 노출되지 않는다. 같은 버전을 팀이 공유한다는 보장이 필요한 시점부터는 태그 고정이 사실상 필수다. 반대로 개발자 본인이 빠르게 dogfood만 하는 상황이라면 @ 없이 설치해 main을 따라가도 된다. 캐시 경로가 출처/이름/버전 단위로 나뉘기 때문에 같은 플러그인의 여러 버전을 병행 설치하는 것도 가능하다.

설치 후 관리 명령어

일상 관리는 네 명령으로 끝난다. /plugin list로 현재 어떤 플러그인이 설치돼 있는지 한눈에 확인하고, /plugin info로 메타데이터·진입점·MCP 서버 상태 같은 자세한 정보를 본다. /plugin update는 같은 URL의 최신 버전을 다시 받아오므로 태그 고정 설치라면 새 태그가 릴리즈됐을 때만 의미가 있다. 제거는 /plugin uninstall 한 번으로 끝나고, 캐시는 자동 삭제되어 별도 정리가 필요 없다. 명령어가 단순한 덕분에 슬랙·문서에 "이 URL을 install하세요" 한 줄을 적어두면 팀원 셋업이 끝난다는 점이 이 배포 모델의 강점이다.

3단계: 마켓플레이스 등록 — 공식 채널로 배포

마켓플레이스 제출은 단순한 푸시가 아니라 타인의 환경에서 안전하게 동작할지 검증받는 과정이다. 먼저 claude plugin validate를 돌려 plugin.json 스키마·필수 필드·이름 충돌 같은 정적 검사를 통과해야 한다. 이후 제출 폼을 통해 Anthropic 심사로 넘어가고, 보안·악성 코드·중복 이름 등을 며칠에 걸쳐 검토한다. 거절되면 피드백을 기반으로 수정한 뒤 재제출하는 루프를 돌게 된다. 통과하면 claude-plugins-community 카탈로그에 등록돼 전 세계 사용자가 URL 없이 이름만으로 설치할 수 있다. URL 공유의 신뢰 부담을 사용자에게 넘기지 않는다는 점이 이 단계의 가장 큰 이득이다.

마켓플레이스 종류 — 공식 vs 커뮤니티

공식과 커뮤니티는 심사 강도와 운영 주체가 다르다. 공식 마켓플레이스는 Anthropic이 직접 관리하고 검토하기 때문에 GitHub MCP·Playwright MCP·context7처럼 인프라급으로 쓰이는 플러그인이 주로 올라가 있다. 보안·호환성 기준이 높아 통과까지 시간이 들지만 통과되면 사실상 표준 도구로 자리잡는다. 커뮤니티 마켓플레이스는 진입 장벽이 낮아 개인이 만든 실험적 플러그인이 모이며, 사용자 리뷰와 다운로드 수가 품질의 일차 신호 역할을 한다. 본인 플러그인이 어느 쪽에 적합한지는 대상 사용자 규모와 본인이 감당할 유지보수 부담을 보고 결정하면 된다.

팀 전용 마켓플레이스 — Private 마켓플레이스 구성

공개하기 어려운 팀 내부 도구라면 Private GitHub 저장소를 그대로 마켓플레이스로 쓸 수 있다. 저장소 루트의 marketplace.json이 플러그인 카탈로그(이름·버전·진입 경로)를 정의하고, 각 플러그인은 plugins/<name>/ 하위에 둔다. 팀원은 /plugin marketplace add <repo-url>로 카탈로그를 한 번 등록한 뒤로 공식 마켓플레이스처럼 /plugin install agent-a@company 형태로 설치한다. GitHub 외에 GitLab·내부 git 호스팅도 동일한 구조로 동작하므로, 회사 정책상 외부 저장소를 쓸 수 없는 환경에서도 그대로 적용 가능하다.

여기서 한 가지 주의할 함정이 있다 — auto-update 기본값이 마켓플레이스 종류마다 다르다. 공식 Anthropic 마켓플레이스는 auto-update가 기본 ON이라 Claude Code 시작 시 자동으로 카탈로그가 새로고침되지만, 서드파티·팀·로컬 마켓플레이스는 기본 OFF다. 그래서 팀원이 새 플러그인을 카탈로그에 추가해도 다른 팀원의 /plugin Discover 탭에는 자동으로 나타나지 않는다. 둘 중 하나가 필요하다 — 매번 /plugin marketplace update company를 수동 실행하거나, 처음 add한 직후 /plugin → Marketplaces 탭에서 해당 마켓플레이스의 Enable auto-update를 토글해 두는 것이다. 팀 운영 차원에서는 onboarding 문서에 "add 직후 auto-update 켜기"를 명시해 두면 신규 플러그인이 자동으로 퍼진다.

전체 배포 생명주기

마켓플레이스 등록은 흐름의 선택지일 뿐이라는 점이 가장 중요하다. 팀 내부 도구라면 Private 저장소 + URL 공유만으로 충분하고, 공개 배포가 목적일 때만 마지막 가지인 마켓플레이스 제출을 고려한다. 어느 경로를 택해도 공통 원칙은 두 가지다. 첫째, 버전 태그로 안정성을 보장한다 — main 브랜치 직접 설치는 개발자 본인의 dogfood용으로만 안전하다. 둘째, 업데이트는 사용자에게 위임한다 — 자동 업데이트 메커니즘은 없으므로 새 태그를 릴리즈했다면 changelog로 알리고 팀원에게 /plugin update를 권장하는 운영 패턴이 일반적이다. 이 두 원칙만 지키면 알파에서 마켓플레이스까지의 전 구간이 같은 도구·같은 명령어로 매끄럽게 이어진다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.