클로드코드 플러그인(claude code plugin) 만들기 — 내 스킬을 배포 가능한 묶음으로

내가 만든 스킬과 에이전트를 하나로 묶어서 다른 컴퓨터나 다른 사람에게 /plugin install 한 줄로 설치되게 하는 방법이 클로드코드 플러그인 만들기입니다.

2026년 7월 기준, 플러그인은 .claude-plugin/plugin.json 파일 하나만 있으면 성립하고, 여기에 스킬·에이전트·명령어·훅을 담아 GitHub 저장소를 마켓플레이스로 공개하면 누구나 설치할 수 있습니다.

이 글을 끝까지 읽으면 최소 플러그인을 직접 만들어 로컬에서 테스트하고, 마켓플레이스로 배포하고, 업데이트를 내보내는 흐름까지 손에 익힐 수 있습니다.

플러그인은 스킬·에이전트·명령어를 하나로 묶어 배포하는 단위입니다. 폴더 하나에 .claude-plugin/plugin.json을 넣으면 플러그인이 되고, 그 폴더를 GitHub에 올려 마켓플레이스로 등록하면 다른 사람이 /plugin install 한 줄로 같은 도구 묶음을 씁니다.

왜 스킬을 플러그인으로 묶어 배포하는가

스킬이나 에이전트를 한두 개 만들어 쓰다 보면 곧 같은 고민에 부딪힙니다.

회사 노트북과 집 데스크톱에서 같은 스킬을 쓰려면 매번 파일을 복사해야 합니다.

팀원에게 "이 스킬 좋으니 써봐"라고 권해도, 설치 방법을 일일이 설명해줘야 합니다.

스킬을 고쳤을 때, 그걸 쓰던 사람들에게 새 버전을 어떻게 전달할지도 막막합니다.

플러그인은 이 세 가지를 한 번에 풉니다.

여러 컴포넌트를 하나의 묶음으로 배포하고, 버전으로 관리하고, 마켓플레이스를 통해 공유하는 구조이기 때문입니다.

개인적으로는 스킬을 두 개 이상 만들기 시작한 순간이 플러그인으로 넘어갈 신호라고 봅니다.

이 글은 클로드코드 생태계 연작의 마지막 편입니다. 앞선 claude-code-plugins-guide(플러그인 활용)에서 남이 만든 플러그인을 설치해 썼다면, 이번엔 내가 만드는 쪽으로 넘어갑니다.

플러그인 구조 — 폴더와 파일은 어디에 두는가

플러그인의 뼈대는 매니페스트 파일 하나입니다.

plugin.json은 반드시 플러그인 루트 아래 .claude-plugin/ 폴더 안에 둡니다.

여기에 흔히 걸리는 함정이 하나 있습니다.

스킬·에이전트·명령어·훅 폴더는 .claude-plugin/ 안에 넣으면 안 됩니다. 이들은 플러그인 루트에 바로 둬야 로드됩니다.

Claude Code 공식 문서도 이 실수를 "Common mistake"로 따로 경고합니다.

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json      ← 매니페스트만 여기
├── skills/              ← 나머지는 전부 루트에
│   └── hello/
│       └── SKILL.md
├── agents/
├── commands/
└── hooks/

각 폴더의 역할은 정해져 있습니다.

skills/는 스킬, agents/는 커스텀 에이전트, commands/는 평평한 마크다운 형태의 명령어, hooks/는 이벤트 핸들러(hooks.json)입니다.

참고로 새로 만드는 플러그인이라면 commands/보다 skills/를 쓰라고 공식 문서가 권장합니다.

매니페스트에 들어가는 필드는 아래 표로 정리했습니다.

필드	필수 여부	역할
name	필수	고유 식별자이자 스킬 네임스페이스. kebab-case 권장 (예: /my-plugin:hello)
description	권장	설치 화면(플러그인 매니저)에 표시되는 설명
version	선택	이 문자열을 바꿀 때만 사용자에게 업데이트가 나감. 생략하면 git 커밋 SHA가 버전 역할
author	선택	귀속용. name은 필수, email은 선택
homepage / repository / license / keywords	선택	문서 URL, 소스 저장소, SPDX 라이선스(MIT 등), 검색 키워드 배열

최소 플러그인 만들기 — 4단계

공식 quickstart를 따라가면 4단계로 첫 플러그인이 완성됩니다.

✅ 1단계, 폴더를 만듭니다.

반응형

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

✅ 2단계, 매니페스트를 작성합니다. my-first-plugin/.claude-plugin/plugin.json에 최소 내용만 넣습니다.

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

✅ 3단계, 스킬을 하나 넣습니다. my-first-plugin/skills/hello/SKILL.md를 만듭니다.

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today.

$ARGUMENTS는 사용자가 넘긴 입력이 들어가는 자리입니다.

✅ 4단계, 로컬에서 바로 테스트합니다. 설치 없이 폴더를 그대로 로드하는 방법이 가장 빠릅니다.

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

실행한 뒤 /my-first-plugin:hello로 호출하면 스킬이 동작합니다.

파일을 고쳤다면 /reload-plugins로 재시작 없이 반영할 수 있습니다.

⚠️ 스킬이 딱 하나라면 skills/ 폴더 없이 SKILL.md를 플러그인 루트에 바로 둬도 됩니다. 다만 스킬이 둘 이상으로 늘어날 낌새가 보이면 처음부터 skills/ 레이아웃으로 가는 편이 편합니다.

마켓플레이스로 배포하기 — GitHub 저장소 하나면 된다

플러그인을 남에게 나눠주려면 마켓플레이스가 필요합니다.

마켓플레이스는 저장소 루트의 .claude-plugin/marketplace.json 파일 하나로 정의됩니다.

필수 필드는 세 가지입니다. name(공개용 식별자), owner(name 필수), plugins(플러그인 배열)입니다.

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quality-review skill for quick code reviews"
    }
  ]
}

각 플러그인 엔트리는 최소 name과 source만 있으면 됩니다.

source가 상대경로일 때는 반드시 ./로 시작하고, 마켓플레이스 루트를 기준으로 삼습니다. ../로 바깥을 참조할 수는 없습니다.

GitHub로 공개하는 흐름은 단순합니다.

1) 마켓플레이스용 GitHub 저장소를 만들고, 2) .claude-plugin/marketplace.json에 플러그인을 정의하고, 3) 저장소를 공개합니다.

그러면 다른 사람은 이렇게 설치합니다.

/plugin marketplace add owner/repo
/plugin install quality-review-plugin@my-plugins

GitLab·Bitbucket·자체 호스팅 저장소도 전체 URL로 등록할 수 있습니다.

공식 플러그인 문서에서 스키마 원문을 확인하고 싶다면 아래 버튼으로 이동하세요.

728x90

📄 클로드코드 플러그인 공식 문서 바로가기 →

버전 관리와 업데이트는 어떻게 내보내는가

여기서 헷갈리는 사람이 가장 많습니다.

버전은 세 곳에서 순서대로 해석됩니다. 그중 먼저 값이 잡히는 것을 씁니다.

① plugin.json의 version → ② 마켓플레이스 엔트리의 version → ③ 소스의 git 커밋 SHA 순입니다.

함정은 version을 "1.0.0"처럼 고정해두는 경우입니다.

이 문자열을 안 바꾸면 새 커밋을 아무리 push해도 기존 사용자에게는 아무 일도 일어나지 않습니다. 버전이 같으니 캐시가 그대로 유지되는 것입니다.

그래서 두 가지 중 하나를 택합니다.

릴리스마다 version을 올리거나, 아예 생략해서 커밋 SHA가 버전을 맡게 하는 방법입니다.

⚠️ plugin.json과 마켓플레이스 엔트리 양쪽에 version을 동시에 두지 마세요. Claude Code는 경고 없이 plugin.json 값을 쓰기 때문에, 오래된 매니페스트가 마켓 버전을 가릴 수 있습니다.

사용자 쪽에서는 /plugin marketplace update로 새로고침합니다.

공개할 때의 책임 — 플러그인은 임의 코드 실행 권한이다

플러그인을 만드는 사람이 가장 무겁게 새겨야 할 대목입니다.

공식 문서는 이렇게 못 박습니다.

플러그인과 마켓플레이스는 사용자 권한으로 당신 컴퓨터에서 임의의 코드를 실행할 수 있는, 높은 신뢰가 필요한 컴포넌트입니다. 설치 화면도 "Anthropic은 플러그인에 어떤 MCP 서버·파일·소프트웨어가 들어있는지 통제하지 않는다"고 경고합니다.

이게 왜 무서운지 실제 사례가 있습니다.

Check Point Research가 공개한 CVE-2025-59536(CVSS 8.7)은, 신뢰 대화상자가 뜨기 전에 프로젝트 코드가 실행될 수 있던 결함입니다.

SessionStart 훅이 신뢰 확인 전에 먼저 실행되는 레이스 컨디션을 악용하면, 악성 저장소를 clone하거나 여는 것만으로 임의 셸 명령 실행과 API 키 탈취가 가능했습니다.

이 결함은 Claude Code 1.0.111에서 수정됐습니다. 자동 업데이트를 쓰는 사용자라면 이미 반영된 상태입니다.

공급망 보안 관점의 자세한 이야기는 ai-skill-supply-chain 편에서 다뤘습니다.

거기서 다룬 claude-seo 사례처럼, 유용한 척하며 몰래 기능을 심는 플러그인은 반면교사입니다.

만드는 쪽의 원칙은 단순합니다.

☐ 훅이 실행하는 명령을 README·SKILL 설명에 투명하게 밝힌다.

☐ 몰래 텔레메트리나 외부 전송을 넣지 않는다.

☐ 최소 권한만 요구한다.

개인적으로는 "이 플러그인이 사용자 몰래 뭘 하는가"라는 질문 앞에서 떳떳할 수 없다면 공개하지 않는 편이 맞다고 생각합니다.

실제로 만들어 쓰는 예 — humanize-korean 플러그인

이 블로그에는 직접 만들어 개인 마켓플레이스로 운용 중인 플러그인이 하나 있습니다.

이름은 humanize-korean, AI가 쓴 한글 글의 어색한 "AI 티"를 탐지해 자연스럽게 다듬는 도구입니다.

탐지 에이전트와 윤문 스킬을 하나로 묶어 플러그인으로 만들었습니다.

이렇게 만들어 두니, 어떤 프로젝트를 열든 /plugin install 한 줄이면 늘 같은 윤문 파이프라인을 씁니다.

실제로 이 블로그의 모든 글은 발행 전에 이 플러그인을 거쳐 문체를 다듬습니다.

핵심은 화려한 기능이 아닙니다.

반복해서 쓰던 스킬 묶음을, 여러 컴퓨터와 여러 프로젝트에서 똑같이 불러 쓸 수 있게 배포 형태로 굳혀둔 것뿐입니다.

스킬 만들기 자체가 궁금하다면 claude-code-skills-guide 편이 이 플러그인에 담긴 재료를 다룹니다.

자주 막히는 부분

플러그인을 처음 만들 때 걸리는 지점은 대체로 정해져 있습니다.

⚠️ 폴더를 잘못 두는 실수가 1위입니다. skills/·agents/·commands/·hooks/를 .claude-plugin/ 안에 넣으면 로드되지 않습니다. 매니페스트만 .claude-plugin/에, 나머지는 루트에 둡니다.

⚠️ 캐시 경로 함정도 흔합니다. 설치할 때 플러그인은 캐시로 복사되므로 ../shared-utils 같은 외부 참조가 풀리지 않습니다. 훅·MCP 경로는 상대경로 대신 ${CLAUDE_PLUGIN_ROOT} 변수를 씁니다.

⚠️ URL만 올린 마켓플레이스도 자주 막힙니다. marketplace.json만 URL로 제공하면 상대경로 source가 안 풀립니다. GitHub나 git 저장소로 통째로 호스팅하세요.

⚠️ 배포 전에는 검증 명령을 돌리는 습관을 들이면 좋습니다. claude plugin validate .가 JSON 스키마·중복 이름·경로 문제·frontmatter를 미리 잡아줍니다.

☐ 발행 전, 위 네 가지를 한 번씩 점검했는지 확인하세요.

연작을 마치며

여기까지가 클로드코드 생태계 5편의 마지막입니다.

지침(CLAUDE.md)으로 규칙을 정하고, 스킬로 반복 작업을 문서화하고, 에이전트로 역할을 나누고, 남의 플러그인을 설치해 쓰고, 이제 내 것을 만들어 배포하는 데까지 왔습니다.

순서대로 다시 짚으면 지침 → 스킬 → 에이전트 → 플러그인 활용 → 플러그인 만들기입니다.

처음엔 스킬 하나로 시작해도 충분합니다.

그게 쌓이면 자연스럽게 묶어서 배포하고 싶어지는 순간이 옵니다. 그때 이 글을 다시 펴면 됩니다.

 

 

참고한 자료

Claude Code 공식 문서 Create plugins(code.claude.com/docs/en/plugins), Create and distribute a plugin marketplace, Discover and install plugins(보안·설치)를 기준으로 정리했습니다. 훅 보안 사례는 Check Point Research의 CVE-2025-59536 공개 자료를, 실전 제작 흐름은 Dawid Nitka의 "Build Your Own Claude Code Marketplace"(DEV.to)를 참고했습니다. 플러그인 개수·최소 버전 등 빠르게 바뀌는 수치는 발행 시점 공식 카탈로그 확인이 필요합니다.