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

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

10분 만에 첫 플러그인 만들기

폴더 하나, 파일 두 개. 진짜 이게 전부야. 손 움직이는 실습편.

드디어 만드는 편이야. 겁먹을 필요 전혀 없어. 오늘 우리가 쓸 파일은 딱 두 개고, 둘 다 열 줄이 안 돼. 커피 한 잔 내리는 동안이면 끝나.

만들 것: 인사 플러그인

이름을 넣으면 인사해주는 스킬 하나짜리 플러그인이야. 쓸모? 없어. 근데 구조를 몸으로 익히는 게 목적이니까 일부러 제일 단순한 걸로 갈게. 여기서 뼈대만 잡히면 나머지는 살 붙이는 일이야.

1단계 — 폴더 만들기

아무 데나 만들어도 돼. 어차피 테스트할 때 경로를 직접 지정할 거거든. 작업 폴더나 임시 폴더 어디든 좋아.

mkdir my-first-plugin

💡 이후 명령어는 전부 my-first-plugin의 부모 폴더에서 실행한다고 생각하고 따라와. 경로가 my-first-plugin/...으로 나가거든.

2단계 — 매니페스트 만들기

매니페스트는 플러그인의 주민등록증이야. 이름이 뭔지, 뭐 하는 애인지, 버전이 몇인지를 적어두는 파일. 이게 있어야 플러그인 관리 화면에 제대로 표시돼.

mkdir my-first-plugin/.claude-plugin

그리고 그 안에 plugin.json을 만들어.

my-first-plugin/.claude-plugin/plugin.json

{
  "name": "my-first-plugin",
  "description": "기본기 익히는 인사 플러그인",
  "version": "1.0.0",
  "author": {
    "name": "내 이름"
  }
}

각 필드가 뭐 하는 앤지 짚고 갈게. 특히 version은 나중에 사고 나기 쉬운 부분이야.

필드	역할
name	고유 식별자이자 슬래시 접두어. 여기 적은 이름이 /my-first-plugin:hello의 앞부분이 돼
description	플러그인 관리 화면에 뜨는 설명
version	선택. 적어두면 이 값이 바뀔 때만 사용자한테 업데이트가 나가. 생략하고 git으로 배포하면 커밋 SHA가 버전 역할을 해서 커밋마다 새 버전이 돼
author	선택. 나중에 배포할 때 있으면 좋아

⚠️ version 함정 — "1.0.0"으로 박아두고 커밋만 계속 밀면, 이미 설치한 사람한테는 아무 업데이트도 안 나가. 클로드코드가 보기엔 같은 버전이거든. 릴리스할 때마다 올리든가, 아니면 아예 빼든가 둘 중 하나로 가야 해.

3단계 — 스킬 하나 넣기

스킬은 skills/ 폴더 안에 폴더 하나 = 스킬 하나 구조로 들어가. 그 폴더 안에 SKILL.md를 두면 끝이야.

mkdir -p my-first-plugin/skills/hello

my-first-plugin/skills/hello/SKILL.md

---
description: 사용자한테 반갑게 인사한다
disable-model-invocation: true
---

사용자에게 따뜻하게 인사하고, 오늘 뭘 도와줄까 물어봐.

보면 알겠지만 코딩이 아니라 글쓰기에 가까워. 위쪽 --- 사이는 설정이고, 아래는 그냥 평범한 지시문이야.

disable-model-invocation: true는 "클로드가 알아서 꺼내 쓰진 말고, 내가 슬래시로 부를 때만 나와"라는 뜻이야. 인사 같은 건 알아서 튀어나오면 성가시니까 걸어둔 거지. 이 옵션은 5편에서 더 자세히 다룰게.

💡 폴더 이름이 곧 스킬 이름 — hello/ 폴더를 만들었으니 스킬 이름이 hello가 돼. 플러그인 이름이랑 합쳐져서 /my-first-plugin:hello가 되는 거야.

4단계 — 테스트하기

설치할 필요 없어. --plugin-dir 플래그로 폴더를 직접 물려주면 돼.

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

클로드코드가 뜨면 바로 불러보자.

/my-first-plugin:hello

✓ 인사가 돌아왔다면 성공이야. /help를 쳐보면 플러그인 이름 밑에 스킬이 정리돼서 나올 거야. 축하해, 방금 플러그인 하나 만든 거야.

5단계 — 인자 받게 만들기

지금은 고정된 인사만 하니까 심심하지? $ARGUMENTS를 쓰면 스킬 이름 뒤에 붙인 텍스트가 그대로 들어와.

my-first-plugin/skills/hello/SKILL.md

---
description: 사용자한테 이름을 넣어 인사한다
disable-model-invocation: true
---

# Hello 스킬

"$ARGUMENTS" 라는 이름의 사용자에게 따뜻하게 인사하고,
오늘 뭘 도와줄까 물어봐. 인사는 개인적이고 기분 좋게.

disable-model-invocation은 아까 그대로 남겨뒀어. 이 스킬은 내가 슬래시로 부를 때만 나오면 되니까. 인자를 받든 안 받든 호출 방식이랑은 별개라서 이 줄은 건드릴 필요가 없어.

수정했으면 재시작할 필요 없이 이거 한 줄이면 반영돼.

/reload-plugins

이제 이름을 붙여서 불러보자.

/my-first-plugin:hello 상현

오늘의 핵심

매니페스트 하나 + SKILL.md 하나 = 플러그인.
테스트는 --plugin-dir, 수정 반영은 /reload-plugins.

보너스 — 사실 자동으로 만들어주는 명령어가 있어

지금 "이거 있었으면 처음부터 이걸로 하지" 싶을 텐데, 일부러 순서를 이렇게 잡았어. 손으로 한 번 만들어봐야 4편부터가 편해지거든. 어떤 파일이 어디 있는지 몸으로 알아야 문제가 생겼을 때 어디를 볼지 감이 오니까.

아무튼, 개발하는 동안 매번 --plugin-dir 붙이는 게 은근 번거로워. 이럴 땐 스킬 디렉터리에 플러그인을 두면 자동으로 로드돼. 스캐폴딩 명령어가 이걸 해줘.

claude plugin init my-tool

이러면 ~/.claude/skills/my-tool/에 매니페스트랑 시작용 SKILL.md가 생겨. 다음 세션부터 my-tool@skills-dir로 알아서 붙어. 마켓플레이스도, 설치도 필요 없어.

다음부터 새 플러그인 시작할 땐 이걸로 뼈대 잡고 시작하면 빨라. 대신 구조를 이해한 상태로 쓰는 거랑 모르고 쓰는 건 차이가 커.

정리하면 이 구조야

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json        # 주민등록증
└── skills/
    └── hello/
        └── SKILL.md       # 실제 능력

다음 편 예고 → 4편은 이 시리즈에서 사고가 제일 많이 나는 편이야. 폴더를 어디에 둬야 하는지 헷갈려서 "분명 만들었는데 안 뜬다"는 상황이 정말 자주 생기거든. 한 번 제대로 짚어두면 두 번 다시 안 헤매. 치트시트도 하나 만들어둘게.