Claude Code 플러그인 eval로 테스트하고 커뮤니티 마켓플레이스에 제출하는 쉬운 방법

1. eval이 뭐예요? 한 줄로 이해하기

claude plugin eval은 내가 만든 Claude Code 플러그인이 얼마나 자주, 얼마나 정확하게 작동하는지를 숫자로 측정해 주는 테스트 도구예요. 우리가 학교에서 시험을 보는 것처럼, 플러그인에게도 시험을 보는 거라고 생각하면 쉽습니다.

eval은 미리 만들어 둔 테스트 질문 목록(테스트 프롬프트)을 여러 번 돌리는데, 이때 플러그인을 켰을 때와 껐을 때의 차이를 자동으로 비교해 줘요. 그래서 "플러그인이 실제로 얼마나 도움이 되는지"를 객관적인 숫자로 알 수 있습니다.

2. 왜 --plugin-dir 말고 eval을 써야 할까?

기존의 --plugin-dir 옵션은 "플러그인이 에러 없이 돌아간다" 정도만 확인해 줘요. 하지만 실제 개발에서 더 중요한 두 가지는 확인이 안 됩니다.

• Claude가 정말로 그 플러그인을 스스로 찾아서 쓰는지
• 플러그인을 쓴 결과가 원하는 답에 가까운지

eval을 돌리면 이 두 가지가 모두 자동으로 측정돼요. 그리고 결정적으로, 회귀(regression)를 사전에 잡아낼 수 있어요.

회귀라는 말이 낯설 수 있는데요, 쉽게 말하면 "전에는 잘 되던 기능이 코드 수정이나 새 모델 업데이트 이후에 갑자기 안 좋아지는 현상"이에요. 사람은 잘 못 느끼지만 eval 점수는 즉시 보여줘서 출시 전에 미리 막을 수 있습니다.

3. eval 실행 순서 (3단계)

막 복잡하지 않아요. 다음 3단계면 충분합니다.

STEP 1. 테스트 질문 목록 만들기

우리 플러그인이 해결해 줘야 하는 대표 질문 10~30개를 메모장에 적어 두세요. 이게 평가의 시험 문제지가 됩니다.

STEP 2. eval 실행하기

각 질문은 플러그인 켠 상태와 플러그인 끈 상태에서 각각 여러 번 반복 실행돼요. 결과 표가 자동으로 출력됩니다.

STEP 3. 점수 비교하고 출시 결정

출력 표에서 "플러그인 켰을 때의 점수 − 껐을 때의 점수"가 플러그인이 만들어 낸 진짜 기여예요. 새 모델이 출시되거나 코드를 고친 뒤에도 이 점수가 떨어지지 않았는지 확인하면 안전하게 출시할 수 있습니다.

4. 마켓플레이스 두 가지, 뭐가 다를까?

Anthropic은 Claude Code 플러그인을 위한 마켓플레이스를 두 개 운영해요. 둘의 성격이 완전히 다릅니다.

쉽게 말하면, official은 백화점 직매장이요, community는 외부 셀러들도 들어와 있는 오픈 마켓이에요. 대부분의 개발자는 community에 먼저 제출하는 것이 일반적인 경로예요.

5. 커뮤니티 마켓플레이스 제출 5단계

내 플러그인을 다른 사용자도 설치할 수 있게 하려면 다음 순서대로 진행하세요.

STEP 1. 로컬에서 validate 돌리기

여기서 ./your-plugin은 내 플러그인 폴더 경로로 바꿔 주면 됩니다. 통과하면 다음과 같이 출력돼요.

경고(warnings)는 검증을 실패시키는 요인이 아니에요. 그래도 경고를 오류처럼 엄격하게 다루고 싶다면 --strict 플래그를 추가하면 됩니다.

STEP 2. 제출 폼 작성하기

아래 두 경로 중 하나를 골라 폼을 작성해 주세요.

• claude.ai 웹: claude.ai/admin-settings/directory/submissions/plugins/new
• Anthropic Console: platform.claude.com/plugins/submit

STEP 3. 자동 심사 기다리기

제출하면 심사 파이프라인이 validate 검사를 다시 돌리고, 자동화된 안전성 검사도 함께 진행해요. 보통 수 시간에서 며칠 안에 결과가 나와요.

STEP 4. 승인 후, 저장소에 새 커밋 푸시

승인된 플러그인은 자동으로 특정 커밋 SHA에 고정(pin)돼요. 이후 내가 저장소에 새 커밋을 푸시하면 CI가 자동으로 핀을 갱신해 줘서 별도 작업을 할 필요가 없습니다.

STEP 5. 카탈로그 반영 여부 확인

공개 카탈로그는 매일 밤 한 번씩 동기화돼요. 따라서 승인 직후에는 약간의 시차가 있을 수 있어요. 커뮤니티 카탈로그에서 내 플러그인 이름을 검색해 보고, 이름이 보이면 그때부터 다른 사용자가 설치할 수 있는 상태가 됩니다.

6. 승인 후 알아둘 자동화 동작

한 번 승인되면 다음 3가지가 자동으로 돌아가서 관리가 편해요.

7. 자주 묻는 질문 (FAQ)

8. 용어 사전 (10개)

글을 따라오면서 어려웠던 단어들을 한 자리에 모았어요. 필요할 때마다 펼쳐 보세요.

플러그인 (Plugin)

Claude Code에 새로운 기능을 더하기 위해 만든 확장 모듈이에요. 스킬(skills), 에이전트(agents), 훅(hooks), MCP 서버 등을 한 줄로 묶어서 배포하는 형태입니다.

평가 / Eval (Evaluation)

테스트 질문으로 플러그인의 품질과 정확도를 자동으로 측정하는 절차예요. claude plugin eval 명령어로 실행합니다.

매니페스트 (Manifest)

플러그인의 이름·설명·버전 같은 신상 정보를 적어 두는 설정 파일이에요. 보통 .claude-plugin/plugin.json에 있어요.

마켓플레이스 (Marketplace)

플러그인을 올리고, 검색하고, 내려받을 수 있는 중앙 카탈로그예요. 공식(official)과 커뮤니티(community) 두 가지가 운영됩니다.

스킬 (Skill)

SKILL.md 파일에 정의되어, 작업 내용에 따라 Claude가 자동으로 불러 쓰는 기능이에요. 호출할 때는 항상 /플러그인명:스킬명처럼 네임스페이스가 붙어요.

훅 (Hooks)

도구 사용 같은 특정 이벤트가 일어나면 자동으로 실행되는 이벤트 처리 코드예요. hooks/hooks.json에 정의합니다.

MCP (모델 컨텍스트 프로토콜)

Claude 같은 AI 모델이 외부 도구· 데이터베이스에 안전하게 붙을 수 있게 해 주는 공개 표준 프로토콜이에요. .mcp.json에 서버 구성을 적습니다.

LSP (언어 서버 프로토콜)

자동완성, 코드 설명, 오류 표시 같은 실시간 코드 보조 기능을 제공하기 위한 표준이에요. TypeScript·Python·Rust 등 공식 지원 외의 언어를 추가할 때 .lsp.json으로 설정합니다.

네임스페이스 (Namespace)

이름이 같은 스킬이 여러 플러그인에 있을 때 충돌하지 않게, 앞에 붙이는 이름 표식이에요. 예: /my-plugin:hello.

에이전트 (Agent)

시스템 프롬프트·도구 제한을 묶어서 재사용 가능한 단위로 만든 자율 실행 구성이에요. settings.json의 agent 키로 메인 스레드에 띄울 수 있어요.

마무리하며

이번에 Claude Code에 추가된 eval 기능은 "플러그인이 진짜 일을 하고 있는가"라는 오래된 질문에 마침내 숫자 하나로 답을 줬다는 데 의미가 있어요. 더 좋은 점은, eval을 자세히 안 본 사람도 플러그인 작성자는 validate 한 번으로 기본 품질을 지킬 수 있고, 커뮤니티 마켓플레이스 제출도 5단계면 끝난다는 거예요.

다음 글에서는 eval 점수를 더 잘 만드는 테스트 프롬프트 작성 요령과, 공식 마켓플레이스에 등재될 가능성을 높이는 큐레이션 팁을 다뤄볼게요.