Claude Code 플러그인 만들기 — 스킬·훅·MCP를 하나로 묶어 배포하기

서브에이전트·훅·MCP 서버·슬래시 명령을 새 프로젝트마다 다시 복사해 붙이고 있다면, 그 설정은 계속 흩어지기만 합니다. 개인 .claude/ 폴더 안에만 있으면 팀원과 공유도 안 되고 버전 관리도 되지 않아, 누가 어떤 설정을 쓰는지조차 알 수 없게 됩니다.

서브에이전트부터 직접 만든 MCP 서버까지 하나씩 붙여 쓰다 보니, 결국 이걸 통째로 묶어 옮기는 문제에 부딪혔습니다. 10분 따라 하면 스킬·훅·MCP를 한 폴더에 묶어 /plugin install 한 줄로 배포하는 구조가 손에 잡힙니다.

1. 플러그인이 뭔가 — 지금까지 만든 걸 묶는 포장 계층

Claude Code 플러그인은 Claude Code를 확장하는 자기완결형 디렉터리입니다. 스킬·에이전트(서브에이전트)·훅·MCP 서버·LSP 서버·모니터를 한 폴더에 담아 프로젝트와 팀 사이에서 공유하고 버전으로 관리합니다.

 

앞선 글에서 만든 서브에이전트·훅·직접 만든 MCP 서버는 모두 .claude/ 안에 흩어져 있었습니다. 플러그인은 이 조각들을 하나로 묶는 포장 계층입니다. 새로 배우는 개념이라기보다, 이미 만든 것을 팀에 배포 가능한 형태로 감싸는 단계에 가깝습니다.

 

혼자 쓰는 standalone 설정과 플러그인의 차이는 이렇습니다.

항목	standalone (.claude/)	플러그인
스킬 이름	/hello	/플러그인명:hello (네임스페이스)
범위	단일 프로젝트·개인	여러 프로젝트·팀·커뮤니티
훅 위치	settings.json	hooks/hooks.json
공유	수동 복사	/plugin install로 설치

스킬 이름에 /플러그인명: 네임스페이스가 붙는 이유는 여러 플러그인을 깔았을 때 같은 스킬명이 충돌하지 않게 하기 위해서입니다. 혼자 단일 프로젝트에서 쓰는 명령 몇 개라면 .claude/로 충분합니다. 팀에 뿌리거나 버전 태그로 관리하기 시작할 때부터 플러그인으로 감싸면 됩니다.

2. 최소 플러그인 만들기 — 구조 + manifest + 스킬

Claude Code 플러그인의 루트 폴더 구조는 이렇게 나뉩니다.

위치 (플러그인 루트)	용도
.claude-plugin/plugin.json	manifest (이 폴더 안엔 이것만)
skills/<이름>/SKILL.md	스킬 (/플러그인:스킬)
agents/	커스텀 서브에이전트
hooks/hooks.json	훅
.mcp.json	MCP 서버 설정
commands/·.lsp.json·monitors/	(선택) 명령·LSP·모니터

핵심은 표 첫 줄에 있습니다. .claude-plugin/ 폴더 안에 들어가는 건 오직 plugin.json 하나이고, skills/·agents/·hooks/는 전부 그 위, 플러그인 루트에 둡니다. 여기서 한 번씩 다 넘어집니다.

증상: claude --plugin-dir로 붙였는데 /my-first-plugin:hello를 아무리 불러도 스킬이 안 뜹니다.

원인: skills/·commands/·hooks/를 .claude-plugin/ 안에 같이 몰아넣었습니다. 처음 만들 때 저도 폴더를 전부 .claude-plugin/ 밑으로 넣었다가 스킬이 안 잡혀 한참 헤맸습니다.

해결: .claude-plugin/에는 plugin.json만 남기고, skills/·agents/·hooks/를 루트로 꺼냅니다.

폴더를 만들고 manifest부터 씁니다.

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

.claude-plugin/plugin.json은 name만 필수이고 나머지는 선택입니다.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

version을 명시하면 사용자는 버전이 올라갈 때만 업데이트를 받습니다. 생략하면 git 커밋 SHA로 폴백해 커밋마다 새 버전으로 취급되니, 안정적으로 배포하려면 넣는 편이 낫습니다.

 

스킬은 skills/hello/SKILL.md에 frontmatter description:과 지시문을 씁니다. 폴더명이 곧 스킬명이라 /my-first-plugin:hello로 불립니다.

---
description: 이름을 받아 인사말을 돌려주는 스킬
---
$ARGUMENTS 님, 플러그인에 오신 걸 환영합니다.

$ARGUMENTS로 호출 시 넘긴 인자를 그대로 받습니다.

3. 컴포넌트 붙이기 — 훅·MCP·에이전트

이 단계는 새로 짜는 게 아니라, 앞서 만든 조각을 정해진 위치로 옮기는 작업입니다. 훅은 settings.json에 있던 hooks 객체를 그대로 hooks/hooks.json으로 옮깁니다. 형식이 같고, 경로만 ${CLAUDE_PLUGIN_ROOT}로 바꿉니다.

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh" }] }
    ]
  }
}

MCP 서버는 루트에 .mcp.json을 두고, 역시 경로에 ${CLAUDE_PLUGIN_ROOT}를 씁니다. 노션·GitHub 같은 외부 서버를 붙이는 MCP 서버 연동은 이전 글에서 다뤘고, 여기서는 그 서버 설정을 플러그인 안에 담는 방식입니다.

{ "mcpServers": { "plugin-database": {
  "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
  "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"] } } }

에이전트는 agents/에 정의 파일을 넣으면 /context의 Custom Agents 목록에 뜹니다. 서브에이전트를 플러그인으로 감싸면 팀 전체가 같은 역할 분리를 그대로 쓸 수 있습니다.

4. 테스트·설치·공유

만든 폴더는 설치 없이 바로 붙여 볼 수 있습니다.

claude --plugin-dir ./my-first-plugin

실행 후 /my-first-plugin:hello를 불러 동작을 확인합니다. 스킬이나 manifest를 수정했으면 세션을 껐다 켤 것 없이 /reload-plugins로 다시 적재하면 됩니다.

 

관리 화면은 /plugin(플러그인 매니저)이고, 설치는 /plugin install <이름>@<마켓플레이스> 형식입니다. 마켓플레이스는 세 갈래로 나뉩니다.

• 공식: claude-plugins-official. 처음 대화형으로 실행할 때 자동 등록됩니다.
• 커뮤니티: /plugin marketplace add anthropics/claude-plugins-community 후 @claude-community로 설치합니다.
• 팀 전용: private 레포에 마켓플레이스를 호스팅하면 사내에만 비공개로 배포됩니다.

제출 전에는 claude plugin validate로 구조를 검증합니다. 처음부터 손으로 폴더를 만들기 번거로우면 claude plugin init my-tool로 스캐폴딩하면 ~/.claude/skills/my-tool/에 manifest와 SKILL.md가 생기고 다음 세션에 my-tool@skills-dir로 자동 로드됩니다.

 

이미 .claude/에 쌓아둔 설정이 있다면 통째로 옮길 수 있습니다. commands/·agents/·skills/는 그대로 복사하고, 훅만 settings.json에서 hooks/hooks.json으로 옮기면 됩니다. 형식이 같아 내용은 손댈 게 없습니다.

마무리

정답은 하나가 아닙니다. 혼자 단일 프로젝트에서 명령 몇 개만 쓴다면 .claude/ standalone으로 충분하고, 플러그인은 오히려 폴더 구조만 늘립니다. 팀원과 공유하거나 버전으로 관리하기 시작하는 순간부터 Claude Code 플러그인으로 감싸면 됩니다. 서브에이전트·훅·MCP까지 만들어 왔다면, 마지막 포장 한 겹만 씌우는 셈입니다. 같은 구성이면 위 순서대로 옮겨도 무리 없습니다.

Q&A — 플러그인 만들 때 자주 막히는 것

Q. standalone .claude/ 설정이랑 뭐가 다른가요?
A. 범위와 공유 방식이 다릅니다. standalone은 단일 프로젝트·개인용이고 스킬이 /hello로 불립니다. Claude Code 플러그인은 여러 프로젝트·팀·커뮤니티가 대상이고 /플러그인명:hello 네임스페이스가 붙어 /plugin install로 설치·버전 관리됩니다.

Q. 기존 .claude 설정을 플러그인으로 옮기려면요?
A. commands/·agents/·skills/ 폴더는 플러그인 루트로 그대로 복사하고, 훅은 settings.json의 hooks 객체를 hooks/hooks.json으로 이동합니다. 두 훅 형식이 동일해 내용은 바꿀 필요가 없습니다.

Q. 팀에만 비공개로 공유하려면요?
A. private 레포에 마켓플레이스를 호스팅하면 됩니다. 공개 커뮤니티 마켓플레이스에 올리지 않고도 사내 구성원이 /plugin install로 설치할 수 있습니다.

Q. version은 꼭 명시해야 하나요?
A. 필수는 아닙니다. 다만 생략하면 git 커밋 SHA로 폴백해 커밋마다 새 버전으로 취급됩니다. 안정 배포가 목적이면 version을 명시해 버전을 올릴 때만 업데이트가 나가도록 하는 편이 낫습니다.

📎 함께 보면 좋은 Claude Code 확장 글

이 글의 플러그인이 아래 세 글에서 만든 조각을 하나로 묶습니다.

• Claude Code 서브에이전트 실전 배치 — 역할 분리부터 병렬 3~5개 스윗스팟까지 — 2026-07-06
• Claude Code Hooks 실전 — 포맷·위험 명령 차단·알림 자동화 5가지 — 2026-07-09
• MCP 서버 직접 만들기 — Claude Code에 내 도구 붙이기 — 2026-07-16

설치 환경: Windows 11, Node.js v24, Claude Code