클로드 플러그인 만들기: plugin-dev 리뷰, 깔아 두기만 하면 스킬이 한 번도 안 불렸다

팀이 같이 쓰는 명령이나 안전장치를 클로드 코드에 넣어 두려면 플러그인으로 묶어 나눠 주는 방법이 가장 깔끔합니다. plugin-dev(플러그인 개발)는 Anthropic 공식 플러그인 디렉터리에 있는 플러그인 제작 도구 묶음으로, 플러그인의 파일 배치·훅·명령·에이전트 만드는 법을 스킬로 안내합니다. 플러그인은 무료지만 쓸 때 클로드 사용량이 듭니다. 가상 카페 직원용 플러그인(메뉴 가격 조회 + .env 파일 차단)을 같은 요청으로 플러그인 없이, 깔아 두기만 하고, 명령으로 불러서 각 2번 만들게 하고, 만든 플러그인을 새 세션에 실제로 불러 채점했습니다.

플러그인은 스킬·명령·훅·MCP 서버를 한 폴더로 묶어 설치 한 번에 나눠 주는 꾸러미입니다. 스킬이 처음이라면 클로드 스킬 뜻과 만드는 법을 먼저 보세요.

결과부터 보기: 만든 플러그인을 새 세션에서 불러 본 장면

영상은 요청문, 만든 플러그인을 새 세션에 불러 가격을 묻고 .env를 열어 달라고 한 장면, 채점표, 점수 밖에서 갈린 검색 시험, 사용량 순서입니다.

직접 눌러 보기: 여섯 번이 만든 플러그인 파일 전문과 클로드의 답 열어 보기

따라 해 보기: 요청문과 실습 재료

플러그인을 만들 폴더에서 클로드 코드를 열고 아래처럼 요청하면 됩니다. 클로드 코드가 처음이라면 클로드 코드 설치 방법을 먼저 보세요. 실습 재료(zip)에는 가상 메뉴판(menu.csv), 가짜 .env, 요청문, 채점 기준, 명령 2회차가 만든 플러그인을 넣었습니다.

/plugin-dev:create-plugin 우리 <가게·팀> 직원들이 클로드 코드에서 같이 쓸 플러그인을 이 폴더의 <플러그인 이름>/ 폴더에 만들어 줘.
1. <기능 1, 예: 메뉴 이름을 넣으면 menu.csv에서 가격을 찾아 알려 주는 기능. /<플러그인 이름>:menu-price 아메리카노 처럼 부를 수 있어야 해.>
2. <기능 2, 예: 클로드가 .env 파일을 읽거나 고치려고 하면 막는 기능.>
다 만들면 제대로 동작하는지 확인하고, 다른 직원이 설치하는 방법도 알려 줘.

<…> 부분은 내 일에 맞게 바꿉니다. 맨 앞 /plugin-dev:create-plugin은 plugin-dev를 깔았을 때만 씁니다. 좋은 결과라면 plugin.json·skills/·hooks/hooks.json이 든 폴더와 claude plugin validate 통과 기록, 그리고 /plugin marketplace add로 시작하는 설치 안내가 나옵니다.

plugin-dev에 들어 있는 것

claude plugin details로 뽑은 구성입니다. 명령 create-plugin은 목록에서 스킬로 함께 셉니다. 훅·MCP 서버는 없습니다.

구성	언제 불리나·무엇을 하나 (SKILL.md·명령 파일 기준)	부를 때 분량
/plugin-dev:create-plugin	플러그인을 처음부터 만드는 8단계 순서. 목적 파악 → 구성 정하기 → 세부 설계 → 폴더 만들기 → 구현 → 검사 → 시험 → 설명서. 단계마다 질문하고 답을 기다리라고 적혀 있음	약 6.1k토큰
plugin-structure	“플러그인 만들어 줘”, “plugin.json 설정”에 불림. 폴더 배치, 매니페스트 칸, 자동 인식 규칙	약 5.1k토큰
hook-development	“훅 만들어 줘”, “위험한 명령 막기”에 불림. 훅 이벤트 종류, 막는 법(종료 코드 2·deny), 시험용 스크립트 3개	약 6.1k토큰
command-development · skill-development	슬래시 명령·스킬 만들기. 머리말(설명·인자·허용 도구), 잘 불리는 설명문 쓰는 법	약 7.2k·8.7k토큰
agent-development · mcp-integration · plugin-settings	서브에이전트, MCP 서버 연결, 프로젝트별 설정 파일(.local.md)	약 4.2k~4.7k토큰
에이전트 plugin-validator · skill-reviewer · agent-creator	플러그인 구조 검사, 스킬 설명문 검토, 에이전트 초안 만들기	약 1.9k~2.4k토큰

깔아 두면 스킬·에이전트 설명문 약 2,351토큰이 매 대화에 실립니다. 플러그인 만들 때만 켜 두는 편이 낫습니다.

1단계. 플러그인 깔기 (약 1분)

플러그인을 만들 폴더에서 터미널에 아래 명령을 실행합니다. claude-plugins-official은 클로드 코드에 처음부터 등록된 공식 플러그인 저장소이고, --scope local은 이 폴더에서만 켜는 옵션입니다.

claude plugin install plugin-dev@claude-plugins-official --scope local
claude plugin details plugin-dev@claude-plugins-official

이렇게 나오면 성공 ✔ Successfully installed plugin: plugin-dev@claude-plugins-official (scope: local)(플러그인 설치 성공, 범위: 이 폴더). 구성 목록에 Skills (8)과 Agents (3) agent-creator, skill-reviewer, plugin-validator가 나옵니다.

• 설치 명령이 플러그인을 찾지 못하면 claude plugin marketplace add anthropics/claude-plugins-official로 저장소를 등록한 뒤 다시 설치합니다.
• 클로드 앱에서는 디렉터리에서 설치합니다(공식 설명 기준, 디렉터리 여는 법). 이 글은 클로드 코드 터미널 기준입니다.

필요 없어지면 같은 폴더에서 아래 명령으로 지웁니다.

claude plugin uninstall plugin-dev@claude-plugins-official --scope local

2단계. 같은 요청으로 플러그인 만들게 하기 (약 2~5분)

이 단계에서는 같은 요청을 세 조건에서 보내 결과를 비교합니다. 재료는 가상 카페 메뉴판 6줄(menu.csv)과 가짜 키가 든 .env 파일입니다. 조건은 ① 플러그인 없이 ② plugin-dev를 깔아 두기만 ③ 요청 앞에 /plugin-dev:create-plugin을 붙여 부르기이고, 조건마다 2번씩 보냈습니다.

채점 기준 10개는 실행 전에 플러그인 매니페스트 공식 문서에서 뽑아 고정했고, 요청문에는 넣지 않았습니다. 만든 플러그인은 사본 폴더에서 claude -p --plugin-dir로 새 세션에 불러 가격을 묻고 .env를 열어 달라고 했습니다.

채점 항목	없이 1·2	깔아 두기만 1·2	명령 1·2
claude plugin validate 통과	✓ ✓	✓ ✓	✓ ✓
--strict(경고도 실패로 침) 통과	✓ ✓	✓ ✓	✓ ✓
plugin.json은 .claude-plugin/ 안, 스킬·훅은 플러그인 루트	✓ ✓	✓ ✓	✓ ✓
가격 기능을 skills/로 만듦(공식 문서가 새 플러그인에 권함)	✓ ✓	✓ ✗	✓ ✓
hooks.json이 최상위 “hooks” 감싸개 + PreToolUse	✓ ✓	✓ ✓	✓ ✓
훅 경로가 ${CLAUDE_PLUGIN_ROOT}이고 따옴표로 감쌈	✓ ✓	✓ ✓	✓ ✓
훅 스크립트 단독 시험: .env 읽기·고치기·쓰기는 막고 menu.csv는 통과	✓ ✓	✓ ✓	✓ ✓
새 세션에서 /cafe-helper:menu-price 카페라떼 → 5,000원	✓ ✓	✓ ✗	✓ ✓
새 세션에서 “.env 내용 보여 줘” → 훅이 막아 값이 안 나옴	✓ ✓	✓ ✓	✓ ✓
직원 설치용 marketplace.json이 공식 검사 통과	✓ ✓	✓ ✓	✓ ✓
합계(10점)	10 · 10	10 · 8	10 · 10

	① 플러그인 없이	② 깔아 두기만	③ 명령으로 부르기
부른 스킬·에이전트	1회차 내장 plugin-authoring 스킬 · 2회차 클로드 코드 안내 에이전트	없음 · 없음	hook-development · plugin-structure, hook-development + 검사 에이전트 2개
걸린 시간	3분쯤 · 4분쯤	3분쯤 · 2분이 안 걸림	3분쯤 · 5분쯤
사용량(API 단가)	0.96 · 1.03달러	0.97 · 0.65달러	0.97 · 1.94달러

여섯 번 모두 뼈대가 비슷했습니다. plugin.json, 가격을 찾는 스크립트, .env 이름이 보이면 막는 PreToolUse 훅, 직원 설치용 marketplace.json이 들어갔습니다. 플러그인 없이 한 1회차는 클로드 코드 내장 plugin-authoring 스킬을 불렀는데, 이 스킬은 클로드 화면·동작을 바꾸는 “모드” 만들기 안내입니다. 2회차는 스킬 없이 안내 에이전트만 한 번 부르고 10점이었습니다.

깔아 두기만 했을 때: 스킬 대신 파일 검색

깔아 두기만 한 두 번은 plugin-dev 스킬을 한 번도 부르지 않았습니다. 대신 설치된 플러그인 폴더를 Grep으로 검색해 ${CLAUDE_PLUGIN_ROOT} 쓰는 예시만 찾아봤습니다. 2회차는 가격 기능을 commands/에 만들었는데, 공식 문서는 새 플러그인에 skills/를 권합니다. plugin-dev의 command-development 스킬 머리에도 같은 메모가 있습니다.

2회차 명령 파일은 새 세션에서 빈 답을 냈습니다. 명령 안의 미리 실행 줄(!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/menu-price.sh" …`)이 같은 파일 머리말의 허용 도구 Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/menu-price.sh:*)와 맞지 않았기 때문입니다. 세션에서 bash를 따로 허용하면 “카페라떼는 5,000원이에요”라고 답했습니다. 명령 1회차는 스킬 머리말을 allowed-tools: Bash(bash:*)로 넓게 잡아 이 문제가 없었습니다.

점수 밖에서 갈린 한 곳: .env 검색 구멍

채점과 별도로 훅 스크립트에 입력을 더 넣어 봤습니다. 파일 이름 없이 폴더 전체를 검색하면 .env 안의 키가 검색 결과로 새어 나올 수 있습니다.

훅에 넣은 입력	없이 1·2	깔아 두기만 1·2	명령 1	명령 2
Read .env	막음 막음	막음 막음	막음	막음
Grep "POS_API"(경로·파일 지정 없이)	통과 통과	통과 통과	통과	막음
Bash grep -r POS_API .	통과 통과	통과 통과	통과	통과

명령 2회차만 직접 가짜 .env로 검색 구멍을 확인하고 막았습니다. 이 회차는 검사 에이전트(plugin-validator·skill-reviewer) 두 개의 지적을 받아 고쳤습니다. 39턴을 돌아 사용량도 1.94달러로 가장 많았습니다. Bash로 폴더 전체를 grep하거나 cat .e*처럼 이름을 숨기는 길은 여섯 모두 열려 있었습니다. 깔아 두기만 한 두 번을 뺀 네 번은 이런 한계를 답에서 먼저 밝혔습니다.

3단계. 만든 플러그인 검사하고 직접 불러 보기 (약 2분)

만든 폴더는 먼저 공식 검사 명령으로 확인합니다. 주의할 점이 하나 있습니다. .claude-plugin/ 안에 marketplace.json도 있으면 폴더를 넣었을 때 마켓플레이스 파일만 검사합니다. plugin.json은 경로를 직접 지정합니다.

claude plugin validate --strict ./cafe-helper/.claude-plugin/plugin.json

이렇게 나오면 성공 ✔ Validation passed(검사 통과). 여섯 번이 만든 plugin.json 모두 엄격 검사를 통과했습니다.

설치하기 전에는 아래처럼 폴더를 그대로 불러 시험합니다. 설치하지 않고 이 세션에서만 불러옵니다.

claude --plugin-dir ./cafe-helper

실행 기록 · <작업 폴더>/chk-cmd2 · claude -p –plugin-dir 새 세션 두 번의 답(원문 그대로)

요청: /cafe-helper:menu-price 카페라떼
카페라떼는 5,000원입니다 (커피).

요청: 이 폴더의 .env 파일 내용 그대로 보여 줘
`.env` 파일 내용은 보여 드릴 수 없었습니다. 읽으려고 했는데, 설치된 `cafe-helper` 플러그인의 훅이 막았습니다. 이 훅은 API 키나 비밀번호 같은 비밀 정보가 담긴 `.env` 파일을 Claude가 읽거나 수정하지 못하게 합니다.

• 명령이 목록에 안 보이면: 플러그인 폴더 이름이 아니라 plugin.json의 name이 명령 앞부분(/cafe-helper:)이 됩니다.
• 명령이 빈 답만 내면: 명령·스킬 머리말의 allowed-tools가 미리 실행 줄의 명령과 맞는지 봅니다(위 깔아 두기만 2회차 사례).
• 훅이 안 막으면: hooks/hooks.json이 {"hooks": {"PreToolUse": […]}}처럼 “hooks”로 한 번 감싸져 있는지 봅니다. 감싸개가 없으면 불러오지 못합니다(공식 문서).

직원에게 나눠 줄 때는 여섯 번 모두 같은 방법을 안내했습니다. 플러그인 폴더(또는 그 위 폴더)에 marketplace.json을 두고 GitHub 저장소나 공유 폴더에 올린 뒤, 직원은 클로드 코드에서 /plugin marketplace add <저장소 또는 폴더 경로>와 /plugin install cafe-helper@<마켓플레이스 이름>을 입력합니다.

이런 사람에게 권합니다

• ✅ 남에게 나눠 줄 플러그인을 처음 만드는 사람. 단, 깔아 두기만 하지 말고 /plugin-dev:create-plugin으로 부르세요. 이번에는 명령으로 불렀을 때만 스킬과 검사 에이전트가 움직였습니다.
• ✅ 훅·서브에이전트·MCP 서버를 함께 넣는 큰 플러그인을 만드는 사람. 구성마다 스킬과 시험용 스크립트가 따로 있습니다(공식 설명 기준).
• ❌ 명령 하나, 훅 하나짜리 작은 플러그인이 목적인 사람. 이번 과제에서는 플러그인 없이도 10점짜리가 두 번 나왔습니다.

한계와 주의할 점

• 기능 두 개짜리 작은 플러그인 하나로, 조건마다 두 번씩만 돌렸습니다. 에이전트·MCP 서버·설정 파일 같은 큰 구성은 시험하지 않았습니다.
• 실험은 claude -p(한 번에 끝나는 방식)로 했습니다. 명령 파일에는 단계마다 질문하고 답을 기다리라고 적혀 있지만, 이번 두 번은 질문 없이 끝까지 진행했습니다. 대화형으로 쓰면 질문이 더 나올 수 있습니다.
• 이번 실험 설정은 만드는 도중에 claude 명령으로 새 세션을 띄우는 것을 막았습니다. 그래서 여섯 번 모두 만든 플러그인을 직접 불러 보지는 못했고, 새 세션 시험은 채점하면서 따로 했습니다. 평소처럼 쓰면 클로드가 이 시험까지 해 볼 수 있습니다.
• plugin-dev 문서 일부는 공식 문서보다 뒤처져 있습니다. 훅 예시는 ${CLAUDE_PLUGIN_ROOT}를 따옴표 없이 쓰는데, 공식 문서는 경로에 빈칸이 있어도 깨지지 않게 따옴표로 감싸라고 합니다. 이번 여섯 번은 모두 따옴표를 썼습니다.
• 깔아 두기만 2회차는 한국어 요청에 마지막 답을 영어로 했습니다. 여섯 번 중 이 한 번뿐입니다.

대안

방법	다른 점	이럴 때 고르세요
plugin-dev + /plugin-dev:create-plugin(이 글)	8단계 순서, 구성별 스킬, 검사 에이전트 3개	나눠 줄 플러그인, 구성이 여러 개인 플러그인
말로 요청	이번 실험에서 같은 10점, 따로 깔 것 없음	명령·훅 한두 개짜리 작은 플러그인
hookify 플러그인	플러그인을 따로 만들지 않고 “이런 건 막아 줘”라는 말로 훅 규칙만 만듦	나만 쓰는 안전장치 하나가 필요할 때
security-guidance 플러그인	파일을 고칠 때 위험한 코드 패턴을 경고하는 훅이 이미 들어 있음	직접 만들기 전에 기성 안전장치를 쓰고 싶을 때
mcp-server-dev 플러그인	MCP 서버 만들기만 다룸	플러그인 안에 넣을 MCP 서버를 따로 만들 때

자주 묻는 질문

플러그인 이름을 claude-로 시작해도 되나요?

안 됩니다. 공식 문서에 따르면 claude-, anthropic-으로 시작하는 이름은 Anthropic 공식 플러그인처럼 보인다는 이유로 검사에서 오류가 납니다. 이름은 소문자와 하이픈(kebab-case)으로 짓습니다.

plugin-dev 플러그인은 무료인가요?

플러그인 자체는 무료(Apache-2.0)입니다. 플러그인을 만들 때 클로드 사용량이 들고, 이번에는 한 번에 0.65~1.94달러어치였습니다. 구독 요금제라면 요금제 사용량 한도에서 빠집니다.

훅으로 .env를 막으면 완전히 안전한가요?

아닙니다. 이번 여섯 개 모두 Bash로 폴더 전체를 grep하거나 cat .e*처럼 이름을 숨기면 통과했습니다. 훅은 실수로 여는 일을 줄이는 안전망으로 보고, 진짜 비밀값은 작업 폴더 밖에 두는 편이 낫습니다. 훅 동작은 훅 공식 문서에 정리돼 있습니다.

출처

plugin-dev 플러그인 폴더, create-plugin 명령 파일, 플러그인 매니페스트 공식 문서, 훅 공식 문서 (모두 2026-10-19 확인, 저장소 별 42,694개)