Skill Git 관리 완전 가이드

팀 공유·브랜치 전략·버저닝까지 실전 운용 방법

배경 지식

Skill의 공유 패턴

Skill을 공유하는 방법은 스코프에 따라 다릅니다.

프로젝트 공유가 가장 실천적

많은 팀에서는 프로젝트 리포지토리에 .claude/skills/ 디렉토리를 포함하여 Git으로 관리하는 것이 가장 실천적입니다.

장점:

코드와 함께 버전 관리된다

Pull Request로 리뷰할 수 있다

팀 멤버가 git pull만으로 최신 Skill을 사용할 수 있다

온보딩 시 git clone 한 번으로 Skill 환경이 완성된다

※ 한국 팀 개발 현장에서의 팁
GitHub / GitLab / Bitbucket 등 어떤 플랫폼을 사용하든 동일하게 적용됩니다. 사내 GitLab을 운용 중인 팀도 .claude/skills/를 리포지토리에 포함하여 MR(Merge Request) 기반으로 관리하면 됩니다.

모노레포에서의 Skill 배치 (중첩된 디렉토리의 자동 감지)

Claude Code는 서브 디렉토리 내의 파일을 편집 중일 때, 해당 디렉토리 내의 .claude/skills/

도 자동으로 감지합니다.

예를 들어, packages/frontend/ 내의 파일을 편집 중인 경우:

---

my-monorepo/

.claude/skills/ # 프로젝트 전체의 Skill

pr-review/

packages/

frontend/

.claude/skills/ # frontend 고유의 Skill (자동 감지됨)

component-gen/

backend/

.claude/skills/ # backend 고유의 Skill (자동 감지됨)

api-gen/

---

이 구조로 인해, 모노레포에서 각 패키지에 고유한 Skill을 배치할 수 있습니다.

--add-dir로 추가한 디렉토리 내의 .claude/skills/도 동일하게 감지됩니다.

※ 한국 팀의 모노레포 활용 예
Turborepo, Nx 등의 모노레포 도구를 사용하는 경우, 각 패키지 디렉토리에 고유한 Skill을 배치할 수 있습니다. 예를 들어 packages/web/에는 React 컴포넌트 생성 Skill, packages/api/에는 NestJS 컨트롤러 생성 Skill을 배치하는 식으로 패키지별로 최적화된 Skill 세트를 구성할 수 있습니다.

스코프의 우선순위와 충돌

동명의 Skill이 여러 스코프에 존재하는 경우의 우선순위는 다음과 같습니다.

enterprise > personal > project

플러그인 Skill에 대해: 플러그인을 통해 제공되는 Skill은 plugin-name:skill-name이라는 별도의 네임스페이스로 관리되므로, 위의 우선순위와 충돌하지 않습니다.