Claude Code Plugin 만드는 방법: Skills·Hooks·MCP 한 번에 설정하기

Claude Code Plugin은 따로 관리하던 Skills, Hooks, Subagent와 MCP 서버 설정을 하나의 설치 가능한 디렉터리로 묶는 방식입니다. 여러 저장소에서 같은 리뷰 절차와 자동 검사를 사용하거나 팀에 표준 개발 도구를 배포할 때 유용합니다. 다만 Plugin에는 자동 실행 명령과 외부 시스템 권한이 함께 들어갈 수 있으므로 기능을 합치는 것만큼 검증·버전·폐기 절차가 중요합니다.

Claude Code Plugin이란 무엇인가

Plugin은 Claude Code의 확장 구성 요소를 하나의 자체 완결된 폴더로 포장한 배포 단위입니다. 반복 지침은 Skills, 이벤트 자동화는 Hooks, 외부 도구 연결은 MCP, 전문 역할은 agents에 넣고 동일한 버전으로 관리할 수 있습니다. 설치된 Plugin의 Skill은 /plugin-name:skill-name처럼 namespace가 붙어 다른 Plugin과 이름 충돌을 줄입니다.

한 프로젝트에서만 빠르게 쓸 설정은 독립된 .claude/ 구성이 단순합니다. 여러 저장소와 팀에 같은 기능을 설치하고 업데이트해야 한다면 Plugin이 적합합니다.

독립 설정과 Plugin 중 무엇을 선택할까

Skills·Hooks·MCP를 함께 묶는 이유

• Skills: 팀의 코드 리뷰, 장애 분석과 릴리스 절차를 재사용합니다.
• Hooks: 파일 수정이나 작업 종료 시 포맷·검사를 자동 실행합니다.
• MCP: 이슈·문서·모니터링처럼 외부 문맥을 안전한 도구로 연결합니다.
• agents: 보안 리뷰어나 테스트 분석가처럼 전문 역할을 제공합니다.

예를 들어 하나의 품질 Plugin이 “변경 검토 Skill”, “파일 수정 후 lint Hook”, “내부 코딩 표준 MCP”를 함께 제공할 수 있습니다. 각 기능의 책임은 분리하면서 설치와 버전은 하나로 관리하는 구조입니다.

완성할 Plugin 폴더 구조

quality-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── review-change/
│       ├── SKILL.md
│       └── checklist.md
├── hooks/
│   └── hooks.json
├── scripts/
│   └── check-file.sh
├── server/
│   └── index.js
├── .mcp.json
└── README.md

가장 흔한 실수는 skills/, hooks/와 agents/를 .claude-plugin/ 아래에 넣는 것입니다. 공식 기본 구조에서는 .claude-plugin/ 안에 plugin.json만 두고 모든 컴포넌트 디렉터리는 Plugin 루트에 둡니다.

1단계: Plugin 디렉터리 만들기

mkdir -p quality-tools/.claude-plugin
mkdir -p quality-tools/skills/review-change
mkdir -p quality-tools/hooks
mkdir -p quality-tools/scripts
mkdir -p quality-tools/server

학습용 Plugin은 현재 프로젝트 밖 별도 폴더에서 시작해도 됩니다. 배포할 계획이라면 처음부터 독립 Git 저장소나 Marketplace 저장소 안의 plugins 디렉터리에서 변경 이력과 보안 리뷰를 관리하세요.

2단계: plugin.json manifest 작성하기

{
  "name": "quality-tools",
  "description": "팀 코드 변경 검토와 자동 검사를 제공하는 개발 Plugin",
  "version": "1.0.0",
  "author": {
    "name": "Example Development Team"
  }
}

name은 Plugin 식별자이자 Skill namespace입니다. 짧고 고유한 소문자 이름을 사용하고, description에는 사용자가 설치 전에 기능과 권한 범위를 이해할 수 있도록 적으세요. version을 manifest에 명시했다면 기능을 배포할 때 버전도 올려야 사용자가 업데이트를 구분할 수 있습니다.

plugin.json 주요 필드

본문 예시는 최소 구성이며 공개 배포라면 README, 변경 기록, 라이선스, 지원 버전과 보안 연락처도 함께 제공하는 편이 좋습니다.

3단계: Plugin에 Skill 추가하기

quality-tools/skills/review-change/SKILL.md를 만듭니다.

---
name: review-change
description: 현재 코드 변경에서 회귀, 테스트 누락과 호환성 위험을 검토할 때 사용합니다.
---

1. 변경 목적과 파일 범위를 확인한다.
2. 공개 API, 데이터와 권한 영향을 검토한다.
3. 정상·오류·경계 조건 테스트를 확인한다.
4. 근거가 있는 문제만 파일 경로와 함께 보고한다.

결과에는 변경 요약, 우선순위별 위험, 테스트 누락과 미확인 항목을 포함한다.

Plugin 이름이 quality-tools라면 직접 호출 명령은 /quality-tools:review-change가 됩니다. 자세한 Skill 설계와 호출 테스트는 Claude Code Skills 만들기에서 확인할 수 있습니다.

4단계: Plugin에 Hook 추가하기

quality-tools/hooks/hooks.json에 이벤트와 실행 스크립트를 정의합니다.

{
  "description": "파일 수정 후 프로젝트 검사를 실행합니다.",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/check-file.sh",
            "args": [],
            "timeout": 30
          }
        ]
      }
    ]
  }
}

${CLAUDE_PLUGIN_ROOT}를 사용하면 Plugin이 사용자 캐시의 어느 위치에 설치돼도 포함된 스크립트를 찾을 수 있습니다. 절대 경로나 Plugin 밖의 ../shared 파일에 의존하면 설치 후 복사되는 캐시 구조에서 실패할 수 있습니다.

Hook 스크립트 작성 시 지킬 기준

• 표준 입력의 이벤트 JSON을 검증한 뒤 필요한 값만 읽습니다.
• 파일 경로를 셸 문자열에 그대로 이어 붙이지 않습니다.
• 검사할 확장자와 프로젝트 루트 범위를 제한합니다.
• 명확한 성공·실패 종료 코드와 제한 시간을 둡니다.
• stdout의 구조화 출력과 stderr 진단 메시지를 구분합니다.
• 비밀값, 소스 전문과 고객 데이터를 로그로 남기지 않습니다.

Hook은 Plugin 설치 즉시 특정 이벤트에 반응할 수 있으므로 Skills보다 더 엄격한 검토가 필요합니다. 자세한 이벤트와 실패 처리법은 Claude Code Hooks 사용법을 참고하세요.

5단계: Plugin에 MCP 서버 추가하기

Plugin 루트의 .mcp.json에 포함된 로컬 서버를 정의할 수 있습니다.

{
  "mcpServers": {
    "quality-data": {
      "type": "stdio",
      "command": "node",
      "args": [
        "${CLAUDE_PLUGIN_ROOT}/server/index.js"
      ]
    }
  }
}

서버 코드, 의존성, 환경 변수와 제공 도구가 모두 Plugin의 보안 범위에 들어갑니다. 토큰을 .mcp.json이나 JavaScript 파일에 넣지 말고 사용자 환경 또는 승인된 비밀 관리 방식으로 전달하세요.

원격 MCP 서버를 포함할 때

원격 HTTP 서버를 연결한다면 URL 소유자, TLS, OAuth scope, 읽기·쓰기 도구와 데이터 보존 정책을 문서화해야 합니다. Plugin 설치만으로 고위험 도구를 자동 허용하지 말고 Claude Code 권한과 조직 관리 정책을 유지하세요.

MCP 서버의 상세 설정과 오류 해결은 Claude Code MCP 서버 설정 가이드에서 확인할 수 있습니다.

Skills·Hooks·MCP가 함께 작동하는 흐름

1. 사용자가 /quality-tools:review-change Skill을 실행합니다.
2. Skill이 변경 범위와 리뷰 체크리스트를 확인합니다.
3. 필요한 경우 MCP의 읽기 전용 도구로 내부 표준을 조회합니다.
4. Claude가 파일을 수정하면 PostToolUse Hook이 검사를 실행합니다.
5. Skill은 검사 결과, 남은 위험과 실행하지 못한 항목을 보고합니다.
6. 사용자가 최종 diff와 외부 쓰기 동작을 승인합니다.

한 Plugin 안에 있다는 이유로 세 기능을 항상 동시에 실행할 필요는 없습니다. Skill은 필요할 때 불러오고 Hook은 이벤트 범위를 좁히며 MCP는 최소 도구만 제공해야 사용량과 위험을 통제할 수 있습니다.

로컬에서 Plugin 불러오기

claude --plugin-dir ./quality-tools

--plugin-dir은 Marketplace 설치 없이 현재 세션에서 Plugin을 직접 테스트합니다. ZIP으로 포장한 Plugin도 로컬 경로로 불러올 수 있습니다. 같은 이름의 설치된 Marketplace Plugin이 있어도 일반적으로 이 세션에서는 로컬 복사본을 우선 시험할 수 있지만 관리형 정책은 별도로 적용됩니다.

개발 중 변경사항 다시 불러오기

/reload-plugins

Plugin을 수정한 뒤 Claude Code 안에서 이 명령을 실행하면 Skills, agents, Hooks와 Plugin MCP 서버를 다시 불러올 수 있습니다. 다시 로드됐다는 메시지만 믿지 말고 각 구성 요소의 실제 동작을 반복 검사하세요.

Plugin 유효성 검사하기

claude plugin validate ./quality-tools --strict

validate는 manifest, Skill frontmatter와 Hook JSON 등 알려진 스키마 문제를 찾는 데 유용합니다. --strict는 경고도 실패로 취급해 배포 전 놓치기 쉬운 문제를 줄입니다. 다만 검증 통과가 스크립트의 안전성, 외부 서버의 신뢰성이나 업무 결과 품질까지 보증하지는 않습니다.

구성 요소별 테스트 순서

Plugin이 로드되지 않을 때

• skills/와 hooks/가 Plugin 루트에 있는지 확인합니다.
• .claude-plugin/plugin.json의 JSON 문법과 name을 검사합니다.
• Skill 폴더 안에 정확한 SKILL.md가 있는지 봅니다.
• Hook 스크립트가 존재하고 실행 권한이 있는지 확인합니다.
• MCP 경로에 ${CLAUDE_PLUGIN_ROOT}가 적용됐는지 봅니다.
• claude --debug와 Plugin 관리자의 Errors 탭에서 로딩 기록을 확인합니다.
• /reload-plugins 후 같은 대표 작업을 다시 실행합니다.

Skills는 보이지만 Hooks가 실행되지 않을 때

Skills와 Hooks는 별도로 로드되므로 Skill 성공이 Hook 설정 정상까지 뜻하지 않습니다. hooks/hooks.json의 최상위 hooks, 이벤트 이름, matcher와 script 경로를 확인하세요. Hook 명령의 작업 디렉터리를 가정하지 말고 Plugin 파일은 ${CLAUDE_PLUGIN_ROOT} 기준으로 찾는 편이 안전합니다.

MCP 도구가 나타나지 않을 때

1. .mcp.json이 Plugin 루트에 있는지 확인합니다.
2. server command와 args를 터미널에서 별도로 점검합니다.
3. Node·Python 등 필요한 런타임이 설치됐는지 봅니다.
4. /mcp에서 연결·인증·노출 도구 수를 확인합니다.
5. claude --debug의 MCP 초기화 오류와 제한 시간을 확인합니다.

Plugin 캐시와 경로 문제 이해하기

Marketplace에서 설치한 Plugin은 사용자 캐시 위치로 복사됩니다. 따라서 원본 저장소의 상위 디렉터리나 Plugin 밖 파일을 상대 경로로 참조하면 설치본에서는 존재하지 않을 수 있습니다. 실행에 필요한 스크립트·설정·템플릿은 Plugin 안에 포함하고 ${CLAUDE_PLUGIN_ROOT}를 사용하세요.

절대 경로는 제작자 컴퓨터에서만 작동할 가능성이 높습니다. 운영체제와 셸 차이도 있으므로 최소 두 환경 또는 팀원의 깨끗한 계정에서 설치 테스트를 진행하는 편이 좋습니다.

버전 관리와 변경 기록

• 기능 추가, 호환성 변경과 보안 수정에 맞춰 version을 갱신합니다.
• README에 지원 Claude Code 버전과 런타임 요구사항을 적습니다.
• CHANGELOG에 Skills·Hooks·MCP별 영향을 구분합니다.
• 새 권한, 네트워크 목적지와 외부 쓰기는 눈에 띄게 알립니다.
• 되돌릴 수 있는 이전 버전과 제거 절차를 유지합니다.

팀에 배포하는 Marketplace 기본 구조

Plugin을 여러 사람에게 설치하게 하려면 Marketplace 카탈로그를 사용할 수 있습니다.

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── quality-tools/
        ├── .claude-plugin/plugin.json
        ├── skills/
        ├── hooks/
        └── .mcp.json

로컬 Marketplace를 추가하고 Plugin을 설치하는 기본 흐름은 다음과 같습니다.

/plugin marketplace add ./my-marketplace
/plugin install quality-tools@my-plugins

Marketplace는 배포 편의를 제공하지만 안전성을 자동 보증하지 않습니다. private 저장소를 쓰더라도 변경 승인, 버전 고정과 공급망 검토가 필요합니다.

Plugin 보안 체크리스트

• manifest의 제작자·저장소·버전과 실제 소스가 일치하는가
• 모든 SKILL.md의 동적 명령과 지원 스크립트를 읽었는가
• Hooks가 언제 어떤 사용자 권한으로 실행되는가
• MCP 서버가 전송·저장하는 데이터와 제공 도구가 명확한가
• 토큰·API 키·개인 경로가 Plugin 파일에 포함되지 않았는가
• 삭제·배포·외부 쓰기에 사람 승인과 감사 기록이 있는가
• 업데이트에서 새 권한과 네트워크 목적지를 비교했는가
• Plugin 제거 후 프로세스·토큰·Hook·설정이 남지 않는가

배포 전 최종 점검

1. claude plugin validate ./quality-tools --strict를 통과합니다.
2. 깨끗한 테스트 프로젝트에서 --plugin-dir로 실행합니다.
3. Skill의 정상·오류·비호출 조건을 확인합니다.
4. Hook의 성공·실패·시간 초과와 중복 실행을 시험합니다.
5. MCP의 연결·인증·읽기·쓰기 권한을 구분합니다.
6. README의 설치·업데이트·제거 절차를 다른 팀원이 재현합니다.
7. 외부 코드와 데이터 흐름을 보안 담당자 또는 독립 리뷰어가 검토합니다.

깨끗한 환경 설치 기록표

제작자 컴퓨터에서만 동작하는 Plugin을 배포하지 않도록 새 계정 또는 격리된 테스트 환경에서 다음 결과를 기록하세요.

편집부 결론

Claude Code Plugin의 장점은 Skills, Hooks와 MCP를 한 폴더에 넣는 데 그치지 않고 개발 절차·자동 검사·외부 도구를 같은 버전과 검증 과정으로 배포하는 데 있습니다. 처음에는 Skill 하나로 Plugin 구조를 확인하고, Hook과 읽기 전용 MCP를 차례로 추가하세요. 구성 요소마다 권한과 실패 방식이 다르므로 개별 테스트를 통과한 뒤 통합 흐름을 검증해야 합니다.

이 글은 2026년 9월 6일 Anthropic 공식 문서를 분석해 작성했으며 예제 Plugin을 실제 조직 Marketplace에서 장기간 운영한 성과 보고는 아닙니다. Plugin 구성 요소와 검증 명령은 업데이트될 수 있으므로 배포 전 현재 Claude Code 버전과 공식 레퍼런스를 확인하세요.

공식 문서와 함께 읽을 글

Claude Code Plugin 제작 공식 문서 보기

Plugin manifest·컴포넌트 레퍼런스 확인하기

Plugin Marketplace 배포 방법 보기

Hooks와 MCP를 연결한 개발 자동화 구성하기

Claude Code Skills 세부 제작법 확인하기

Claude Code Hooks 이벤트 설정하기

Claude Code MCP 외부 도구 연결하기

Claude Code Subagent를 Plugin 역할로 구성하기

자주 묻는 질문

Claude Code Plugin은 무엇인가요?

Skills, Hooks, Subagent, MCP 서버와 기타 확장을 하나의 자체 완결된 디렉터리로 묶어 설치·공유·업데이트하는 단위입니다.

plugin.json은 어디에 만들어야 하나요?

Plugin 루트의 .claude-plugin/plugin.json에 만듭니다. skills, hooks와 agents 디렉터리는 .claude-plugin 안이 아니라 Plugin 루트에 둬야 합니다.

Plugin의 Skill은 어떻게 실행하나요?

/plugin-name:skill-name 형식으로 실행합니다. namespace가 적용되어 다른 Plugin의 같은 Skill 이름과 충돌하는 것을 줄입니다.

설치하지 않고 Plugin을 테스트할 수 있나요?

claude --plugin-dir ./plugin-path로 현재 세션에서 로컬 Plugin을 불러올 수 있습니다. 변경 후 /reload-plugins로 다시 로드하세요.

Claude Code Plugin을 어떻게 검증하나요?

claude plugin validate ./plugin-path --strict로 구조와 스키마를 검사하고 Skill, Hook, MCP와 통합 작업을 각각 별도로 시험해야 합니다.

Plugin Hook에서 포함된 스크립트 경로는 어떻게 지정하나요?

${CLAUDE_PLUGIN_ROOT}를 기준으로 지정합니다. 설치 시 Plugin이 캐시로 복사될 수 있어 제작자 컴퓨터의 절대 경로나 외부 상대 경로는 실패할 수 있습니다.

Plugin 안에 API 키를 넣어도 되나요?

안 됩니다. Plugin 파일과 Marketplace 저장소에 노출될 수 있으므로 사용자 환경 또는 조직의 승인된 비밀 관리 도구에서 전달하고 최소 권한과 만료를 적용하세요.

팀에 Plugin을 배포하려면 어떻게 하나요?

Marketplace의 marketplace.json에 Plugin을 등록하고 팀원이 Marketplace를 추가한 뒤 /plugin install 이름@마켓이름으로 설치할 수 있습니다. private 저장소에서도 독립 보안 검토가 필요합니다.