마켓플레이스 참조

• 마켓플레이스 파일: 최상위 필드 및 플러그인 항목
• 항목의 source: 플러그인 소스
• 설정의 source 객체: 마켓플레이스 소스
• claude plugin validate <path>의 출력: 검증 메시지 - 각 메시지를 이름이 지정된 필드에 매핑합니다

​

마켓플레이스 파일

​

예약된 이름

• 공식 마켓플레이스 이름: claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, life-sciences, knowledge-work-plugins, claude-for-legal, claude-for-financial-services, financial-services-plugins, first-party-plugins, claude-tag-plugins. github.com/anthropics/ 아래의 github 또는 git 마켓플레이스 소스에서 오는 마켓플레이스가 아닌 한 예약됨.
• 커뮤니티 마켓플레이스 이름: claude-community, claude-plugins-community, healthcare. 공식 이름과 동일한 규칙 아래 예약됨.
• 플러그인 디렉토리 이름: anthropic-plugin-directory, claude-plugin-directory. 공식 이름과 동일한 규칙 아래 예약됨.
• 공식 마켓플레이스를 사칭하는 이름: official-claude-plugins 또는 claude-plugins-v2와 같은 이름, 그리고 비ASCII 문자를 포함하는 모든 이름. 오류는 Marketplace name impersonates an official Anthropic/Claude marketplace입니다. 이름의 제어 또는 양방향 서식 문자도 Marketplace name cannot contain control or bidirectional-formatting characters를 보고합니다.
• 예약된 이름의 다른 철자: 예약된 이름과 후행 점으로만 다르거나 하이픈 대신 다른 기호를 사용하는 이름이므로 claude.code.plugins는 claude-code-plugins로 계산됩니다. claude plugin validate는 이러한 이름을 수락합니다. 마켓플레이스 추가는 is another spelling of "<reserved>", a reserved marketplace name으로 실패하고, 하나 아래에 등록된 마켓플레이스는 로드를 중지합니다. 이 확인에는 Claude Code v2.1.280 이상이 필요합니다.
• Claude Code가 마켓플레이스에서 오지 않는 플러그인에 사용하는 이름: --plugin-dir로 로드된 플러그인의 경우 inline, 기본 제공 플러그인의 경우 builtin, .claude/skills/에서 자동 로드되는 플러그인의 경우 skills-dir, claude.ai 계정에서 동기화된 플러그인의 경우 synced. claude-plugin-test도 예약됩니다. skills-dir은 {"source": "skills-dir"}로도 strictKnownMarketplaces 및 blockedMarketplaces에 나타나며, 소스 값이 정책 목록에서만 유효함에서 설명합니다.
• npm, pip, uv, cargo, github, gh: 모든 대소문자로 예약됨. 이 확인에는 Claude Code v2.1.275 이상이 필요합니다.
• claudeai-로 시작하는 이름: claude.ai에서 호스팅되는 마켓플레이스를 위해 예약됨. claude plugin marketplace add는 Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai로 이를 사용하는 다른 마켓플레이스를 거부합니다.

​

최상위 필드

​

플러그인 항목

​

항목이 plugin.json과 결합되는 방식

• plugin.json 없음: 항목은 strict에 관계없이 매니페스트입니다. mcpServers, lspServers, userConfig, channels를 포함한 모든 매니페스트 필드가 항목에 적용됩니다.
• plugin.json 있음: plugin.json이 매니페스트입니다. 엄격 모드는 항목의 6개 구성 요소 필드인 commands, agents, skills, hooks, outputStyles, themes를 결합할지 아니면 충돌로 거부할지 결정합니다. 항목 mcpServers, lspServers, userConfig, channels는 적용되지 않습니다. plugin.json에서 선언하세요.

​

항목의 훅

​

표시 필드

• 항목에 설정한 필드의 경우, 사용자는 plugin.json이 다른 값을 설정하더라도 항목의 값을 봅니다.
• 항목이 설정하지 않은 필드의 경우, 사용자는 plugin.json 값을 봅니다.

​

엄격 모드

​

플러그인 소스

• ref: 브랜치 또는 태그입니다. 저장소의 기본 브랜치로 기본 설정됩니다.
• sha: 전체 40자 소문자 커밋 SHA입니다. ref와 sha를 모두 설정하면 Claude Code는 sha를 체크아웃합니다. GitHub, GitLab, Bitbucket을 포함한 대부분의 git 호스트에서 이는 ref로 지정된 브랜치 또는 태그가 업스트림에서 삭제되었더라도 커밋이 여전히 저장소에서 도달 가능한 한 설치가 성공함을 의미합니다. AWS CodeCommit과 같은 일부 서버는 SHA로 커밋을 가져오는 것을 지원하지 않습니다. 이러한 서버에서는 ref가 여전히 존재해야 하고 고정된 커밋이 이로부터 도달 가능해야 합니다.

​

상대 경로 플러그인 소스

{ "name": "formatter", "source": "./plugins/formatter" }

• github, git, file, directory: Claude Code가 마켓플레이스의 파일을 가지고 있습니다.
• url: Claude Code는 marketplace.json만 가져오므로 상대 경로를 확인할 수 없습니다. 각 플러그인에 github 또는 git-subdir과 같은 객체 소스를 제공합니다.
• settings: 상대 경로는 완전히 거부됩니다.

​

pluginRoot 아래의 베어 이름

• 그 자체가 마켓플레이스 내의 상대 경로여야 합니다.
• 이미 ./로 시작하는 소스에는 영향을 주지 않습니다.
• team-a/formatter와 같이 /를 포함하는 소스는 베어 이름이 아니며 metadata.pluginRoot가 설정되어 있더라도 여전히 ./ 접두사가 필요합니다.

​

github 플러그인 소스

{
  "name": "formatter",
  "source": {
    "source": "github",
    "repo": "your-org/formatter",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

​

url 플러그인 소스

{
  "name": "formatter",
  "source": {
    "source": "url",
    "url": "https://gitlab.example.com/your-group/formatter.git",
    "ref": "main"
  }
}

​

git-subdir 플러그인 소스

{
  "name": "formatter",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/your-org/monorepo.git",
    "path": "tools/formatter"
  }
}

​

npm 플러그인 소스

• package: 패키지 이름 또는 @your-org/formatter와 같은 스코프된 이름
• version: 버전 또는 범위
• registry: 기본 레지스트리에 없는 패키지의 레지스트리 URL

{
  "name": "formatter",
  "source": {
    "source": "npm",
    "package": "@your-org/formatter",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

​

archive 플러그인 소스

{
  "name": "formatter",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/formatter-2.0.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

​

command 플러그인 소스

• command: 플러그인 디렉토리의 절대 경로를 한 줄로 출력하고 0으로 종료하는 셸 명령입니다. Claude Code는 실행하기 전에 사용자에게 전체 문자열을 검토하도록 표시합니다. 인쇄 가능한 ASCII로 작성하고, 최대 500자이며, 4개 이상의 연속 공백이 없어야 합니다.
• timeout: 1에서 600 사이의 전체 초 수입니다. 기본값은 60입니다.
• mode: copy(기본값) 또는 link입니다. 복사 모드 및 링크 모드를 참조하세요.

{
  "name": "formatter",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path",
    "timeout": 120
  }
}

​

명령이 수행해야 할 작업

• 셸 및 작업 디렉토리: Claude Code는 사용자의 홈 디렉토리에서 sh 또는 Windows의 cmd.exe를 통해 명령을 실행합니다. 절대 경로 또는 PATH의 명령을 제공합니다.
• 출력: stdout에 정확히 한 줄(플러그인 디렉토리의 절대 경로)을 출력하고 timeout 초 내에 0으로 종료합니다.
• 디렉토리 내용: 디렉토리는 명령이 종료될 때까지 완전한 플러그인을 보유합니다. 경로는 실행마다 다를 수 있습니다.

​

설치 또는 업데이트를 실패하게 하는 출력

• 플러그인 콘텐츠 없음: 인쇄된 디렉토리의 최상위 수준에 .claude-plugin/ 디렉토리 또는 skills/, commands/, agents/, hooks/ 디렉토리와 같은 플러그인 콘텐츠가 없습니다.
• 세션의 자체 디렉토리: 인쇄된 디렉토리는 Claude Code가 시작된 디렉토리 또는 그 부모 중 하나입니다.
• 네트워크 경로: Windows에서 인쇄된 경로는 UNC 경로입니다.
• 복사하기에 너무 큼: 복사 모드에서 디렉토리는 256 MiB보다 크거나 20,000개 이상의 항목을 가집니다.

​

복사 모드 및 링크 모드

• copy: Claude Code는 디렉토리를 플러그인 캐시에 복사하고 복사된 파일의 해시에서 플러그인 버전을 파생합니다. 도구는 명령이 종료된 후 디렉토리를 삭제하거나 다시 쓸 수 있습니다. 동일한 파일을 생성하는 재실행은 최신 상태로 계산됩니다.
• link: Claude Code는 인쇄된 디렉토리의 각 최상위 항목에 대한 링크로 플러그인의 캐시 항목을 채우고 파일을 제자리에서 로드합니다. 아무것도 복사되지 않고, 파일 내용이 해시되지 않으며, 크기 제한이 적용되지 않습니다. 렌더링된 SDK 내보내기와 같이 복사하기에 너무 큰 디렉토리에 사용합니다.

• 디렉토리를 제자리에 유지: Claude Code는 모든 시작 시 링크를 통해 플러그인을 로드하므로 인쇄된 디렉토리는 플러그인이 설치된 상태로 유지되는 동안 그 위치에 남아 있어야 합니다.
• 새 콘텐츠를 신호하기 위해 다른 경로 출력: 버전은 인쇄된 디렉토리의 실제 경로 및 최상위 항목에서 나오며, 내부의 파일에서는 나오지 않습니다.
• 디렉토리 내에 최상위 심볼릭 링크 유지: 최상위 항목이 인쇄된 디렉토리 외부를 가리키는 심볼릭 링크인 경우 설치가 실패합니다.
• node_modules 포함: Claude Code는 링크 모드 플러그인에 대해 Node.js 패키지 종속성 설치를 건너뛰므로 플러그인이 필요한 패키지를 이미 포함하는 디렉토리를 출력합니다.
• 디렉토리 내에서 시작된 세션: 인쇄된 디렉토리 또는 그 아래 어디서나 시작된 세션은 플러그인을 로드하지 않습니다.
• Windows에서 아님: Claude Code는 Windows에서 링크 모드 플러그인 설치를 거부합니다. 거기서 "mode": "copy"를 선언합니다.

​

마켓플레이스 소스

• claude plugin marketplace add: Claude Code는 전달한 문자열에서 소스를 빌드합니다.
• extraKnownMarketplaces: source 객체로 직접 작성합니다.
• strictKnownMarketplaces 및 blockedMarketplaces: 관리자가 이 두 정책 목록에 소스를 작성합니다. strictKnownMarketplaces는 허용 목록이고 blockedMarketplaces는 차단 목록입니다.

​

유형별 필드

​

정책 목록에서만 유효한 소스 값

• hostPattern 및 pathPattern: Claude Code가 가져오기 전에 소스에 대해 테스트하는 정규 표현식.
• skills-dir: 소스가 아닙니다. strictKnownMarketplaces를 설정하면, skills-directory 플러그인은 해당 목록에 {"source": "skills-dir"}을 추가할 때까지 로드를 중지합니다.
• owner/*: 마켓플레이스 소스의 github repo 값으로, 정확히 해당 GitHub 소유자 아래의 모든 저장소와 일치합니다. Claude Code v2.1.223 이상 필요.

​

설정의 소스 객체

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/your-org/your-marketplace.git",
        "ref": "main"
      }
    }
  }
}

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/*" },
    { "source": "hostPattern", "hostPattern": "^git\\.example\\.com$" }
  ]
}

​

유효성 검사 메시지

​

source의 잘못된 입력

• ./로 시작하지 않는 상대 경로("." 또는 metadata.pluginRoot 아래의 베어 이름 제외)
• ..를 포함하는 npm package
• 플러그인 source 중 하나가 아닌 source 유형
• 필수 필드가 누락되었거나 잘못된 유형의 알려진 유형(예: repo 없는 github)

​

유효성 검사가 포착하지 못하는 오류

​

다음 단계

• 마켓플레이스 만들기: 이러한 필드에서 마켓플레이스를 빌드하고 로컬에서 설치
• 마켓플레이스 호스팅 및 유지보수: 파일을 어디에 넣을지, 사용자가 변경 사항을 받는 방식
• 플러그인 매니페스트 참조: 항목이 재정의할 수 있는 plugin.json 필드
• 조직의 플러그인 관리: 이러한 소스 값을 사용하는 허용 목록 및 차단 목록 레시피