Claude Code 가이드: 플러그인 패키징·테스트와 배포

InYourLeague 리서치 · 2026-08-28

Answer in brief

Claude Code 플러그인은 독립된 디렉터리로 패키징하고, 구성 요소 폴더는 플러그인 루트에 두며 .claude-plugin/ 아래에는 plugin.json만 배치한다. --plugin-dir로 테스트하되 /reload-plugins는 문서에 나온 스킬 수정 사례에 한정해 설명하고, claude plugin validate는 근거가 확인된 에이전트 프런트매터 검사에 사용한다. 릴리스는 마켓플레이스 카탈로그로 배포하고, 선언한 매니페스트 버전은 필요한 시점에 올리며, 제공된 발췌문에 없는 캐시 동작은 단정하지 않는다.

Key facts at a glance

Failure modes and verification

FAQ

Claude Code 플러그인의 최소 구조는 무엇인가요?

플러그인은 지원 구성 요소를 담은 독립된 디렉터리다. .claude-plugin/plugin.json 매니페스트는 선택 사항이며, 사용할 때는 .claude-plugin/ 아래에 둔다. skills/, agents/, commands/, hooks/ 같은 구성 요소 폴더는 플러그인 루트에 둔다. 자세한 내용은 플러그인 생성 가이드에서 확인할 수 있다.

플러그인을 로컬에서 어떻게 테스트하나요?

claude --plugin-dir ./my-plugin으로 실행하고, 각 스킬을 예상한 네임스페이스로 호출한 뒤 /help의 Custom commands 탭을 확인한다. 이 절차로 플러그인 생성 가이드에 나온 로컬 패키지 경로와 스킬 검색 결과를 확인할 수 있다.

/reload-plugins가 모든 플러그인 구성 요소를 다시 불러오나요?

제공된 근거는 예제 스킬을 수정한 뒤 /reload-plugins를 사용하는 사례만 보여 준다. 에이전트, 훅, MCP 서버, LSP 서버, 모니터에도 같은 즉시 반영 동작이 적용된다고 입증하지는 않으므로, 이들 구성 요소는 새 테스트 세션에서도 확인해야 한다.

claude plugin validate 결과는 무엇을 입증하나요?

제공된 기술 참조는 이 명령으로 프런트매터가 파싱되지 않는 플러그인 에이전트 파일을 찾는 방법을 구체적으로 설명한다. 매니페스트가 있으면 플러그인 루트를, 문서에 나온 매니페스트 없는 사례에서는 agents/ 디렉터리를 전달한다. Claude Code v2.1.233 이상이 필요하며, 오류가 없더라도 모든 구성 요소가 포괄적으로 검증됐다는 뜻은 아니다.

매니페스트 버전은 업데이트에 어떤 영향을 주나요?

선택적인 매니페스트 version을 선언했다면 command source 예외를 제외하고 그 값을 올려야 사용자가 업데이트를 받는다. 생략하면 문서에 정의된 버전 결정 순서의 다른 소스가 값을 제공하지만, 제공된 발췌문에는 전체 우선순위가 나오지 않는다. 자세한 명세는 플러그인 기술 참조를 확인해야 한다.

마켓플레이스 배포는 어떻게 작동하나요?

사용자는 먼저 마켓플레이스 카탈로그를 추가한 다음 개별 플러그인을 설치한다. 카탈로그 추가만으로 플러그인이 설치되지는 않는다. 공식 마켓플레이스 수록 여부는 Anthropic이 결정하며, 독립 배포자는 자체 카탈로그를 공유할 수 있다. 커뮤니티 마켓플레이스는 자동 검증과 안전성 심사를 사용하고 각 항목을 commit SHA에 고정한다. 자세한 내용은 플러그인 검색 및 설치 문서에 나와 있다.

제공된 근거로 확인할 수 있는 캐시 동작은 무엇인가요?

발췌문에는 설치된 플러그인의 캐시 위치, 보존 기간, 파일 복사 방식 또는 모든 설치 방식에 공통인 무효화 규칙이 명시되어 있지 않다. 따라서 마켓플레이스로 설치한 플러그인의 임의 변경 사항이 언제 보이는지는 단정할 수 없으며, 버전을 명시적으로 관리하고 게시된 설치 경로를 직접 시험해야 한다.

Sources and freshness

• Official source
• Official source
• Official source
• Last verified: 2026-08-28

Extended guide

Claude Code 플러그인은 하나의 독립된 디렉터리로 패키징한다. 구성 요소 폴더는 플러그인 루트에 두고, .claude-plugin/은 plugin.json 전용 위치로 사용한다.

패키지 구조

매니페스트는 선택 사항이다. 사용할 경우 .claude-plugin/plugin.json에 name, description, version, author 같은 식별 정보와 표시용 메타데이터를 선언한다. 여기서 name은 스킬 네임스페이스로도 사용된다. 예를 들어 my-first-plugin에 포함된 hello 스킬은 /my-first-plugin:hello로 호출한다. 플러그인 루트는 --plugin-dir에 전달하는 개별 디렉터리 또는 .claude-plugin/plugin.json을 포함하는 개별 디렉터리다. ~/.claude/ 자체를 플러그인 루트로 간주해서는 안 된다. 자세한 구조는 공식 플러그인 생성 가이드와 기술 참조에서 확인할 수 있다.

빌드와 릴리스 절차

1. 패키지를 만든다. 전용 플러그인 디렉터리를 먼저 만든다. 안정적인 식별자, 플러그인 관리자에 표시할 설명 또는 명시적인 버전이 필요하면 .claude-plugin/plugin.json을 추가한다. skills/, commands/, agents/, hooks/는 .claude-plugin/ 안이 아니라 그 폴더와 같은 플러그인 루트에 배치한다. 이 경계를 지키면 Claude Code가 구성 요소를 찾는 위치와 사람이 패키지를 검토하는 기준이 일치한다.

2. 스킬을 의도적으로 구성한다. 여러 스킬을 제공한다면 스킬마다 SKILL.md를 포함하는 별도 디렉터리를 만든다. skills/ 디렉터리와 매니페스트의 skills 필드가 모두 없을 때는 루트의 SKILL.md 하나를 단일 스킬로 불러올 수 있다. 이 파일에는 프런트매터 name을 지정하는 편이 안전하다. name이 없으면 설치 디렉터리 이름이 호출 이름으로 사용될 수 있으며, 마켓플레이스 설치에서는 그 디렉터리 이름이 업데이트마다 달라지는 버전 문자열일 수 있다. 호출 이름이 릴리스 사이에서 바뀌면 사용자 문서와 자동화도 함께 깨질 수 있으므로 실제 네임스페이스를 반드시 확인한다.

3. 로컬에서 실행해 본다. claude --plugin-dir ./my-plugin으로 Claude Code를 시작하고, 각 스킬을 예상한 네임스페이스로 직접 호출한다. /help의 Custom commands 탭에서도 올바른 플러그인 이름 아래에 표시되는지 확인한다. 생성 가이드는 예제 스킬을 수정한 다음 /reload-plugins를 실행하는 절차를 보여 준다. 이 근거는 수정한 스킬을 다시 읽는 사례까지는 뒷받침하지만, 훅, 에이전트, MCP 서버, LSP 서버, 모니터의 모든 변경 사항이 같은 방식으로 즉시 반영된다는 뜻은 아니다. 다른 구성 요소나 완성된 릴리스를 확인할 때는 새 테스트 세션에서도 다시 실행해 보는 것이 보수적인 검증 방법이다.

4. 문서에 명시된 범위만 검증한다. 매니페스트가 있는 플러그인은 claude plugin validate ./my-plugin을 사용한다. 문서에 나온 매니페스트 없는 에이전트 사례에서는 claude plugin validate ./my-plugin/agents를 사용한다. 제공된 기술 참조는 이 명령이 플러그인의 기본 agents/ 디렉터리에서 파싱되지 않는 에이전트 프런트매터를 찾는 용도라고 구체적으로 설명한다. 이 기능에는 Claude Code v2.1.233 이상이 필요하다. 검사 결과가 깨끗하더라도 모든 매니페스트 필드, 훅, MCP 서버 또는 다른 구성 요소의 의미까지 포괄적으로 검증됐다고 해석해서는 안 된다. 관련 스키마를 별도로 대조하고 실제 호출과 이벤트 동작도 함께 시험한다.

5. 릴리스 버전을 관리한다. 매니페스트의 version은 선택 사항이다. 값을 선언했다면 command source 예외를 제외하고 그 값을 올려야 사용자가 업데이트를 받는다. 값을 생략하면 문서에 정의된 버전 결정 순서의 다른 소스가 버전을 제공한다. 다만 제공된 발췌문은 나머지 소스의 전체 우선순위를 보여 주지 않으므로, 여기서는 구체적인 순서를 추정하지 않는다. 배포 전에 매니페스트 버전과 실제로 배포하려는 소스 리비전이 같은 릴리스를 가리키는지 확인한다.

6. 마켓플레이스로 배포한다. 마켓플레이스는 플러그인 묶음이 아니라 플러그인을 찾고 설치하기 위한 카탈로그다. 사용자는 먼저 카탈로그를 추가하고, 그다음 필요한 플러그인을 개별적으로 설치한다. 카탈로그만 추가해서는 플러그인이 설치되지 않는다. claude-plugins-official 수록 여부는 Anthropic이 결정하며, 앱 내부 제출 양식은 공식 마켓플레이스가 아니라 커뮤니티 마켓플레이스로 제출된다. 독립 배포자는 자체 마켓플레이스를 만들어 사용자에게 공유할 수 있다. 커뮤니티 마켓플레이스의 타사 플러그인은 자동 검증과 안전성 심사를 거쳤으며, 각 카탈로그 항목은 특정 commit SHA에 고정된다. 설치 흐름은 플러그인 검색 및 설치 문서에 설명되어 있다.

릴리스 점검과 근거의 한계

게시 전에는 루트 디렉터리 구조, 매니페스트 식별 정보, 스킬 네임스페이스, 로컬 호출, 근거가 확인된 에이전트 프런트매터 검사, 버전 변경, 마켓플레이스 설치 경로를 차례로 확인한다. 가능하면 기존 로컬 상태에 의존하지 않는 깨끗한 환경에서 게시된 항목을 다시 설치해 실제 사용자 경로도 시험한다.

제공된 발췌문은 수정한 예제 스킬을 다시 불러오는 방법은 보여 주지만, 설치된 플러그인의 캐시 디렉터리, 보존 기간, 파일 복사 방식 또는 모든 설치 방식에 적용되는 무효화 규칙은 설명하지 않는다. 따라서 마켓플레이스로 설치한 플러그인이 임의의 파일 변경을 언제 감지하는지는 여기서 단정하지 않는다. 이 글에서 근거가 확인된 릴리스 통제 수단은 선언한 버전의 변경과 실제 설치 경로를 통한 종단 간 테스트다.

모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.