[Claude] Claude Code(클로드 코드) 플러그인 만드는 법 - Skill 네임스페이스 분리하기

Claude Code의 Skill 기능은 이미 많은 사람이 쓰고 있다. .claude/skills/commit/SKILL.md를 만들어 놓고 /commit으로 잘 쓰고 있었다. Skill이 있으면 반복되는 프롬프트 복붙이 끝나니까 처음엔 이걸로 충분하다고 생각했다.

 

그런데 Skill이 쌓여갈수록 불편함을 느끼기 시작했다. 어떤 Skill이 어디서 온 건지 구분이 안 되고, 전부 전역으로 나열되니 한눈에 파악이 안 된다. 이 두 가지를 한 번에 해결해 주는 것이 플러그인이다.

 

결정적인 계기는 Claude Code의 플러그인 마켓플레이스였다. 거기서 /github:pr-review, /github:issue-search 같은 커맨드를 보고 "아, 저렇게 네임스페이스를 붙여서 쓸 수도 있구나" 하고 영감을 받았고 로컬에서도 이렇게 구분지으면 되구나 싶었다.

 

Skill만 쓰면 슬래시 커맨드가 전부 전역으로 쌓이지만, 플러그인으로 묶으면 아래처럼 /<플러그인>:<스킬> 형태로 자동 네임스페이싱이 된다.

/pr                     ← 전역 Skill (어디서 왔는지 모호)
/leevigong-dev:pr       ← 내 개인 플러그인의 PR Skill
/github:pr-review       ← 공식 마켓플레이스 플러그인 Skill

 

플러그인 구조

플러그인의 핵심 구성은 Plugin + Skill 이다. 파일 기준으로는 plugin.json 하나와 skills/ 디렉터리 하나면 된다.

레이어	파일/디렉터리	필수 여부	역할
Plugin	.claude-plugin/plugin.json	필수	설치 단위. "이 플러그인은 뭘 하는 건가"
Skill	skills/<name>/SKILL.md	필수	실행 단위. "이 상황에서 이렇게 행동한다"
Marketplace	.claude-plugin/marketplace.json	선택	배포 단위. 여러 명에게 공유할 때만 필요

 

혼자 쓰거나 로컬 테스트할 땐 --plugin-dir 플래그 하나면 충분하다. 마켓플레이스는 글 하단에서 따로 다룬다.

 

 

사용하고 있는 개인 플러그인 leevigong-dev의 파일 트리는 아래와 같다.

leevigong-dev/
├── .claude-plugin/
│   └── plugin.json              ← 플러그인 메타
└── skills/                      ← 스킬 모음
    ├── commit/SKILL.md
    ├── pr/SKILL.md
    ├── review/SKILL.md
    ├── refactor/SKILL.md
    ├── docs/SKILL.md
    └── changelog/SKILL.md

 

단일 디렉터리 하나가 곧 플러그인이다. 복잡한 중첩 구조는 없다.

파일 하나씩 뜯어보기

[ ① plugin.json ]

{
  "name": "leevigong-dev",
  "version": "1.0.0",
  "description": "개인 개발 워크플로우 자동화 플러그인",
  "author": { "name": "leevigong" }
}

name, version, description만 있으면 동작한다.

여기서 name이 바로 네임스페이스 접두사가 된다. leevigong-dev라고 하면 모든 Skill이 /leevigong-dev:<skill> 형태로 호출된다.

 

[ ② SKILL.md ]

Skill은 플러그인의 실제 기능이다. 원래 사용하던 Skill 파일 그대로다.

 

내가 쓰는 commit Skill 예시는 아래와 같다.

---
name: commit
description: Use when committing changes — analyzes modified files and creates
  logical commit units with Korean messages. Trigger on /commit or "커밋"
---

# Git Commit: $ARGUMENTS

## 핵심 원칙
**파일별/기능별로 논리적 단위로 분리해서 커밋해야 함!**
- 한 커밋에 관련 없는 변경사항 섞지 않기
- 각 커밋은 하나의 목적만 가져야 함

## 1. 현재 상태 분석
git status
git diff --stat
git log -3 --oneline

## 2. 변경사항 그룹핑
feat / fix / refactor / docs / test / chore 중 하나로 분류하고,
연관된 파일끼리 묶어 커밋 단위를 나눈다.

 

기존 Skill을 플러그인으로 전환하기

이미 .claude/skills/ 아래에 Skill이 몇 개 있다면, 파일만 옮기고 plugin.json만 얹으면 플러그인이 된다.

# Before (전역 Skill)              # After (플러그인)
.claude/                            leevigong-dev/
└── skills/                         ├── .claude-plugin/
    ├── commit/SKILL.md             │   └── plugin.json      ← 새로 작성
    ├── pr/SKILL.md                 └── skills/
    └── review/SKILL.md                 ├── commit/SKILL.md    ← 그대로 이동
                                        ├── pr/SKILL.md        ← 그대로 이동
                                        └── review/SKILL.md    ← 그대로 이동

 

SKILL.md 내용은 한 글자도 안 고쳐도 된다. frontmatter의 name, description도 그대로 쓴다. 달라지는 건 호출 방식뿐이다.

- Before: /commit
- After:  /leevigong-dev:commit

 

전환 순서 4단계

1. 플러그인 디렉터리 생성 + .claude-plugin/plugin.json 작성
2. 기존 .claude/skills/*를 플러그인 루트의 skills/로 이동
3. 터미널에서 claude --plugin-dir ./leevigong-dev로 Claude Code 실행
4. /leevigong-dev:commit 형태로 호출되는지 확인. 안 걸리면 description만 수정

 

결과

`/plugin` 명령어로 설치 목록을 열면 `leevigong-dev`가 뜬다.

Scope는 user, Status는 Enabled. 그리고 Description 자리에 plugin.json에서 적어뒀던 "개인 개발 워크플로우 자동화 플러그인" 문구가 그대로 올라와 있다.

 

내가 작성한 메타데이터가 Claude Code에 제대로 전달됐다는 뜻이다. 이제 `/leevigong-dev:commit`처럼 네임스페이스 붙은 커맨드를 어디서든 호출할 수 있다.

! 꿀 팁 !

1. SKILL.md 수정할 때마다 재시작하지 말고, /reload-plugins로 바로 반영하자.  
2. 처음 시작한다면 플러그인 구조부터 짜지 말고 .claude/skills/commit/SKILL.md 하나부터 만들어 쓰는 게 낫다. 2~3개쯤 실제로 쓰다 보면 그때 플러그인으로 묶어도 충분하다.

 

마켓플레이스 - 배포용

혼자 쓰는 것에서 그치지 않고 다른 사람에게 공유하기 위해서 마켓플레이스를 이용해야한다.

이는 공식 문서에서도 "배포용"이라고 명시한 별도 개념이다.

leevigong-plugins/
├── .claude-plugin/
│   └── marketplace.json         ← 카탈로그
└── plugins/
    └── leevigong-dev/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── ...

 

marketplace.json은 아래와 같이 "이 리포가 제공하는 플러그인 목록"을 선언한다.

{
  "name": "leevigong-plugins",
  "owner": { "name": "leevigong" },
  "plugins": [
    {
      "name": "leevigong-dev",
      "source": "./plugins/leevigong-dev",
      "description": "개인 개발 워크플로우 자동화 플러그인",
      "version": "1.0.0"
    }
  ]
}

 

이걸 GitHub에 올려 두면, 다른 사람이 /plugin install로 내 플러그인을 받아 쓸 수 있다. 마켓플레이스 구성·배포 전략은 공식 문서의 Plugin Marketplaces 페이지를 참고하자.

 

마무리

사실 플러그인에 담을 수 있는 건 Skill만이 아니다. agent, hook, MCP 서버까지 같이 넣을 수 있다. 이번 포스팅은 그중 Skill 네임스페이스 분리일 뿐이다. 구조가 이렇게 단순한 덕분에, 나머지 조각들도 같은 디렉터리 위에 하나씩 얹어가면 된다.

 

이미 Skill을 쓰고 있다면 오늘 당장 나만의 플러그인으로 전환해 볼 수 있다. 디렉터리 하나 만들고 plugin.json 쓰고 --plugin-dir로 돌려보면 끝이다.

 

참고

• Claude Code Plugins 가이드
• Plugins Reference
• Plugin Marketplaces