Claude Code 플러그인으로 팀에 스킬 한 번에 배포하는 법

팀 협업 & 자동화

Claude Code 스킬을 혼자만 쓰기엔 아깝습니다. 플러그인으로 묶어서 팀 전체에 한 줄 명령으로 배포하는 방법을 처음부터 끝까지 정리했습니다.

📌 3줄 요약

• 스킬·서브에이전트를 plugin.json으로 패키징하면 팀원이 한 줄로 설치할 수 있다
• Git 저장소에 포함하면 git pull 한 번으로 최신 플러그인이 자동 배포된다
• 시맨틱 버저닝과 CHANGELOG로 버전을 관리하면 팀 전체 AI 작업 품질이 일정해진다

📑 목차

• 1. 스킬을 팀에 공유해야 하는 이유
• 2. 플러그인 디렉토리 구조 만들기
• 3. Git 저장소로 팀에 플러그인 배포하기
• 4. 플러그인 업데이트와 버전 관리 전략

스킬을 팀에 공유해야 하는 이유

Claude Code에서 스킬(skill)이나 서브에이전트(subagent)를 하나 만들면, 보통 내 컴퓨터의 .claude/ 폴더 안에 저장됩니다. 문제는 이 파일들이 개인 로컬에만 존재한다는 겁니다. 다른 팀원이 내 스킬을 쓰고 싶어도, 그 사람 컴퓨터에는 해당 파일이 없으니 당연히 실행이 안 됩니다.

팀원이 같은 스킬을 쓰려면, 파일을 하나하나 복사해서 넘겨줘야 합니다. 스킬이 2~3개면 괜찮지만, 10개가 넘어가면 수작업 공유는 실수 투성이가 됩니다. 슬랙으로 파일을 보내고, 압축 풀고, 어느 폴더에 넣어야 하는지 설명하는 과정이 매번 반복됩니다. 특히 스킬을 수정할 때마다 전체 팀원에게 다시 전달해야 하므로, 변경이 잦을수록 혼란이 커집니다.

누군가는 옛날 버전을 쓰고, 누군가는 폴더 구조를 잘못 복사하고, 결국 "나는 되는데 너는 왜 안 돼?"라는 대화가 시작됩니다. 한 번이라도 이런 상황을 겪어보면, 체계적인 배포 방식이 절실하다는 걸 느끼게 됩니다. 이 문제를 한 방에 해결하는 것이 플러그인(plugin) 방식입니다.

플러그인은 스킬과 서브에이전트를 하나의 패키지로 묶어서, 팀원이 한 줄 명령으로 전부 설치할 수 있게 만들어 줍니다. 버전 관리까지 자동으로 되기 때문에, 누가 어떤 버전을 쓰고 있는지 헷갈릴 일도 없어집니다.

💬 직접 써보니까 3명 이상이 같은 워크플로우를 쓰는 프로젝트라면, 플러그인 없이 버티기가 어렵습니다.

 

플러그인 디렉토리 구조 만들기

플러그인을 만들려면 먼저 정해진 폴더 구조를 갖춰야 합니다. 프로젝트 루트에 claude-plugin/ 같은 디렉토리를 하나 만드는 것부터 시작합니다. 폴더 이름은 자유지만, 팀원 모두가 알아볼 수 있는 직관적인 이름을 권장합니다.

기본 구조는 아래와 같습니다.

claude-plugin/
├── plugin.json
├── skills/
│   ├── my-skill-1/
│   │   └── skill.md
│   └── my-skill-2/
│       └── skill.md
└── agents/
    └── code-reviewer/
        └── agent.md

🔍 plugin.json은 플러그인의 이름, 버전, 포함된 스킬 목록을 정의하는 설정 파일입니다. 이 파일이 없으면 Claude Code가 해당 폴더를 플러그인으로 인식하지 못합니다. 말하자면 plugin.json이 플러그인의 신분증 역할을 하는 셈입니다.

plugin.json의 기본 형태는 다음과 같습니다.

{
  "name": "my-team-plugin",
  "version": "1.0.0",
  "description": "우리 팀 공용 스킬 모음",
  "skills": ["skills/my-skill-1", "skills/my-skill-2"],
  "agents": ["agents/code-reviewer"]
}

skills 배열에는 포함할 스킬 폴더의 경로를 적습니다. agents 배열에도 같은 방식으로 서브에이전트 경로를 나열합니다. 배열 안의 순서는 상관없지만, 나중에 관리하기 편하도록 알파벳 순이나 기능별로 정리해 두는 것이 좋습니다.

⚠️ 주의

경로는 plugin.json 파일 기준 상대 경로로 작성해야 합니다. 절대 경로(C:\Users\...)를 쓰면 다른 팀원의 컴퓨터에서 경로가 달라서 작동하지 않습니다.

💡 팁

운영체제가 섞인 팀이라면 슬래시(/) 방향도 통일해 두는 것이 좋습니다. Windows에서는 역슬래시(\)를 쓰지만, JSON 파일 안에서는 슬래시(/)로 적어야 모든 운영체제에서 문제없이 인식됩니다.

 

Git 저장소로 팀에 플러그인 배포하기

플러그인 폴더가 완성되면, 이것을 팀원에게 전달할 차례입니다. 가장 깔끔한 방법은 Git 저장소에 플러그인 폴더를 포함시키는 것입니다. Git을 이미 쓰고 있는 팀이라면 별도 도구를 추가할 필요가 전혀 없습니다.

프로젝트 저장소 안에 claude-plugin/ 폴더를 함께 커밋하면, 팀원이 git pull만 해도 최신 플러그인을 받을 수 있습니다. 별도의 설치 과정이 필요 없다는 것이 가장 큰 장점입니다. 코드 리뷰 과정에서 스킬 변경 사항도 자연스럽게 확인할 수 있어서 품질 관리에도 도움이 됩니다.

팀원이 플러그인을 적용하려면 프로젝트 루트의 .claude/settings.json에 플러그인 경로를 등록해야 합니다.

{
  "plugins": ["./claude-plugin"]
}

이 설정 파일도 저장소에 포함시키면, 팀원은 클론(clone) 한 번으로 스킬과 서브에이전트를 전부 사용할 수 있습니다. 새로 합류한 팀원도 별도 안내 없이 동일한 환경을 갖추게 됩니다.

💬 온보딩 시간이 크게 줄어들기 때문에, 팀 입장에서는 생산성 향상 효과가 상당합니다.

만약 프로젝트 저장소와 플러그인 저장소를 분리하고 싶다면, 별도 Git 저장소를 만들어 URL로 참조하는 방법도 있습니다.

{
  "plugins": ["https://github.com/my-team/claude-plugins.git"]
}

이 방식은 여러 프로젝트에서 같은 플러그인을 공유할 때 유용합니다. 예를 들어 백엔드 프로젝트와 프론트엔드 프로젝트가 동일한 코드 리뷰 에이전트를 사용한다면, 별도 저장소 하나에 관리하는 것이 중복을 줄여 줍니다.

⚠️ 저장소 접근 권한 설정을 빠뜨리면 팀원이 설치에 실패하므로, 권한 관리를 꼭 확인하세요.

배포 방식	적합 규모	특징
프로젝트 내 폴더	5명 이하	단순하고 편의성이 압도적
별도 Git 저장소	10명 이상	여러 프로젝트 공유, 관리 용이

💬 두 방식 모두 써본 결과, 소규모 팀에서는 폴더 방식의 편의성이 압도적이었습니다.

 

플러그인 업데이트와 버전 관리 전략

플러그인은 한 번 배포하면 끝이 아닙니다. 스킬을 수정하거나 새 서브에이전트를 추가할 때마다 팀 전체에 반영해야 합니다. 업데이트 없이 방치하면, 시간이 지날수록 팀원마다 다른 버전을 사용하게 되어 결국 처음의 수작업 공유와 다를 바 없어집니다.

plugin.json의 version 필드를 활용하면 변경 이력을 추적할 수 있습니다. 스킬 내용이 바뀔 때마다 버전 번호를 올리는 습관을 들이는 것이 중요합니다.

{
  "name": "my-team-plugin",
  "version": "1.2.0",
  "description": "코드 리뷰 에이전트 추가"
}

🔍 시맨틱 버저닝(semantic versioning, 의미 기반 버전 규칙)을 따르면 팀원이 변경 규모를 한눈에 파악할 수 있습니다. 숫자 세 자리 중 첫째 자리는 큰 변경, 둘째 자리는 기능 추가, 셋째 자리는 버그 수정을 뜻합니다. 예를 들어 1.2.0에서 1.3.0으로 바뀌었다면 새 기능이 추가된 것이고, 2.0.0으로 바뀌었다면 기존 스킬의 동작이 크게 달라졌을 수 있다는 신호입니다.

Git 저장소 방식을 쓰고 있다면, 플러그인 수정 후 커밋-푸시만 하면 됩니다. 팀원은 git pull 한 번이면 최신 버전을 받습니다.

💡 팁 커밋 메시지에 어떤 스킬이 바뀌었는지 한 줄로 적어두면, 나중에 변경 이력을 추적하기 훨씬 수월합니다.

별도 저장소 방식이라면 claude plugin update 명령으로 최신 버전을 가져올 수 있습니다.

claude plugin update my-team-plugin

이 명령은 원격 저장소에서 최신 커밋을 내려받아 로컬 플러그인 폴더를 갱신합니다. 팀원이 이 명령을 실행하기만 하면 되므로, 별도 안내 없이도 업데이트가 가능합니다.

⚠️ 주의

스킬 파일의 프롬프트(prompt)를 크게 바꾸면 기존에 잘 되던 워크플로우가 깨질 수 있습니다. 큰 변경은 반드시 팀 채널에 공지하고, 테스트를 거친 뒤 반영하는 것을 권장합니다. 가능하다면 별도 브랜치에서 변경된 스킬을 먼저 테스트하고, 문제가 없을 때 메인 브랜치에 머지하는 방식이 안전합니다.

💡 팁 변경 내역을 CHANGELOG.md 파일에 한 줄씩 남겨두면, 나중에 "이 스킬이 왜 바뀌었지?" 하는 상황에서 시간을 아낄 수 있습니다.

플러그인 관리가 번거로워 보여도, 팀 전체의 AI 작업 품질을 일정하게 유지하는 데는 이 방법이 가장 확실합니다.

 

✍️ 마치며

Claude Code 스킬을 파일 단위로 공유하던 시절은 이제 끝났습니다. plugin.json 하나로 스킬과 서브에이전트를 패키징하고, Git 저장소에 올려두면 팀원은 git pull 한 번으로 최신 환경을 갖출 수 있습니다. 시맨틱 버저닝과 CHANGELOG까지 갖추면 "누가 어떤 버전을 쓰고 있는지" 고민할 필요도 사라집니다. 3명 이상이 Claude Code를 함께 쓰는 팀이라면, 오늘 바로 플러그인 구조부터 잡아 보세요.

#ClaudeCode #플러그인 #팀협업 #스킬배포 #버전관리 #AI자동화