Claude Code 플러그인 만들기: 팀 자동화를 재사용 가능한 패키지로 바꾸는 법

Read in English

Claude Code를 쓰다 보면 프로젝트마다 비슷한 지침, 검토 절차, MCP 연결을 다시 설정하게 됩니다. 처음에는 저장소의 .claude/ 폴더에 두는 편이 빠릅니다. 하지만 여러 저장소와 여러 사람이 같은 작업 흐름을 써야 한다면, 파일을 복사하는 방식은 버전 차이와 권한 실수를 키우기 쉽습니다. 이때 필요한 단위가 Claude Code 플러그인입니다.

이 글은 개인 또는 단일 프로젝트 설정을 언제 플러그인으로 바꿔야 하는지, 최소한의 구조는 무엇인지, 팀에 배포하기 전에 무엇을 검토해야 하는지를 정리합니다. 공식 문서를 기준으로 실제 파일을 놓는 위치와 실행할 명령, 검토할 결과를 구분했습니다. 플러그인 기능 자체를 새로 출시된 기능으로 소개하는 글은 아닙니다.

공유할 구성 요소를 플러그인으로 묶어 여러 팀에 배포하는 개념도입니다. 실제 매니페스트 경로는 아래 예시의 .claude-plugin/plugin.json이며, 그림은 파일 트리를 그대로 표시한 것이 아닙니다.

먼저 구분하기: .claude/ 설정과 플러그인은 역할이 다르다

프로젝트 루트의 .claude/는 해당 저장소에만 맞는 빠른 실험과 규칙에 적합합니다. 예를 들어 특정 서비스의 테스트 명령, 그 저장소만의 코드 스타일, 아직 검증 중인 프롬프트라면 저장소 설정으로 시작하는 편이 안전합니다. 반면 플러그인은 스킬, 에이전트, 훅, MCP 서버 설정처럼 여러 프로젝트에서 반복할 구성 요소를 하나의 디렉터리로 묶어 공유하는 방식입니다.

판단 기준	프로젝트 설정	플러그인
주된 목적	한 저장소의 빠른 맞춤	여러 저장소·팀의 재사용
변경 관리	프로젝트 커밋과 함께 관리	독립 버전과 배포 단위로 관리
명령 이름	예: /hello	예: /plugin-name:hello
시작 시점	문제와 규칙이 아직 변할 때	작업 흐름이 반복되고 검토 기준이 안정됐을 때

주의할 점은 경로의 범위입니다. 저장소 안의 .claude/settings.json은 커밋하면 팀이 공유할 수 있고, .claude/settings.local.json은 그 저장소에서 개인이 쓰는 설정입니다. 사용자 홈의 ~/.claude/settings.json은 같은 컴퓨터의 여러 프로젝트에 적용됩니다. 따라서 .claude/라는 이름만 보고 무조건 개인 전용이라고 판단하면 안 됩니다.

이 구분은 단순한 폴더 정리가 아닙니다. 플러그인에는 배포 가능한 자동화가 들어갈 수 있으므로, “편리한가”보다 “다른 저장소에서도 같은 권한과 결과 기준으로 안전하게 동작하는가”를 먼저 묻는 것이 좋습니다.

시작 전 준비: 범위와 권한을 한 장으로 정리한다

먼저 Claude Code를 설치하고 인증을 마친 환경이 필요합니다. 민감한 코드나 자격증명이 없는 연습용 저장소에서 시작하세요. 아래 명령은 Claude 채팅창이 아니라 그 저장소 루트에서 연 일반 터미널에 입력합니다.

파일을 만들기 전, 플러그인이 할 일을 한 문장으로 좁히세요. “PR에서 변경된 API 계약만 검사하고, 수정은 하지 않는다”처럼 입력, 허용 도구, 산출물, 금지 행동을 분명히 적습니다. 이어서 다음 네 가지를 확인합니다.

1. 대상 저장소: 어떤 언어·디렉터리·CI 환경에서 쓸지 정합니다. 모든 저장소를 대상으로 삼지 않습니다.
2. 실행 주체: 개발자 로컬 실행인지, GitHub Actions 같은 CI 실행인지 구분합니다. CI는 저장소 관리자 권한과 비밀값 관리가 추가로 필요합니다.
3. 필요 권한: 읽기만 필요한지, 이슈 댓글 작성·브랜치 푸시·외부 MCP 호출이 필요한지 목록으로 만듭니다.
4. 검토 기준: 성공을 “코드를 고쳤다”가 아니라, 예를 들어 “변경된 공개 API와 테스트 누락을 목록으로 남겼다”처럼 확인 가능한 형태로 정의합니다.

비밀값, 고객 데이터, 프로덕션 접근 권한을 프롬프트나 플러그인 파일에 직접 넣지 마세요. GitHub Actions에서 자동화한다면 인증 정보는 저장소 또는 조직의 Secrets로 분리하고, 워크플로에 필요한 최소 권한만 부여하는 것이 공식 가이드의 기본 원칙입니다.

최소 플러그인 구조 만들기

Claude Code 공식 문서는 플러그인 루트에 구성 요소를 두고, .claude-plugin/ 디렉터리에는 plugin.json만 두라고 안내합니다. 즉 skills/, agents/, hooks/를 매니페스트 폴더 안에 넣지 않는 것이 핵심입니다. 아래는 공유할 검토 스킬 하나로 시작하는 최소 구조입니다.

api-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── api-review/
│       └── SKILL.md
└── README.md

연습용 저장소 루트에서 다음 폴더를 만든 뒤 편집기로 두 파일을 저장합니다. 폴더 생성 명령은 macOS·Linux 셸 기준이며, 다른 환경에서는 같은 구조를 파일 탐색기나 편집기로 만들어도 됩니다.

mkdir -p api-review-plugin/.claude-plugin api-review-plugin/skills/api-review

파일 1: api-review-plugin/.claude-plugin/plugin.json

{
  "name": "api-review-plugin",
  "version": "1.0.0",
  "description": "Review a specified API change without editing files"
}

파일 2: api-review-plugin/skills/api-review/SKILL.md

---
description: 사용자가 지정한 코드 변경에서 공개 API와 테스트 공백을 검토한다.
---
1. 사용자가 지정한 변경 범위를 먼저 확인한다. 범위가 없으면 질문한다.
2. 공개 인터페이스 변화와 관련 테스트만 검토한다.
3. 결과를 근거 파일, 예상 영향, 필요한 테스트, 불확실한 점으로 나눈다.
4. 파일을 수정하거나 외부에 전송하지 않는다.
5. 확인하지 못한 동작은 검증 완료로 표현하지 않는다.

이 지침은 검토 범위를 정하는 예시입니다. 스킬에 “수정하지 않는다”고 적는 것과 실제 도구 권한을 차단하는 것은 다릅니다. 읽기 전용 작업에 맞게 별도의 권한 설정도 확인해야 합니다. 기능이 늘어날 때 agents/, hooks/, .mcp.json 등을 플러그인 루트에 추가합니다.

참고로 공식 문서의 claude plugin init my-tool은 ~/.claude/skills/my-tool/에 시작 구조를 만들고 다음 세션부터 자동으로 불러오는 별도 방식입니다. 현재 폴더에 같은 이름의 디렉터리를 만든다고 가정하면 안 됩니다. 이 글은 위치를 분명히 하기 위해 수동 디렉터리와 --plugin-dir 경로를 사용합니다.

로컬에서 먼저 확인하는 순서

1. 위 파일을 저장한 연습용 저장소 루트에 일반 터미널을 엽니다. api-review-plugin/ 폴더가 그 아래 있는지 확인합니다.
2. 터미널에서 claude --plugin-dir ./api-review-plugin을 실행해 로컬 플러그인을 불러옵니다. 다른 위치에서 실행한다면 실제 위치에 맞는 경로를 지정합니다.
3. 열린 Claude Code 입력창에서 /api-review-plugin:api-review를 호출하고 검토할 파일·변경 범위를 지정합니다. 요청 예시는 “지정한 변경에서 공개 API와 관련 테스트 공백만 근거 파일과 함께 표로 정리해 줘”입니다.
4. 출력에 대상 밖 파일, 비밀값, 과도한 추정이 없는지 검토합니다. 명령의 결과가 아니라 보고 형식과 범위 준수가 완료 확인 기준입니다.
5. 두 번째 저장소에서도 같은 이름 충돌, 경로 가정, 불필요한 권한 요청이 없는지 확인한 뒤에만 공유 범위를 넓힙니다.

파일을 수정한 뒤에는 Claude Code 안에서 /reload-plugins를 실행해 변경을 반영합니다. 공유 전에는 일반 터미널에서 claude plugin validate ./api-review-plugin을 실행하고 오류와 경고를 점검합니다. 이 검사는 구성 검증이지 스킬의 정확성이나 보안 전체를 보증하는 절차는 아닙니다.

여기서 --plugin-dir는 개발·시험용으로 유용합니다. 팀 공용 플러그인을 곧바로 전사 설정으로 밀어 넣기보다, 실제 사용자가 검토할 수 있는 변경 이력과 README를 함께 두는 편이 운영 비용을 낮춥니다.

활용 예시 3가지: 목적과 경계를 함께 적는다

1. API 변경점 검토

목적은 PR의 공개 인터페이스 변화와 테스트 누락을 정리하는 것입니다. 입력은 변경된 파일과 PR 설명, 산출물은 영향 범위·확인할 테스트·불확실한 항목 목록입니다. 자동 수정이나 배포 권한은 주지 않습니다. 사람은 실제 API 호환성 판단과 결과 반영을 맡습니다.

2. 릴리스 노트 초안 만들기

입력은 승인된 커밋 목록과 이미 공개 가능한 이슈입니다. 스킬은 사용자 영향, 마이그레이션 필요 여부, 확인이 필요한 주장으로 초안을 나누게 합니다. 고객명·비공개 티켓·확정되지 않은 성능 수치는 제외하도록 규칙을 둡니다. 최종 공개 전에는 제품 담당자가 사실과 표현을 검토합니다.

3. CI에서 반복 리포트 실행

GitHub Actions 연동에서는 이벤트와 프롬프트를 명시하면 자동 실행 모드로 사용할 수 있습니다. 이 경우 실행 로그만 남길지, PR에 댓글을 쓸지 미리 선택하고 필요한 권한을 최소화합니다. 비용은 GitHub Actions 실행 시간과 모델 사용량 모두에서 발생할 수 있으므로, 작업 범위·최대 턴·워크플로 타임아웃을 제한하는 것이 좋습니다.

막히는 지점과 해결 순서

명령이 보이지 않거나 이름이 충돌한다면, 먼저 플러그인 디렉터리 구조와 매니페스트 위치를 확인합니다. 플러그인 명령은 이름공간을 쓰므로, 문서에 나온 /plugin-name:skill 형식으로 호출하는지도 점검하세요.

CI에서 권한 오류가 나면, 토큰을 새로 복사하기보다 워크플로의 권한, GitHub App 설치 상태, Secrets 이름, 실행 주체의 저장소 접근 권한을 순서대로 확인합니다. 공식 GitHub Actions 문서는 자동 실행에서도 필요한 도구와 권한을 명시해야 한다고 설명합니다.

결과가 너무 넓거나 일관되지 않다면, 모델을 바꾸기 전에 스킬의 입력 범위와 산출물 형식을 좁힙니다. “전체 코드 품질을 평가” 대신 “이번 PR에서 외부에 노출되는 함수의 변경과 근거 파일을 표로 제시”처럼 검토 단위를 고정하면 사람이 확인하기도 쉬워집니다.

팀에 공유할 때: 파일 복사보다 버전과 배포 경로부터

README에 설치 방법, 호출 이름, 필요한 권한, 지원하는 저장소와 제외 대상을 기록합니다. 팀 내부 배포라면 공식 문서의 비공개 저장소 기반 마켓플레이스 방식을 검토하고, 소수의 팀원이 먼저 같은 버전으로 확인하게 하세요. 버전을 올릴 때는 변경 이유와 이전 버전으로 돌아갈 기준도 남깁니다. 출처를 확인하지 않은 플러그인은 훅이나 외부 도구 연결을 포함할 수 있으므로 이름이나 설치 수만 보고 신뢰하지 않습니다.

배포 전에 확인할 체크리스트

• 플러그인의 목적과 대상 저장소가 README에 한 문장으로 적혀 있는가
• 필요한 도구와 권한이 최소화되어 있는가
• 비밀값과 개인·고객 데이터가 파일이나 예시에 들어가지 않았는가
• 로컬 시험에서 보고 형식, 제외 범위, 실패 시 동작을 검토했는가
• 버전 태그와 변경 기록을 남겨 어느 저장소가 어떤 구성을 쓰는지 추적할 수 있는가

플러그인은 더 많은 기능을 넣는 상자가 아니라, 검증된 작업 절차를 안전하게 재사용하는 배포 단위입니다. 먼저 한 프로젝트에서 규칙을 작게 검증하고, 필요한 권한과 완료 기준을 문서화한 뒤 공유 플러그인으로 옮기면 팀 자동화가 개인 설정의 복사본으로 흩어지는 문제를 줄일 수 있습니다.

관련 글: Diagram Design 설치·활용 가이드에서는 외부 스킬을 활용하는 흐름을 확인할 수 있습니다. 이번 글은 직접 만든 절차를 공유 가능한 플러그인으로 묶는 데 초점을 맞췄습니다.

공식 자료와 확인일

• Anthropic, Claude Code plugins
• Anthropic, Claude Code GitHub Actions
• Anthropic, Claude Code settings

자료 확인일: 2026년 9월 17일