서브에이전트를 GitHub로 배포하기 — 팀 공유부터 오픈소스까지

서브에이전트를 만들고 나면 팀원과 공유하고 싶어진다. 가장 직관적인 방법이 GitHub다. Git을 이미 쓰고 있고, 버전 관리가 되고, URL 하나로 설치할 수 있다. 이 글은 서브에이전트를 GitHub로 배포하는 두 시나리오를 설명한다 — 프로젝트에 포함시켜 자동 공유하는 방법과, 별도 저장소로 플러그인을 배포하는 방법.

두 시나리오 선택 기준

세 질문을 순서대로 던진다. MCP 도구가 필요한가? 여러 저장소·팀에 배포해야 하는가? 버전 고정이 필요한가? 어느 하나라도 "예"라면 시나리오 2(별도 저장소 플러그인)로 간다. 세 질문 모두 "아니오"라면 시나리오 1(프로젝트에 포함)로 충분하다. MCP가 첫 분기 기준인 이유는 뒤에서 다시 보충하지만, 짧게 말하면 시나리오 1로도 MCP를 동봉할 수는 있어도 첫 사용 때마다 사용자 승인을 거쳐야 해서 자동화 흐름이 끊긴다.

시나리오 1 — 프로젝트에 포함, git pull로 자동 공유

가장 간단하다. 파일을 커밋하면 끝이다. 팀원은 git pull 한 번으로 에이전트를 받는다. 별도 설치 명령이 필요 없다.

프로젝트 구조

my-project/
├── src/
├── tests/
└── .claude/
    └── agents/
        └── domain-reviewer.md   ← Git에 커밋

변경 이력 추적

에이전트가 코드와 같은 commit 그래프에 묶여 있어서 가능한 일이다. git log .claude/agents/ 한 줄로 에이전트 규칙이 언제 어떤 commit에서 추가·수정·삭제됐는지 시간 순으로 본다. "왜 갑자기 리뷰어가 type-check를 요구하지?" 같은 질문이 commit 메시지로 곧장 답이 된다. 별도 저장소로 떼어내면 잃게 되는 추적성이다.

시나리오 2 — 별도 저장소로 플러그인 배포

흐름은 npm 패키지나 VS Code 확장 배포와 동형이다. 개발자는 한 번 푸시하고, 외부 사용자는 URL 하나로 설치한다. 설치된 플러그인은 각 팀원의 ~/.claude/plugins/cache/ 아래에 보관되며, 에이전트 정의와 함께 .mcp.json에 적힌 MCP 서버까지 같이 활성화된다. 시나리오 1과 결정적으로 다른 점은 "특정 프로젝트 안에 갇혀 있지 않다"는 것이다 — 같은 에이전트를 여러 프로젝트·여러 팀에서 동시에 쓰는 순간 시나리오 2가 유일한 답이 된다.

저장소 구조 — 루트가 플러그인 루트여야 한다

.claude-plugin/이 저장소 루트에서 바로 보여야 한다. 서브디렉토리 안에 있으면 플러그인으로 인식되지 않는다.

버전 태그 — 안정 버전 고정

핵심은 두 갈래로 갈린다. 태그 없이 설치하면 main 브랜치가 그대로 따라온다 — main이 한 번 바뀌면 다음 /plugin update 시점에 팀 전체 동작이 일제히 바뀐다. 반면 URL@v1.0.0 형태로 태그를 박으면 그 시점의 동작이 그대로 고정된다. 덕분에 배포 후에도 main에 실험적인 변경을 자유롭게 머지할 수 있다. 그래서 모든 팀 배포는 태그 고정 설치를 권장 패턴으로 둔다.

Private 저장소 — 비공개 배포

공개 플러그인과 같은 명령으로 설치되지만 내부 인증이 한 단계 더 끼는 것이 차이다. GITHUB_PERSONAL_ACCESS_TOKEN 환경변수만 미리 설정해두면 /plugin install이 PAT으로 인증해 비공개 저장소를 그대로 다운로드한다. 덕분에 외부 공개가 어려운 비공개 API 스키마·도메인 규칙·내부 명명 규칙을 에이전트와 함께 묶어 팀 안에서만 돌릴 수 있다. 외부 유출 위험 없이 조직 특화 지식을 에이전트에 녹이는 표준 경로다.

업데이트 흐름

업데이트와 롤백이 같은 인터페이스로 묶인다. /plugin update는 캐시를 새 태그로 갈아끼우고, 문제가 보이면 똑같은 /plugin install URL@v1.0.0 한 줄로 이전 태그를 다시 잡으면 끝이다. 이전 캐시는 지워지지 않으므로 빠른 복귀가 가능하다. "배포가 사고를 키운다"는 부담을 가장 잘 줄여주는 부분이다.

두 시나리오 최종 비교

▲ 시나리오 1: 프로젝트 포함 — .claude/agents/ 커밋, git pull로 공유

이 박스가 보여주는 핵심은 시나리오 1의 모든 강점이 "이 프로젝트 안에서만"이라는 전제를 깔고 있다는 점이다. 코드와 같이 다니니 추적성·통일성이 자동으로 따라오지만, 같은 에이전트를 다른 프로젝트에서 다시 쓰려면 복사·붙여넣기로 시작해야 한다. 단일 팀·도메인 특화에 가장 잘 맞는 까닭이다.

▲ 시나리오 2: 별도 저장소 플러그인 — /plugin install, MCP 포함 배포

여기서는 반대로 에이전트가 코드에서 떨어져 나와 그 자체가 독립 제품이 된다. 한 번 만들어 여러 프로젝트·팀·외부 사용자에게 같은 URL로 나눠준다. 버전을 태그로 박을 수 있고, MCP 서버까지 함께 묶여 한 번의 설치로 도구 세트가 통째로 따라온다. 대신 그 자체를 유지보수할 책임도 같이 따라온다.

한 가지 짚을 점은 시나리오 1도 MCP를 동봉할 수는 있다는 것이다. 프로젝트 루트에 .mcp.json을 두고 git에 커밋하면 팀원이 git pull로 동일한 MCP 서버 설정을 받는다(claude mcp add --scope project가 이 파일을 생성한다). 다만 claude mcp list에 ⏸ Pending approval 상태로 잡혀 첫 사용 때마다 사용자가 직접 신뢰 승인을 거쳐야 한다. 플러그인은 마켓플레이스 메타데이터로 이 승인 단계를 한 번에 정형화하고, 검색·발견성까지 가져간다. 즉 진짜 차이는 "MCP 공유 가능 여부"가 아니라 "승인 자동화와 발견성"이다.

혼용도 좋다. 공통 에이전트는 플러그인으로 팀에 배포하고, 프로젝트 특화 에이전트는 .claude/agents/에 커밋하는 전략이 현실적으로 가장 효과적이다. MCP 도구 배포 자동화 수준이 가장 강력한 선택 기준이다.

---

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