클로드 코드(Claude Code) 플러그인 사용법, 만들기부터 첫 실행까지

새 폴더에 파일 두 개만 만든 뒤 claude plugin validate로 검사하면 0.6초 만에 '경고와 함께 통과'가 나옵니다. 이어서 --plugin-dir로 불러와 /hello-plugin:hello를 실행하는 데는 6.7초가 걸렸죠. claude code plugin을 처음 만들어 보려는 1인 개발자라도 마켓플레이스 없이 바로 시험할 수 있습니다. 클로드 코드(Claude Code) 2.1.309에서 이 과정을 한 번씩 실행한 기록을 순서대로 따라가 보겠습니다.

클로드 코드 플러그인 사용법, 순서부터

직접 만들어 불러오는 순서는 다섯 단계입니다. 각 단계의 명령과 출력은 아래 절에서 하나씩 보여 드릴게요.

1. claude --version으로 버전을 확인합니다.
2. 플러그인 폴더를 만들고 .claude-plugin/plugin.json에 이름·설명·버전을 적습니다.
3. commands/hello.md에 슬래시 명령을 넣습니다.
4. claude plugin validate ./hello-plugin으로 검사합니다.
5. --plugin-dir ./hello-plugin으로 그 실행에만 불러와 /hello-plugin:hello를 실행합니다.

1~3단계는 각각 0.0초, 검사는 0.6초, 불러와 실행하기는 6.7초였고 종료 코드는 모두 0이었습니다. 설치 단계가 없으니 플러그인을 고친 뒤 다시 불러 보기도 쉽습니다.

도식출처: 직접 실행한 순서

함께 읽을 글

• 파이썬(Python) 설치 방법, 맥에서 첫 코드 실행까지 직접 해 보니
• 클로드 코드(Claude Code) 로그인 오류, 원인과 해결 순서
• 클로드 코드(Claude Code) 설치, npm과 설치 스크립트 직접 비교

플러그인 파일 두 개 만드는 방법

먼저 버전을 확인합니다. 이 글의 실행은 아래 버전에서 했습니다.

$ claude --version
2.1.309 (Claude Code)

다음은 플러그인 설명 파일(매니페스트)입니다. 매니페스트 레퍼런스에 따르면 매니페스트를 작성할 때 필수 키는 name입니다. 이 예제는 이름 외에 설명과 버전만 넣습니다.

$ mkdir -p hello-plugin/.claude-plugin hello-plugin/commands && printf '{\n  "name": "hello-plugin",\n  "description": "한국어로 짧게 인사하는 연습용 플러그인",\n  "version": "0.1.0"\n}\n' > hello-plugin/.claude-plugin/plugin.json && cat hello-plugin/.claude-plugin/plugin.json
{
  "name": "hello-plugin",
  "description": "한국어로 짧게 인사하는 연습용 플러그인",
  "version": "0.1.0"
}

그다음 슬래시 명령을 마크다운 파일 하나로 넣습니다. 머리말의 description은 명령 설명이고, 본문이 모델에게 주는 지시입니다.

$ printf -- '---\ndescription: 한국어로 짧게 인사합니다\n---\n\n사용자에게 한국어로 한 문장만 인사하고, 끝에 "(hello-plugin이 보낸 인사)"라고 붙이세요.\n' > hello-plugin/commands/hello.md && find hello-plugin -type f | sort && cat hello-plugin/commands/hello.md
hello-plugin/.claude-plugin/plugin.json
hello-plugin/commands/hello.md
---
description: 한국어로 짧게 인사합니다
---

사용자에게 한국어로 한 문장만 인사하고, 끝에 "(hello-plugin이 보낸 인사)"라고 붙이세요.

여기서 주의할 점이 있습니다. 문서는 매니페스트만 .claude-plugin/ 안에 두고, commands/·skills/·hooks/ 같은 나머지 파일은 플러그인 루트에 두라고 말합니다. 파일이 준비됐으니 이제 검사로 넘어가죠.

검사에서 나온 경고는 무슨 뜻일까요?

claude plugin validate는 문서가 매니페스트를 판정하는 기준으로 꼽는 명령입니다. 출력의 앞부분은 이렇습니다.

$ claude plugin validate ./hello-plugin
Validating plugin manifest: ./hello-plugin/.claude-plugin/plugin.json

⚠ Found 1 warning:

  ❯ author: No author information provided. Consider adding author details for plugin attribution

마지막 줄은 ✔ Validation passed with warnings였습니다. 그럼 경고가 있어도 쓸 수 있을까요? 문서 기준으로 이 결과는 매니페스트가 불러와지지만 고칠 거리가 있다는 뜻입니다. 그 사이에는 Anthropic 플러그인 디렉터리(제출용 목록)를 위한 점검이 따로 나옵니다.

출력은 이 디렉터리 점검이 최종 결과를 바꾸지 않는다고 밝힙니다. 제출 거절 사유에서 실패시키려면 --profile directory를 붙이라고 안내하고요. 아이콘은 SVG·WebP를 받지 않습니다. 또 개발자 포털에서 처음 저장하거나 제출할 때 한 번만 목록 아이콘이 될 수 있다고 하니, 공개할 생각이라면 처음부터 준비해 두는 편이 낫습니다. 디렉터리는 이 명령이 하지 않는 안전 검사와 정책 검토도 따로 합니다.

혼자 쓰는 플러그인이라면 이 경고들은 당장 막히는 문제는 아닙니다. 반대로 CI에서 경고까지 실패로 다루고 싶다면, 문서가 안내하는 --strict를 붙이면 됩니다.

불러와서 명령 실행하기

검사를 통과했으면 설치 없이 그 실행에만 불러옵니다. 문서도 개발 중에는 마켓플레이스 없이 폴더에서 바로 --plugin-dir로 불러오라고 안내합니다.

$ claude --plugin-dir ./hello-plugin --model opus -p "/hello-plugin:hello"
안녕하세요, 오늘도 즐거운 하루 보내세요! (hello-plugin이 보낸 인사)

명령 파일에 적은 대로 한 문장 인사 끝에 표시가 붙었고, 6.7초가 걸렸습니다. 그런데 왜 이름 앞에 hello-plugin:이 붙을까요? 문서는 플러그인의 모든 구성 요소가 name 아래에 묶인다고 설명합니다. 예를 들어 deploy-tools 플러그인의 about 명령은 /deploy-tools:about으로 실행됩니다. 그래서 이 플러그인의 정식 명령 이름은 /hello-plugin:hello입니다.

이름을 빼거나 플러그인 없이 부르면?

같은 인사를 세 가지로 불러 본 결과는 아래와 같습니다. 정식 이름 외의 두 결과는 모델이 그 입력을 어떻게 다뤘는지를 보여 주는 한 번의 기록일 뿐이고, 실행마다 달라질 수 있습니다.

이름만 부른 실행과 플러그인 없이 부른 실행의 출력은 이렇습니다.

$ claude --plugin-dir ./hello-plugin --model opus -p "/hello"
안녕하세요! 😊

이 세션에는 `/hello`라는 명령이 없어서 실행되지 않았어요. 플러그인 버전인 `/hello-plugin:hello`는 설치되어 있으니, 그 인사를 원하셨다면 이 이름으로 입력해 주세요.

무엇을 도와드릴까요?

$ claude --model opus -p "/hello-plugin:hello"
`/hello-plugin:hello` isn't installed in this session, so it didn't run. If you want to use it, you can add it as an organization plugin or as a project skill.

Hello anyway! What would you like to work on?

세 실행 모두 종료 코드는 0이었습니다. 그러니 스크립트에서 플러그인 명령을 부를 때 종료 코드만 보고 성공을 판단하면 안 됩니다. 출력에 기대한 표시가 있는지까지 확인하는 편이 안전해요. 시간 차이는 한 번씩만 잰 값이라 이 측정만으로는 원인을 가를 수 없습니다.

도식출처: 근거를 바탕으로 코드가 그린 도식

남이 만든 플러그인 설치하는 방법

직접 만들기 전에 이미 있는 것을 써 보고 싶다면 어떻게 할까요? 플러그인 개요에 따르면 터미널 세션에서 /plugin을 실행하고 Discover 탭에서 고르면 됩니다. 이 탭은 추가해 둔 마켓플레이스의 플러그인을 보여 줍니다.

• 공식 마켓플레이스: 대화형 터미널 세션을 처음 시작할 때 자동으로 추가됩니다(관리 정책이 막는 경우는 예외).
• 다른 마켓플레이스: /plugin marketplace add로 한 번 추가한 뒤, commit-commands@claude-plugins-official처럼 이름으로 설치합니다.
• 설치 범위: 사용자(이 컴퓨터의 모든 프로젝트), 프로젝트(커밋된 .claude/settings.json으로 저장소 전체), 로컬(나에게만, 이 저장소에서만) 중에서 고릅니다.
• 끄기: 지우지 않고 멈추려면 /plugin이나 셸의 claude plugin disable을 씁니다.

설치 전에 알아 둘 점도 있습니다. 켜진 플러그인은 쓰지 않는 세션에도 들어갑니다. 모델이 스스로 부를 수 있는 스킬·에이전트·명령은 이름과 설명이 매 턴 컨텍스트에 실리고, 그만큼 사용량에 잡힙니다. 또 플러그인은 내 권한으로 코드를 실행합니다. 혼자 여러 프로젝트를 돌린다면, 자주 쓰지 않는 플러그인은 사용자 범위로 켜 두기보다 필요한 프로젝트에서만 켜는 쪽이 낫다고 볼 수 있습니다.

자주 하는 실수와 점검 목록

• commands/ 폴더를 .claude-plugin/ 안에 넣는 실수: 매니페스트만 그 안에 두고 나머지는 루트에 둡니다.
• 이름 규칙: name은 kebab-case로 쓰고 공백·@·:·경로 구분자를 넣지 않습니다. claude-나 anthropic-로 시작하는 이름은 오류입니다.
• 접두사 없이 부르기: 플러그인 명령은 /플러그인이름:명령 꼴로 부릅니다.
• homepage 값: URL로 읽히지 않으면 플러그인이 불러와지지 않습니다.

마지막으로 아래를 확인해 보세요.

• 검사 결과가 Validation passed 또는 Validation passed with warnings인가
• 정식 이름으로 불렀을 때 명령 파일의 지시대로 출력되는가
• 디렉터리에 제출할 계획이라면 README·LICENSE·아이콘을 갖췄는가

측정 조건과 한계

모든 실행은 맥 한 대(darwin arm64, Node.js v22.23.1)의 Claude Code 2.1.309에서 했습니다. 로그인된 상태로 새 임시 폴더에서 명령을 적힌 차례대로 한 번씩만 실행했고, 모델은 --model opus로 고정했습니다. 플러그인은 설치하지 않고 --plugin-dir로만 불러왔습니다.

그래서 걸린 시간은 네트워크나 모델 응답에 따라 달라질 수 있는 한 번의 값입니다. 특히 /hello와 플러그인 없이 부른 답은 실행마다 다르게 나올 수 있습니다. 마켓플레이스 설치 과정은 이번에 실행하지 않았으니, 그 부분은 공식 문서 설명으로만 읽어 주세요.