참조

marketplace.json 스키마

마켓플레이스 매니페스트는 저장소 루트의 .claude-plugin/marketplace.json에 위치합니다.

최상위 필드

필드	필수 여부	설명
`$schema`	아니오	유효성 검사를 위한 JSON Schema URL
`name`	예	고유한 마켓플레이스 식별자
`version`	아니오	마켓플레이스 스키마 버전 (semver)
`metadata.description`	예	사람이 읽을 수 있는 마켓플레이스 설명
`owner.name`	예	마켓플레이스를 소유하는 조직 또는 사용자
`owner.url`	아니오	소유자의 프로필 또는 웹사이트 URL
`owner.email`	아니오	연락처 이메일
`plugins`	예	플러그인 항목 배열

플러그인 항목 필드

필드	필수 여부	설명
`name`	예	플러그인 식별자 (`plugin.json`과 일치해야 함)
`description`	예	플러그인에 대한 간단한 설명
`version`	예	시맨틱 버전 문자열
`author.name`	예	플러그인 작성자
`source`	예	플러그인의 경로 또는 URL (소스 유형 참조)
`category`	예	플러그인 카테고리 (예: `productivity`)
`homepage`	아니오	플러그인 문서 또는 홈페이지 URL
`license`	아니오	SPDX 라이선스 식별자
`keywords`	아니오	검색 키워드 배열
`tags`	아니오	필터링을 위한 태그 배열
`repository`	아니오	저장소 URL

플러그인 소스 유형

marketplace.json의 source 필드는 여러 형식을 지원합니다:

유형	예시	설명
상대 경로	`./plugins/example-plugin`	동일한 저장소 내의 플러그인
GitHub 단축 표기	`owner/repo`	저장소 루트의 플러그인
경로 포함 GitHub	`owner/repo/path/to/plugin`	하위 디렉터리의 플러그인
Git URL	`https://github.com/owner/repo.git`	Git 저장소
npm 패키지	`npm:@scope/package`	게시된 npm 패키지

plugin.json 스키마

각 플러그인은 해당 디렉터리 내의 .claude-plugin/plugin.json에 매니페스트를 가집니다.

필드	필수 여부	설명
`name`	예	플러그인 식별자
`description`	예	플러그인의 기능
`version`	예	시맨틱 버전
`author.name`	예	플러그인 작성자
`author.url`	아니오	작성자의 프로필 또는 웹사이트 URL
`homepage`	아니오	문서 URL
`keywords`	아니오	검색 키워드
`license`	아니오	SPDX 라이선스 식별자
`repository`	아니오	저장소 URL

플러그인 디렉터리 레이아웃

plugins/example-plugin/
  .claude-plugin/
    plugin.json          # 플러그인 매니페스트 (필수)
  skills/
    skill-name/
      SKILL.md           # 스킬 정의 (스킬당 필수)
      references/        # 참조 데이터 파일 (선택 사항)
  commands/
    command-name.md      # 명령 정의 (명령당 하나)
  agents/
    agent-name.md        # 에이전트 정의 (에이전트당 하나)
  README.md              # 플러그인 문서 (권장)

환경 변수

플러그인은 스킬 및 명령 파일에서 다음 변수를 사용할 수 있습니다:

변수	설명
`$\{CLAUDE_PLUGIN_ROOT\}`	플러그인 루트 디렉터리의 절대 경로

유효성 검사

마켓플레이스 및 플러그인 매니페스트를 로컬에서 유효성 검사합니다:

claude plugin validate .

다음 항목을 확인합니다:

marketplace.json 스키마 준수
참조된 모든 플러그인 디렉터리 존재 여부
각 플러그인의 유효한 plugin.json 보유 여부
스킬의 올바른 형식의 SKILL.md 프론트매터 보유 여부
명령의 필수 프론트매터 필드 보유 여부

팀 구성

마켓플레이스 사전 구성

임의의 저장소의 .claude/settings.json에 추가합니다:

{
  "extraKnownMarketplaces": [
    "f5-sales-demo/marketplace"
  ]
}

플러그인 사전 활성화

{
  "enabledPlugins": [
    "f5xc-docs-tools@f5-sales-demo-marketplace"
  ]
}

문제 해결

마켓플레이스를 찾을 수 없음

마켓플레이스가 추가되었는지 확인합니다:

/plugin marketplace list

없는 경우 다시 추가합니다:

/plugin marketplace add f5-sales-demo/marketplace

플러그인이 활성화되지 않음

플러그인이 설치되었는지 확인합니다: /plugin list
Claude Code 버전이 플러그인을 지원하는지 확인합니다 (v1.0.33 이상)
스킬의 트리거 조건이 현재 컨텍스트와 일치하는지 확인합니다

스킬이 자동으로 트리거되지 않음

스킬은 SKILL.md 프론트매터의 description 필드를 기반으로 활성화됩니다. 스킬이 예상대로 활성화되지 않는 경우:

설명이 트리거 컨텍스트를 정확하게 설명하는지 확인합니다
명령을 직접 사용합니다 (예: /f5xc-docs-tools:review-mdx) 임시 해결 방법으로 활용합니다

검토 후 빌드 오류

플러그인은 문제를 보고하지만 자동으로 수정하지 않습니다. 제안된 수정 사항을 수동으로 적용한 후 검토를 다시 실행하여 해결 여부를 확인합니다.