클로드코드 플러그인 완전정복 · 1편

클로드코드 플러그인 완전정복 · 1편

내 클로드코드 세팅, 한 줄로 설치되게 만들자

스킬·에이전트·훅·MCP를 한 봉지로 묶는 플러그인 — 오늘은 개념만 편하게 잡아볼게.

혹시 이런 적 있어? 회사 노트북에서 열심히 세팅해둔 서브에이전트랑 슬래시 명령어들, 집 컴퓨터에서 다시 쓰려니까 폴더째 복사해서 옮기고 있는 나 자신. 아니면 팀원한테 "이거 좋아" 하고 알려주는데 설명이 열 줄 넘어가는 상황.

그거 해결하라고 나온 게 플러그인이야. 한마디로 내 클로드코드 세팅을 통째로 포장해서 배포하는 방법이지.

플러그인이 대체 뭔데?

지금까지 클로드코드를 확장하는 방법은 여러 갈래로 흩어져 있었어. 스킬은 .claude/skills/에, 서브에이전트는 .claude/agents/에, 훅은 settings.json 안에, MCP 서버는 또 따로. 각각은 잘 동작하는데 남한테 통째로 넘기기가 애매했지.

플러그인은 이걸 폴더 하나로 묶어. 그리고 그 폴더를 GitHub에 올려두면, 다른 사람은 이렇게만 하면 돼.

# 끝. 정말로 이게 다야
/plugin install my-tool@my-marketplace

스킬도, 에이전트도, 훅도, MCP 서버 연결까지 전부 한 번에 딸려와. 크롬 확장 프로그램 설치하는 느낌이랑 비슷하다고 보면 돼.

이 시리즈에서 딱 하나만 기억한다면

플러그인 = 스킬 + 에이전트 + 훅 + MCP를 담은 폴더 하나.
거기에 .claude-plugin/plugin.json 하나 넣으면 끝이야.

그냥 .claude/ 폴더 쓰면 안 돼?

돼. 오히려 혼자 쓸 거면 그게 더 편해. 근데 상황에 따라 갈려.

○ 단독 설정 (.claude/)

• 나 혼자, 이 프로젝트에서만 쓸 때
• 일단 만들어보고 실험할 때
• 이름이 짧아 — /hello
• 공유하려면 폴더 복사밖에 답이 없음

○ 플러그인

• 팀이나 커뮤니티에 뿌릴 때
• 여러 프로젝트에서 재사용할 때
• 버전 관리하고 업데이트 밀어줄 때
• 이름에 접두어가 붙어 — /my-plugin:hello

공식 문서 권장도 똑같아. 일단 .claude/에서 빠르게 만들어보고, 공유할 때가 되면 플러그인으로 옮기는 것. 처음부터 플러그인으로 시작할 필요 전혀 없어.

이름 앞에 접두어가 왜 붙지?

플러그인 스킬은 무조건 플러그인이름:스킬이름 형태로 불러야 해. 예를 들어 my-first-plugin이라는 플러그인 안에 hello 스킬이 있으면 이렇게 되지.

/my-first-plugin:hello

좀 길어서 귀찮게 느껴질 수 있는데, 이유가 있어. 플러그인을 여러 개 깔다 보면 이름이 겹치는 사고가 반드시 나거든. A 플러그인에도 review가 있고 B 플러그인에도 review가 있으면 누가 불려나올지 아무도 몰라. 접두어는 그걸 원천 차단하는 장치야.

💡 접두어 바꾸고 싶다면 — plugin.json의 name 필드가 그대로 접두어가 돼. 이름을 짧게 지으면 호출도 짧아져.

플러그인에 뭘 담을 수 있어?

생각보다 담을 게 많아. 이 시리즈에서 하나씩 다 다룰 건데, 미리 지도만 그려볼게.

담을 것	어디에	뭐 하는 애
스킬	skills/	클로드가 알아서 꺼내 쓰거나, 슬래시로 부르는 능력
서브에이전트	agents/	따로 일하는 전문 담당자
훅	hooks/hooks.json	특정 시점에 자동으로 끼어드는 스크립트
MCP 서버	.mcp.json	외부 서비스 연결 (Canva, Higgsfield 같은)
LSP 서버	.lsp.json	코드 지능 — 정의로 이동, 참조 찾기
백그라운드 모니터	monitors/	로그 감시하다가 이벤트 생기면 알려줌

이 중에 하나만 있어도 플러그인이 돼. 스킬 하나짜리 플러그인이 제일 흔하고, 실제로 쓸모도 많아.

앞으로 이런 순서로 갈게

• 1편 — 플러그인이 뭐길래. 지금 읽고 있는 이 글. 개념만 잡고 넘어가.
• 2편 — 남이 만든 거 먼저 써보기. 만들기 전에 설치부터. 감이 확 와.
• 3편 — 10분 만에 첫 플러그인. 진짜로 손 움직이는 편.
• 4편 — 디렉터리 구조 완전정복. 여기서 제일 많이 틀려. 꼭 봐야 해.
• 5편 — 서브에이전트 태우기. 기존에 만든 에이전트를 플러그인으로.
• 6편 — 훅이랑 MCP까지. 설치 한 번에 MCP까지 딸려오게 만들기.
• 7편 — 기존 설정 이사시키기. 흩어진 .claude/를 정리하는 편.
• 8편 — 마켓플레이스 배포. 내 GitHub 주소로 남들이 설치하게 만들기.

⚠️ 미리 알아둘 것 — 플러그인은 내 권한으로 임의 코드를 실행할 수 있어. npm 패키지 설치하는 거랑 위험도가 같다고 보면 돼. 남의 플러그인 깔 땐 출처를 꼭 확인하자. 이 얘기는 2편에서 자세히 할게.

다음 편 예고 → 2편에서는 만들기 전에 남이 만든 플러그인부터 깔아볼 거야. /plugin 명령어 하나면 공식 마켓플레이스가 통째로 열리거든. 직접 써보면 "아, 이런 걸 만들면 되는구나"가 훨씬 빨리 잡혀. 오늘은 "폴더 하나가 플러그인이다"만 챙겨가면 충분해.