플러그인 마켓플레이스 생성 및 배포

Claude Code 확장 프로그램을 팀과 커뮤니티에 배포하기 위한 플러그인 마켓플레이스를 구축하고 호스팅합니다.

플러그인 마켓플레이스는 다른 사용자에게 플러그인을 배포할 수 있는 카탈로그입니다. 마켓플레이스는 중앙 집중식 검색, 버전 추적, 자동 업데이트 및 git 저장소와 로컬 경로를 포함한 여러 소스 유형을 지원합니다. 이 가이드에서는 팀이나 커뮤니티와 플러그인을 공유하기 위해 자신의 마켓플레이스를 만드는 방법을 보여줍니다.

기존 마켓플레이스에서 플러그인을 설치하려고 하시나요? 미리 빌드된 플러그인 검색 및 설치를 참조하세요.

개요

마켓플레이스를 생성하고 배포하는 과정은 다음과 같습니다:

1. 플러그인 생성: skills, 에이전트, hooks, MCP 서버 또는 LSP 서버를 사용하여 하나 이상의 플러그인을 빌드합니다. 이 가이드에서는 배포할 플러그인이 이미 있다고 가정합니다. 플러그인 생성 방법에 대한 자세한 내용은 플러그인 생성을 참조하세요.
2. 마켓플레이스 파일 생성: 플러그인을 나열하고 플러그인을 찾을 위치를 정의하는 marketplace.json을 정의합니다. 마켓플레이스 파일 생성을 참조하세요.
3. 마켓플레이스 호스팅: GitHub, GitLab 또는 다른 git 호스트에 푸시합니다. 마켓플레이스 호스팅 및 배포를 참조하세요.
4. 사용자와 공유: 사용자가 /plugin marketplace add로 마켓플레이스를 추가하고 개별 플러그인을 설치합니다. 플러그인 검색 및 설치를 참조하세요.

마켓플레이스가 라이브 상태가 되면 저장소에 변경 사항을 푸시하여 업데이트할 수 있습니다. 사용자는 /plugin marketplace update로 로컬 복사본을 새로 고칩니다.

연습: 로컬 마켓플레이스 생성

이 예제에서는 하나의 플러그인으로 마켓플레이스를 생성합니다: 코드 리뷰를 위한 quality-review skill입니다. 디렉터리 구조를 생성하고, skill을 추가하고, 플러그인 매니페스트와 마켓플레이스 카탈로그를 생성한 다음, 설치하고 테스트합니다.

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

---
description: Review code for bugs, security, and performance
---

선택한 코드 또는 최근 변경 사항을 다음 항목에 대해 검토합니다:
- 잠재적 버그 또는 엣지 케이스
- 보안 문제
- 성능 문제
- 가독성 개선

간결하고 실행 가능한 내용을 제공합니다.

{
"name": "quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}

{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews"
}
]
}

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

/quality-review-plugin:quality-review

플러그인이 수행할 수 있는 작업(hooks, 에이전트, MCP 서버 및 LSP 서버 포함)에 대해 자세히 알아보려면 플러그인을 참조하세요.

마켓플레이스 파일 생성

저장소 루트에 .claude-plugin/marketplace.json을 생성합니다. 이 파일은 마켓플레이스의 이름, 소유자 정보 및 소스가 있는 플러그인 목록을 정의합니다.

각 플러그인 항목에는 최소한 name과 source(Claude Code가 가져올 위치를 알려주는)가 필요합니다. 사용 가능한 모든 필드는 아래의 전체 스키마를 참조하세요.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "저장 시 자동 코드 포맷팅",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "배포 자동화 도구"
    }
  ]
}

마켓플레이스 스키마

필수 필드

소유자 필드

선택적 필드

description 및 version은 이전 버전과의 호환성을 위해 metadata 아래에서도 허용됩니다.

플러그인 항목

plugins 배열의 각 플러그인 항목은 플러그인과 플러그인을 찾을 위치를 설명합니다. 플러그인 매니페스트 스키마의 모든 필드(예: description, version, author, commands, hooks 등)와 이러한 마켓플레이스 특정 필드를 포함할 수 있습니다: source, category, tags, strict, relevance, headers, 및 headersHelper.

필수 필드

선택적 플러그인 필드

표준 메타데이터 필드:

항목과 플러그인의 자체 plugin.json 모두 표시 필드 displayName, description, author, homepage, repository, license, 및 keywords를 설정할 수 있습니다. 플러그인 목록 및 세부 정보에서 설치 전후:

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

설치 전에 Claude Code는 plugin.json을 상대 경로 소스가 있는 항목에 대해서만 읽을 수 있으며, 이 항목의 플러그인 파일은 마켓플레이스 내부에 있습니다. 다른 소스 유형이 있는 항목의 경우, 사용자는 플러그인을 설치할 때까지 항목의 자체 필드만 봅니다.

구성 요소 구성 필드:

아카이브 인증 필드:

항목에 자격 증명이 필요한 서버의 archive 소스가 있을 때 이를 설정합니다.

플러그인 소스

플러그인 소스는 Claude Code에 마켓플레이스에 나열된 각 개별 플러그인을 가져올 위치를 알려줍니다. 이는 marketplace.json의 각 플러그인 항목의 source 필드에 설정됩니다.

Claude Code는 설치된 각 플러그인을 ~/.claude/plugins/cache의 로컬 버전 관리 플러그인 캐시에 복사합니다. 단, 플러그인이 제자리에서 로드되는 경우는 제외됩니다. 링크 모드의 command 소스는 제자리에서 로드되며, 상대 경로 소스도 로컬 디렉터리에서 추가된 마켓플레이스에서 제자리에 로드됩니다. Claude Code는 또한 플러그인의 적격 Node.js 패키지 종속성을 캐시된 복사본에 설치합니다. 플러그인 캐싱 및 파일 해석을 참조하여 로컬 디렉터리 마켓플레이스에서 제자리에 로드된 플러그인이 편집 내용을 선택하는 방법을 알아보세요.

아래의 git 기반 소스 유형은 github, url, 및 git-subdir입니다. ref와 sha가 모두 설정되면 sha가 유효한 핀입니다. Claude Code는 고정된 커밋을 직접 가져오고 체크아웃합니다.

GitHub, GitLab, Bitbucket을 포함한 대부분의 git 호스트에서 이는 분기 또는 태그가 업스트림에서 삭제되었더라도 커밋이 저장소에서 여전히 도달 가능한 한 설치가 성공함을 의미합니다. AWS CodeCommit과 같은 일부 서버는 SHA로 커밋을 가져오는 것을 지원하지 않습니다. 이러한 서버에서는 ref가 여전히 존재해야 하고 고정된 커밋이 이로부터 도달 가능해야 합니다.

조직 설정 > 플러그인을 통해 플러그인을 배포하는 경우 일부 소스 유형만 허용됩니다. 조직 설정을 통해 배포를 참조하세요.

상대 경로

동일한 저장소의 플러그인의 경우 ./로 시작하는 경로를 사용합니다:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

경로는 마켓플레이스 루트(.claude-plugin/을 포함하는 디렉터리)에 상대적으로 해석됩니다. 위의 예에서 ./plugins/my-plugin은 marketplace.json이 <repo>/.claude-plugin/marketplace.json에 있더라도 <repo>/plugins/my-plugin을 가리킵니다. 마켓플레이스 루트 외부로 나가기 위해 ../를 사용하지 마세요. macOS 및 Linux에서 Claude Code는 선행 ./ 이후 어디든 백슬래시가 있는 항목 경로를 거부하므로 모든 플랫폼에서 구분 기호를 /로 작성합니다.

bare name은 /가 없는 단일 디렉터리 이름입니다(예: "formatter"). ./ 경로 대신 bare name을 작성하려면 metadata.pluginRoot를 이들이 해석되는 디렉터리로 설정합니다. "pluginRoot": "./plugins"를 사용하면 Claude Code는 "source": "formatter"를 ./plugins/formatter로 해석합니다. Claude Code v2.1.239 이상 필요합니다.

metadata.pluginRoot는 그 자체로 마켓플레이스 내의 상대 경로여야 합니다. Claude Code는 이미 ./로 시작하는 소스에 대해 이를 무시합니다. /를 포함하는 소스(예: team-a/formatter)는 bare name이 아니며 metadata.pluginRoot가 설정되어 있더라도 여전히 ./ 접두사가 필요합니다.

GitHub 저장소

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

특정 분기, 태그 또는 커밋에 고정할 수 있습니다:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git 저장소

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

특정 분기, 태그 또는 커밋에 고정할 수 있습니다:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git 하위 디렉터리

git-subdir을 사용하여 git 저장소의 하위 디렉터리 내에 있는 플러그인을 가리킵니다. Claude Code는 희소하고 부분적인 복제를 사용하여 하위 디렉터리만 가져오므로 대규모 모노레포의 대역폭을 최소화합니다.

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

특정 분기, 태그 또는 커밋에 고정할 수 있습니다:

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

url 필드는 GitHub 단축형(owner/repo) 또는 SSH URL(git@github.com:owner/repo.git)도 허용합니다.

npm 패키지

npm 소스는 공개 npm 레지스트리 또는 팀이 호스팅하는 개인 레지스트리의 모든 패키지를 지정할 수 있습니다. Claude Code는 npm 클라이언트로 패키지를 해석하고 tarball을 다운로드한 후 플러그인 캐시에 압축 해제합니다.

패키지의 설치 스크립트(예: preinstall 또는 postinstall)는 절대 실행되지 않으며 종속성은 가져오기 중에 설치되지 않습니다.

패키지가 package.json 옆에 지원되는 lockfile을 제공하면 Claude Code는 스크립트가 비활성화된 상태에서 별도의 단계로 해당 Node.js 패키지 종속성을 설치합니다. 그렇지 않으면 플러그인이 필요한 모든 것이 이미 빌드된 상태로 게시합니다. 다른 패키지가 필요한 MCP 서버는 npx를 통해 시작할 수 있으며, 이는 첫 실행 시 설치합니다.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

특정 버전에 고정하려면 version 필드를 추가합니다:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

개인 또는 내부 레지스트리에서 설치하려면 registry 필드를 추가합니다:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

Zip 아카이브

archive를 사용하여 Claude Code가 HTTPS를 통해 다운로드하는 zip 파일로 플러그인을 배포합니다. 따라서 사용자의 머신에 git 또는 npm 없이 설치가 작동합니다. S3 버킷, Artifactory 일반 저장소 또는 nginx와 같은 정적 파일 서버 또는 아티팩트 저장소에서 파일을 호스팅합니다. Claude Code v2.1.224 이상 필요합니다. v2.1.120부터 v2.1.223까지의 버전에서는 플러그인 설치가 This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.으로 실패합니다. 더 오래된 버전에서는 archive 항목을 포함하는 마켓플레이스가 완전히 로드되지 않습니다.

이 항목은 아티팩트 서버의 zip 파일에서 플러그인을 설치합니다:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

zip을 빌드할 때 플러그인의 내용을 직접 압축하거나 플러그인 폴더 자체를 압축할 수 있습니다. Claude Code는 아카이브의 맨 위에서 .claude-plugin/을 찾은 다음 단일 최상위 폴더 내에서 찾으므로 두 레이아웃 모두 설치됩니다:

my-plugin.zip          my-plugin.zip
├── .claude-plugin/    └── my-plugin/
│   └── plugin.json        ├── .claude-plugin/
└── commands/              │   └── plugin.json
                           └── commands/

Claude Code는 한 폴더보다 더 깊게 찾지 않으므로 더 아래에 중첩된 플러그인은 설치되지 않습니다. Claude Code는 256 MiB보다 큰 아카이브를 거부합니다.

정확한 파일을 고정하려면 아카이브의 다이제스트와 함께 sha256 필드를 추가합니다:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

다운로드된 파일이 핀과 일치하지 않으면 Claude Code는 설치를 거부하고 Plugin archive integrity check failed를 보고합니다.

아카이브 소스는 다음 필드를 허용합니다:

sha256 다이제스트는 plugin.json 또는 마켓플레이스 항목이 버전을 선언하지 않을 때 플러그인의 버전으로도 작동합니다. 버전 관리를 참조하세요. version을 선언하면 해당 버전 문자열이 업데이트 신호이므로 zip과 다이제스트를 변경한 후 버전도 범프하거나 사용자는 캐시된 복사본을 유지합니다.

아카이브 다운로드 인증

개인 레지스트리에서의 다운로드와 같은 아카이브 다운로드를 인증하려면 Claude Code가 이를 통해 보내는 HTTP 헤더를 설정합니다. extraKnownMarketplaces 항목과 같이 마켓플레이스를 등록한 url 소스에서 headers를 설정합니다. Claude Code v2.1.238 이상에서는 플러그인의 항목에서 source 옆에 설정할 수 있습니다.

headers에 넣을 값이 단기간인 경우(예: 레지스트리가 요청 시 발행하는 토큰) 대신 같은 위치에 headersHelper 명령어를 설정합니다. Claude Code는 명령어를 실행하고 인쇄하는 JSON 객체를 해당 위치의 헤더로 보냅니다. Claude Code v2.1.238 이상 필요합니다.

선택한 위치는 어느 다운로드가 헤더를 받고 Claude Code가 명령어를 실행할 때를 결정합니다:

두 위치 모두 동일한 이름의 헤더를 설정하면 Claude Code는 항목의 값을 보냅니다. 한 위치 내에서 명령어가 인쇄하는 헤더는 동일한 이름의 headers에 나열된 헤더를 재정의합니다.

플러그인 항목에 headersHelper 추가

이 항목은 source 옆에 headersHelper를 설정합니다. 또한 "strict": false를 설정하며, Claude Code는 headersHelper를 설정하는 marketplace.json 항목에 이를 요구합니다. "strict": false를 사용하면 마켓플레이스 항목이 플러그인의 전체 정의이므로 사용자는 명령어를 수락하기 전에 플러그인에 포함된 내용을 검토할 수 있습니다:

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "commands": "./commands",
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

항목을 확인하려면 claude plugin install my-plugin@your-marketplace를 실행합니다. Claude Code는 명령어와 아카이브 URL을 표시하고 수락 후 zip을 다운로드합니다.

v2.1.238 이전에는 Claude Code가 항목의 아카이브를 headers 또는 headersHelper 없이 다운로드했으므로 이들에 의존하는 설치가 HTTP 401 while downloading plugin archive from으로 실패했으며, 그 뒤에 URL이 있고 레지스트리의 상태 코드가 401 대신 있었습니다.

headersHelper 명령어 작성

마켓플레이스의 url 소스 또는 플러그인 항목에 headersHelper를 설정하든 명령어를 다음 요구 사항을 충족하도록 작성합니다:

• 명령어 텍스트: 최대 500자의 인쇄 가능한 ASCII. 4개 이상의 공백이 연속되지 않음.
• 출력: stdout에 헤더 이름과 문자열 값의 JSON 객체 하나를 인쇄한 후 10초 내에 종료 코드 0으로 종료합니다.
• 셸 및 작업 디렉터리: Claude Code는 구성 디렉터리(~/.claude 또는 CLAUDE_CONFIG_DIR)에서 sh 또는 Windows의 cmd.exe를 통해 명령어를 실행합니다. 상대 경로가 해당 디렉터리에 대해 해석되므로 절대 경로 또는 PATH의 명령어를 제공합니다. 사용자의 프로젝트가 아닙니다.
• Claude Code가 제거하는 변수: marketplace.json 항목 또는 프로젝트의 .claude/settings.json 또는 .claude/settings.local.json에 설정된 명령어의 환경에서 Claude Code는 TOKEN, SECRET, KEY 또는 AUTH와 같은 단어를 포함하는 이름의 모든 변수를 제거합니다. ANTHROPIC_API_KEY 포함. Claude Code는 사용자 설정, --settings 파일 또는 관리 설정에 설정된 명령어에 이 제거를 적용하지 않습니다.
• Claude Code가 설정하는 변수: url 소스의 명령어에 대해 CLAUDE_CODE_MARKETPLACE_URL 및 CLAUDE_CODE_MARKETPLACE_NAME. 항목의 명령어에 대해 CLAUDE_CODE_PLUGIN_NAME 및 CLAUDE_CODE_PLUGIN_ARCHIVE_URL. CLAUDE_CODE_MARKETPLACE_NAME은 사용자가 URL로 마켓플레이스를 추가한 후 첫 번째 가져오기에서 설정되지 않습니다. 해당 가져오기가 이름을 제공하기 때문입니다.

bearer 토큰을 발행하는 명령어는 다음과 같은 객체를 인쇄합니다:

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

Claude Code가 headersHelper 명령어를 건너뛰거나 출력을 삭제할 때

Claude Code는 headersHelper 명령어를 실행하지 않거나 headers 또는 명령어의 출력에서 온 헤더를 삭제합니다. 이러한 상황에서:

• 명령어 실패: 명령어가 0이 아닌 코드로 종료되거나 10초를 초과하거나 JSON 객체 이외의 것을 인쇄하면 Claude Code는 명령어를 실행한 가져오기 또는 다운로드를 수행하지 않습니다.
• 마켓플레이스 URL이 https://로 시작하지 않음: Claude Code는 해당 url 소스의 명령어를 실행하지 않고 headers 필드에 나열된 헤더만 보냅니다.
• 리디렉션이 원본을 벗어남: 다운로드가 아카이브 URL의 원본에서 리디렉션될 때 Claude Code는 마켓플레이스 url 소스와 플러그인 항목의 headers 값과 명령어 출력을 삭제합니다.
• 항목이 라우팅 또는 ID 헤더를 설정함: Claude Code는 항목의 headers 및 명령어 출력에서 Host, Cookie 및 X-Forwarded-*와 같은 요청 라우팅 및 클라이언트 ID 이름을 삭제하고 Authorization과 같은 인증 이름을 유지합니다. Claude Code는 모든 marketplace.json 항목을 이 방식으로 필터링하고 인라인 설정 항목은 어느 파일이 이를 선언하는지에 따라 다릅니다.
• --add-dir 디렉터리의 설정에 설정된 명령어: Claude Code는 이를 무시합니다. url 소스 및 인라인 플러그인 항목 모두에서 그리고 해당 파일의 headers만 보냅니다.
• 관리 설정이 명령어를 차단함: disableCommandPluginSources를 true로 설정하면 headersHelper 명령어를 차단하고 allowManagedHooksOnly도 disableCommandPluginSources가 명시적으로 false가 아닌 한 이들을 차단합니다. 두 차단 중 하나에서 Claude Code는 여전히 관리 설정 자체가 선언하는 마켓플레이스에 대해 명령어를 실행합니다.

사용자가 headersHelper 명령어를 수락하는 방법

사용자는 플러그인 항목의 명령어를 설치하거나 업데이트할 때마다 해당 플러그인 하나를 설치하거나 업데이트할 때마다 수락합니다. /plugin의 플러그인 자신의 보기에서 또는 claude plugin install 또는 claude plugin update를 사용합니다. Claude Code는 명령어와 아카이브 URL을 표시하고 사용자가 수락한 후에만 명령어를 실행합니다.

비대화형 셸에서 --yes를 전달하여 수락합니다. 이전 --json 실행이 표시한 명령어만 수락하려면 실행이 보고한 sha256과 함께 --accept-command를 전달합니다.

Claude Code는 표시한 명령어만 실행합니다. 표시한 아카이브 URL의 경우. 항목의 명령어 또는 아카이브 URL이 그 사이에 변경되면 Claude Code는 설치 또는 업데이트를 거부합니다. 쿼리 문자열만의 변경은 계산되지 않습니다.

명령어를 거부하는 대신 요청하지 않는 설치 및 업데이트

다른 작업에서 Claude Code는 항목의 명령어를 실행하거나 아카이브를 다운로드하지 않으므로 플러그인은 설치된 버전에 유지되거나 설치되지 않은 상태로 유지됩니다. 사용자가 보는 것은 작업에 따라 다릅니다:

• 여러 플러그인을 한 번에 설치하거나 플러그인 제안에서 또는 다른 플러그인의 종속성으로: Claude Code는 명령어가 있는 플러그인을 거부하고 사용자를 /plugin의 해당 플러그인 자신의 보기로 가리킵니다. 대량 설치의 다른 플러그인은 여전히 설치됩니다. 거부된 플러그인에 의존하는 플러그인은 사용자가 거부된 플러그인을 설치할 때까지 설치되지 않습니다.
• 백그라운드 자동 업데이트 또는 아카이브가 다운로드되지 않은 플러그인의 세션 시작: Claude Code는 /plugin 오류 탭에 플러그인을 나열하므로 사용자는 수동으로 설치하거나 업데이트해야 합니다. 설치된 버전을 찾는 자동 업데이트는 아무것도 나열하지 않습니다.

마켓플레이스 `url` 소스의 명령어가 실행될 때

마켓플레이스 url 소스의 headersHelper는 마켓플레이스가 게시하는 카탈로그가 아닌 설정 파일(예: extraKnownMarketplaces 항목)에 선언되므로 Claude Code는 각 설치 또는 업데이트에서 사용자에게 수락을 요청하지 않습니다. 이를 선언하는 설정 파일은 Claude Code가 실행할 때를 결정합니다:

-p 또는 SDK 세션에서 Claude Code는 보안 승인 대화를 표시할 수 없습니다. 다른 전달된 설정을 적용하지만 마켓플레이스 가져오기 및 명령어가 필요한 아카이브 다운로드는 사용자가 대화형 세션에서 승인할 때까지 실패합니다.

이러한 파일 중 하나의 인라인 플러그인 항목의 경우 Claude Code는 해당 파일의 마켓플레이스 수준 명령어와 동일한 폴더 신뢰 또는 설정 승인을 요구하며 사용자는 각 설치 또는 업데이트에서 항목의 명령어를 수락합니다.

명령어 소스

로컬로 설치된 도구가 플러그인 디렉터리를 생성할 때 command를 사용합니다. 예를 들어 현재 선택된 도구 체인에 대해 플러그인을 렌더링하는 IDE. Claude Code는 사용자가 플러그인을 설치할 때 명령어를 실행하고 백그라운드에서 세션당 한 번 다시 실행하므로 사용자는 도구의 변경된 출력을 다시 설치하지 않고 선택합니다. Claude Code v2.1.229 이상 필요합니다. v2.1.120부터 v2.1.228까지에서는 플러그인 설치가 This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.으로 실패하고 더 오래된 버전에서는 전체 마켓플레이스가 로드되지 않습니다.

이 항목은 도구가 인쇄하는 모든 디렉터리에서 플러그인을 설치합니다:

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

Claude Code는 사용자의 홈 디렉터리에서 플랫폼 셸(macOS 및 Linux의 sh 또는 Windows의 cmd.exe)을 통해 명령어를 실행합니다. 명령어는 stdout에 정확히 한 줄을 인쇄하고 코드 0으로 종료해야 합니다. 해당 줄은 명령어가 종료될 때까지 완전한 플러그인을 포함하는 디렉터리의 절대 경로이며 경로는 실행 간에 변경될 수 있습니다.

Claude Code는 timeout 초보다 오래 실행되는 명령어를 중지하고 설치 또는 업데이트가 실패합니다. Claude Code는 또한 이러한 경우에 인쇄된 경로를 거부하고 설치 또는 업데이트가 동일한 방식으로 실패합니다:

• 디렉터리의 최상위 수준에 플러그인 콘텐츠가 없습니다. 예를 들어 .claude-plugin/ 디렉터리 또는 skills/, commands/, agents/ 또는 hooks/ 디렉터리
• 디렉터리는 Claude Code가 시작된 디렉터리 또는 그 부모 중 하나입니다
• Windows에서 경로는 UNC 경로입니다

명령어 소스는 다음 필드를 허용합니다:

복사 모드 및 링크 모드

기본 "mode": "copy"를 사용하면 Claude Code는 인쇄된 디렉터리를 버전 관리 플러그인 캐시에 복사하고 디렉터리 내용의 해시에서 플러그인 버전을 파생합니다. 도구는 명령어가 종료된 후 디렉터리를 삭제하거나 다시 쓸 수 있으며 동일한 내용을 생성하는 다시 실행은 최신 상태로 계산됩니다. Claude Code는 256 MiB보다 크거나 20,000개 이상의 항목을 포함하는 디렉터리 설치를 거부합니다.

렌더링된 SDK 내보내기와 같이 복사되지 않아야 하는 대규모 플러그인 디렉터리에 대해 "mode": "link"를 설정합니다. Claude Code는 인쇄된 디렉터리의 각 최상위 항목에 대한 링크로 플러그인의 캐시 항목을 채우고 제자리에서 파일을 사용하므로 아무것도 복사되지 않고 파일 내용이 해시되지 않으며 크기 제한이 적용되지 않습니다. 최상위 항목이 인쇄된 디렉터리 외부를 가리키는 심볼릭 링크인 경우 설치가 실패합니다. Claude Code는 또한 링크 모드 플러그인에 대해 Node.js 패키지 종속성 설치를 건너뛰므로 플러그인이 필요한 모든 node_modules을 이미 포함하는 디렉터리를 인쇄합니다.

플러그인이 설치된 상태로 유지되는 동안 인쇄된 디렉터리를 제자리에 유지합니다. Claude Code는 모든 시작 시 해당 링크를 통해 플러그인을 로드하기 때문입니다. Claude Code는 파일 내부가 아닌 인쇄된 디렉터리의 실제 경로 및 최상위 항목에서 플러그인 버전을 파생합니다. 따라서 새 콘텐츠를 신호하려면 다른 경로를 인쇄합니다. 인쇄된 디렉터리 또는 그 아래 어디서나 시작된 세션에서 Claude Code는 플러그인을 로드하지 않습니다.

Claude Code는 Windows에서 링크 모드를 지원하지 않으며 거기에 링크 모드 플러그인 설치를 거부합니다. 대신 "mode": "copy"를 선언합니다.

사용자가 명령어를 수락하는 방법

Claude Code는 사용자의 머신에서 명령어를 실행하므로 모든 실행을 사용자의 명시적 수락에 바인딩합니다:

• 사용자가 /plugin의 세부 정보 화면에서 플러그인을 설치하거나 대화형 터미널에서 claude plugin install 또는 claude plugin update를 사용하여 설치하거나 업데이트할 때 Claude Code는 먼저 정확한 명령어 문자열을 표시하고 해당 설치에 대해 수락된 명령어를 기록합니다. 동일한 명령어의 수락으로 진행할 수 있는 claude plugin update는 아무것도 표시하지 않습니다.
• 비대화형 셸(예: 프로비저닝 스크립트)에서 claude plugin install 또는 claude plugin update에 --yes를 전달하여 인쇄하는 명령어를 수락합니다. 이전 --json 실행이 표시한 명령어만 수락하려면 실행이 보고한 sha256과 함께 --accept-command를 전달합니다.
• 다른 모든 경로는 사용자가 이미 수락한 명령어만 실행합니다. 여기에는 /plugin에서 시작된 업데이트 및 Claude Code가 명령어를 다시 실행할 때에 설명된 백그라운드 실행이 포함됩니다. 아무것도 수락되지 않으면 Claude Code는 명령어 실행을 거부하고 사용자에게 검토 방법을 알려줍니다. Claude Code는 다른 플러그인의 종속성으로 명령어 소스 플러그인을 설치하지 않으므로 사용자는 먼저 설치합니다.
• 항목의 command를 변경하거나 mode를 전환하면 사용자는 이미 가진 버전을 유지하고 Claude Code는 명령어 다시 실행을 중지합니다. 대화형 세션에서 /plugin 오류 탭은 사용자가 claude plugin update <plugin>@<marketplace>를 실행하여 검토하고 수락할 때까지 새 명령어를 표시합니다.

관리자는 관리 설정 disableCommandPluginSources를 사용하여 조직 전체에서 명령어 소스를 차단할 수 있습니다. 조직이 allowManagedHooksOnly를 설정하면 Claude Code는 기본적으로 명령어 소스를 차단합니다.

Claude Code가 명령어를 다시 실행할 때

인쇄된 디렉터리는 명령어가 실행된 시점의 도구 상태를 반영하므로 Claude Code는 다음 시간에 명령어를 다시 실행합니다:

• 사용자가 플러그인을 설치하거나 업데이트할 때마다
• 활성화된 각 명령어 소스 플러그인에 대해 세션당 한 번. 백그라운드에서 세션이 시작된 직후. 이 실행은 마켓플레이스 자동 업데이트를 거치지 않으므로 마켓플레이스의 자동 업데이트 설정에 따라 다르지 않습니다
• 시작 또는 /reload-plugins에서 활성화된 플러그인의 설치된 버전이 플러그인 캐시에서 누락된 경우

사용자가 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC를 설정하면 Claude Code는 두 백그라운드 실행을 건너뜁니다. 명시적 설치 및 업데이트는 여전히 해당 변수 집합으로 명령어를 실행합니다.

명령어의 해시된 출력이 변경되면 Claude Code는 결과를 새 버전으로 설치하고 실행 중인 대화형 세션에서 다시 로드합니다. /reload-plugins가 전환하는 동일한 구성 요소를 전환합니다. 사용자는 플러그인이 다시 로드되었다는 알림을 봅니다. 제자리에서 다시 로드하면 세션의 프롬프트 캐시가 무효화되면 Claude Code는 대신 사용자에게 /reload-plugins를 실행하도록 요청합니다. 이는 캐시 비용에 대해 경고하고 --force로 다시 실행할 때 적용됩니다.

고급 플러그인 항목

이 예제는 명령어, 에이전트, hooks 및 MCP 서버의 사용자 정의 경로를 포함하여 많은 선택적 필드를 사용하는 플러그인 항목을 보여줍니다:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

주목할 주요 사항:

• commands 및 agents: 여러 디렉터리 또는 개별 파일을 지정할 수 있습니다. 경로는 플러그인 루트에 상대적이며 그 내에 유지되어야 합니다.
  • Claude Code는 ./../shared.md와 같이 플러그인 디렉터리 외부로 해석되는 경로를 path escapes plugin directory 오류로 거부하고 여전히 해당 구성 요소 없이 플러그인을 로드합니다
• ${CLAUDE_PLUGIN_ROOT}: hook 명령어 및 MCP 서버 구성에서 이 변수를 사용하여 플러그인의 설치 디렉터리 내의 파일을 참조합니다.
  • 서버 유형별로 어느 구성 필드가 이를 대체하는지에 대한 대체 테이블을 참조하세요
  • 플러그인 업데이트를 통해 유지되어야 하는 종속성 또는 상태의 경우 ${CLAUDE_PLUGIN_DATA}를 대신 사용합니다
• strict: false: 이것이 false로 설정되어 있으므로 플러그인은 자신의 plugin.json이 필요하지 않습니다. 마켓플레이스 항목이 모든 것을 정의합니다. 아래의 Strict 모드를 참조하세요.

기본적으로 플러그인의 skills는 해당 source 아래의 skills/ 디렉터리에서 로드됩니다. skills 필드에 나열된 경로는 해당 스캔에 추가됩니다:

"skills": ["./skills/", "./extra-skills/"]

여러 플러그인 항목이 마켓플레이스 루트(source: "./")에서 하나의 skills/ 폴더를 공유할 때 각 항목이 자신의 skills만 로드하도록 특정 하위 디렉터리를 대신 나열합니다:

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

마켓플레이스 루트 source를 사용하면 나열된 경로가 해당 항목의 완전한 집합이 되며, 공유된 skills/ 폴더의 다른 디렉터리는 로드되지 않습니다. ./skills/ 자체 또는 플러그인 루트를 나열하면 전체 스캔이 유지됩니다. 나열된 경로 중 어느 것도 존재하지 않으면 기본 스캔이 대신 실행됩니다.

Strict 모드

strict 필드는 plugin.json이 구성 요소 정의(skills, 에이전트, hooks, MCP 서버, 출력 스타일)의 권한인지 여부를 제어합니다.

각 모드를 사용할 때:

• strict: true: 플러그인은 자신의 plugin.json을 가지고 있으며 자신의 구성 요소를 관리합니다. 마켓플레이스 항목은 맨 위에 추가 skills 또는 hooks를 추가할 수 있습니다. 이것이 기본값이며 대부분의 플러그인에서 작동합니다.
• strict: false: 마켓플레이스 운영자가 완전한 제어를 원합니다. 플러그인 저장소는 원본 파일을 제공하고 마켓플레이스 항목은 이러한 파일 중 어느 것이 skills, 에이전트, hooks 등으로 노출되는지 정의합니다. 마켓플레이스가 플러그인 작성자의 의도와 다르게 플러그인의 구성 요소를 재구성하거나 큐레이션할 때 유용합니다.

마켓플레이스 호스팅 및 배포

사용자가 git 저장소에서 호스팅되는 마켓플레이스를 추가하거나 이를 나열하는 git 기반 플러그인을 설치할 때 Claude Code는 해당 마켓플레이스 또는 플러그인 저장소를 사용자의 머신에 복제합니다. 복제는 Git LFS 콘텐츠를 다운로드하지 않으므로 LFS 추적 파일은 포인터 파일로 도착합니다. 플러그인이 필요한 파일을 LFS 외부에 유지하세요.

GitHub에서 호스팅(권장)

GitHub는 마켓플레이스를 호스팅하고 배포하는 권장 방법입니다:

1. 저장소 생성: 마켓플레이스를 위한 새 저장소 설정
2. 마켓플레이스 파일 추가: 플러그인 정의와 함께 .claude-plugin/marketplace.json 생성
3. 팀과 공유: 사용자가 /plugin marketplace add owner/repo로 마켓플레이스를 추가합니다

이점: 기본 제공 버전 제어, 문제 추적 및 팀 협업 기능.

다른 git 서비스에서 호스팅

GitLab, Bitbucket 및 자체 호스팅 서버와 같은 모든 git 호스팅 서비스가 작동합니다. 사용자는 전체 저장소 URL로 추가합니다:

/plugin marketplace add https://gitlab.com/company/plugins.git

개인 저장소

Claude Code는 개인 저장소에서 플러그인 설치를 지원합니다. 조직 설정 > 플러그인을 통해 마켓플레이스를 배포하는 경우 git 자격 증명이 관련되지 않습니다. 조직 동기화는 조직의 GitHub 또는 GitLab 연결을 통해 claude.ai에서 마켓플레이스 저장소를 읽습니다. 개인 플러그인 소스가 될 수 있는 항목은 조직 설정을 통해 배포를 참조하세요.

실행하는 명령어

/plugin marketplace add, /plugin install, /plugin update 또는 /plugin marketplace update를 실행할 때 Claude Code는 기존 git 자격 증명 도우미를 사용하므로 gh auth login, macOS Keychain 또는 git-credential-store를 통한 HTTPS 액세스는 터미널에서와 동일하게 작동합니다. SSH 액세스는 호스트가 이미 known_hosts 파일에 있고 키가 ssh-agent에 로드되어 있는 한 작동합니다. Claude Code는 호스트 지문 및 키 암호에 대한 대화형 SSH 프롬프트를 억제하기 때문입니다. GitHub owner/repo 단축 소스는 기본적으로 SSH를 통해 복제합니다. 대신 HTTPS를 통해 복제하려면 CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1을 설정합니다.

백그라운드 자동 업데이트

백그라운드 새로고침은 마켓플레이스의 원격에서 새 커밋을 확인할 때 구성된 git 자격 증명 도우미를 사용합니다. 실행하는 명령어와 동일합니다. SSH 원격의 경우 ssh-agent에 로드된 키가 확인을 인증합니다. Claude Code는 확인을 비대화형으로 실행합니다. git의 터미널 프롬프트 및 askpass 프로그램을 끄고 자격 증명 도우미에 프롬프트하지 않도록 지시합니다. 확인이 HTTPS를 통해 개인 저장소에 인증할 수 있는지 여부는 도우미에 따라 다릅니다:

• 프롬프트 없이 저장된 자격 증명을 제공할 수 있는 도우미는 확인을 인증합니다. Git Credential Manager, macOS Keychain 도우미 및 git-credential-store는 호스트에 대한 자격 증명을 보유하면 이런 식으로 작동합니다.
• 프롬프트가 필요한 도우미는 백그라운드에서 응답할 수 없습니다. 업데이트가 조용히 실패하고 기존 체크아웃이 제자리에 유지되므로 플러그인은 마지막 동기화된 상태에서 계속 작동합니다. /plugin marketplace update <name>을 실행하여 자격 증명으로 마켓플레이스를 새로고칩니다.

확인이 체크아웃이 최신 상태임을 발견하면 Claude Code는 그대로 둡니다. 확인이 새 커밋을 발견하거나 원격에 도달하거나 인증할 수 없어서 실패하면 Claude Code는 마켓플레이스를 다시 복제하고 새 복제본으로 교체합니다. 해당 복제가 실패하면 기존 체크아웃이 제자리에 유지됩니다. 다시 복제는 대규모 저장소에서 시간 초과될 수 있습니다.

두 가지 설정이 개인 마켓플레이스를 예측 가능하게 작동하게 합니다:

• CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1을 설정하여 백그라운드 확인이 원격에 도달하거나 인증할 수 없을 때 다시 복제를 시도하지 않고 기존 체크아웃을 유지합니다. 플러그인은 마지막 동기화된 상태에서 계속 작동하며 /plugin marketplace update를 사용한 수동 업데이트는 여전히 자격 증명으로 인증합니다.
• git 자격 증명 도우미를 구성합니다. 예를 들어 GitHub의 경우 gh auth setup-git을 사용하여 백그라운드 확인과 다시 복제가 프롬프트 없이 인증할 수 있습니다.

GITHUB_TOKEN과 같은 공급자 토큰을 환경에서 설정하는 것만으로는 백그라운드 인증을 활성화하지 않습니다. 토큰은 구성된 자격 증명 도우미(예: GH_TOKEN 및 GITHUB_TOKEN을 읽는 gh CLI의 도우미)를 통해서만 적용됩니다.

조직 설정을 통해 배포

Team 또는 Enterprise 플랜에서 조직 설정 > 플러그인을 통해 플러그인을 배포하는 경우 다음 소스 규칙이 적용됩니다:

• github.com 및 gitlab.com에서 마켓플레이스 저장소는 개인 또는 내부여야 합니다. 조직 동기화는 호스트와 일치하는 연결을 통해 저장소를 읽습니다:
  • github.com: Claude GitHub App
  • GitHub Enterprise Server 호스트: 조직의 GitHub Enterprise App
  • gitlab.com 또는 자체 관리 GitLab 인스턴스: 조직의 GitLab 구성의 해당 호스트에 대한 액세스 토큰
• 각 플러그인 소스는 github, url 또는 git-subdir 유형이거나 ./로 시작하는 상대 경로여야 합니다. metadata.pluginRoot 아래에 bare name으로 플러그인을 나열하면 조직 동기화가 이를 지원되지 않는 소스로 거부하므로 경로를 명시적으로 작성합니다(예: ./plugins/deploy-tools).
• 플러그인 소스는 세 가지 경우에 개인일 수 있습니다:
  • 마켓플레이스 저장소의 소유자를 공유하는 github.com 소스
  • GHE App이 저장소에 설치된 조직의 GitHub Enterprise 호스트의 소스
  • 마켓플레이스 저장소와 동일한 GitLab 호스트의 url 또는 git-subdir 소스. gitlab.com에서 소스는 마켓플레이스 저장소와 동일한 최상위 그룹 또는 사용자 네임스페이스 아래에 있어야 합니다.
• 다른 모든 플러그인 소스는 github.com, gitlab.com 또는 bitbucket.org의 공개 저장소여야 하며, 조직 동기화는 자격 증명 없이 가져옵니다. 조직 동기화는 이러한 규칙이 적용되지 않는 호스트의 플러그인 소스를 거부합니다.

관리 워크플로우는 조직을 위한 플러그인 관리를 참조하세요.

개인 플러그인을 포함하려면 플러그인 폴더를 마켓플레이스 저장소 내에 배치하고 상대 경로로 참조합니다. 조직 동기화는 배포 중에 각 플러그인을 패키징하므로 사용자는 별도의 소스 저장소에 액세스할 필요가 없습니다.

예를 들어 이 marketplace.json 플러그인 항목은 마켓플레이스 저장소의 plugins/deploy-tools에 커밋한 플러그인을 참조합니다:

{
  "name": "deploy-tools",
  "source": "./plugins/deploy-tools"
}

GitLab 호스팅 마켓플레이스 동기화

gitlab.com 또는 자체 관리 GitLab 인스턴스에서 마켓플레이스를 동기화하려면 Owner가 먼저 조직 설정 > Claude Code에서 해당 호스트에 대한 GitLab 구성을 추가합니다. GitLab 구성은 공개 베타 상태이며 플러그인 마켓플레이스 동기화에만 적용됩니다. 하나를 추가해도 웹의 Claude Code에서 GitLab 저장소를 사용할 수 없습니다. 설정 단계는 조직을 위한 플러그인 관리를 참조하세요.

마켓플레이스를 추가할 때 프로젝트의 HTTPS URL(예: https://gitlab.example.com/platform/claude-plugins)을 입력합니다. 중첩된 하위 그룹의 프로젝트가 작동합니다. 조직 동기화는 프로젝트의 기본 분기를 읽습니다. 자동으로 동기화를 켜면 기본 분기에 대한 푸시만 동기화를 시작합니다.

최상위 bin 디렉터리에서 실행 파일 제외

조직 설정을 통해 배포하는 모든 플러그인에 최상위 bin/ 디렉터리를 포함하지 마세요. claude.ai는 마켓플레이스 동기화 또는 직접 업로드를 통해 플러그인이 도착하는지 여부에 관계없이 하나를 가진 플러그인을 거부합니다:

• 마켓플레이스 동기화: 조직 동기화는 해당 플러그인을 거부하고 나머지 마켓플레이스를 동기화합니다. 오류 메시지는 Plugin contains a top-level bin/ directory로 시작합니다.
• 직접 업로드: 조직 설정 > 플러그인에서 플러그인을 업로드하는 경우 claude.ai는 동일한 메시지로 업로드를 거부합니다.

실행 파일을 scripts/와 같은 다른 디렉터리에 유지하고 skills, hooks 또는 MCP 서버 구성에서 ${CLAUDE_PLUGIN_ROOT}/scripts/<name>으로 참조합니다.

팀을 위한 마켓플레이스 필수

프로젝트 폴더를 신뢰할 때 Claude Code가 팀 구성원을 위해 마켓플레이스를 추가하도록 저장소를 구성할 수 있습니다. 별도의 프롬프트 없이 마켓플레이스를 .claude/settings.json에 추가합니다:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

기본적으로 활성화해야 하는 플러그인을 지정할 수도 있습니다:

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

전체 구성 옵션은 플러그인 설정을 참조하세요.

컨테이너에 대한 플러그인 사전 채우기

컨테이너 이미지 및 CI 환경의 경우 빌드 시간에 플러그인 디렉터리를 사전 채우므로 Claude Code가 런타임에 아무것도 복제하지 않고도 마켓플레이스 및 플러그인이 이미 사용 가능한 상태로 시작됩니다. CLAUDE_CODE_PLUGIN_SEED_DIR 환경 변수를 이 디렉터리를 가리키도록 설정합니다.

여러 시드 디렉터리를 계층화하려면 Unix에서는 :로, Windows에서는 ;로 경로를 구분합니다. Claude Code는 각 디렉터리를 순서대로 검색하고 주어진 마켓플레이스 또는 플러그인 캐시를 포함하는 첫 번째 시드를 사용합니다.

시드 디렉터리는 ~/.claude/plugins의 구조를 미러링합니다:

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

시드 디렉터리를 구축하려면 이미지 빌드 중에 Claude Code를 한 번 실행하고, 필요한 플러그인을 설치한 다음, 결과 ~/.claude/plugins 디렉터리를 이미지에 복사하고 CLAUDE_CODE_PLUGIN_SEED_DIR을 가리킵니다.

복사 단계를 건너뛰려면 빌드 중에 CLAUDE_CODE_PLUGIN_CACHE_DIR을 대상 시드 경로로 설정하여 플러그인이 직접 설치되도록 합니다:

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

그런 다음 런타임 환경에서 CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed를 설정하여 Claude Code가 시작 시 시드에서 읽도록 합니다.

시작 시 Claude Code는 시드의 known_marketplaces.json에서 찾은 마켓플레이스를 기본 구성에 등록하고 cache/ 아래에서 찾은 플러그인 캐시를 다시 복제하지 않고 사용합니다. 이는 대화형 모드와 -p 플래그를 사용한 비대화형 모드 모두에서 작동합니다.

동작 세부 정보:

• 읽기 전용: Claude Code는 시드 디렉터리에 절대 쓰지 않습니다.
• 자동 업데이트 비활성화: 시드 마켓플레이스는 자동 업데이트되지 않습니다.
• 시드 항목이 우선합니다: 시드에서 선언된 마켓플레이스는 각 시작 시 사용자 구성의 일치하는 항목을 덮어씁니다. 시드 플러그인을 거부하려면 마켓플레이스를 제거하는 대신 /plugin disable을 사용합니다.
• 경로 해석: Claude Code는 시드의 JSON 내에 저장된 경로를 신뢰하지 않고 런타임에 $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/을 탐색하여 마켓플레이스 콘텐츠를 찾습니다. 이는 시드가 빌드된 위치와 다른 경로에 마운트된 경우에도 시드가 올바르게 작동함을 의미합니다.
• 변경 차단: 시드 관리 마켓플레이스에 대해 /plugin marketplace remove 또는 /plugin marketplace update를 실행하면 시드 이미지를 업데이트하도록 관리자에게 문의하라는 지침과 함께 실패합니다.
• 설정과 구성: extraKnownMarketplaces 또는 enabledPlugins이 시드에 이미 존재하는 마켓플레이스를 선언하면 Claude Code는 복제하는 대신 시드 복사본을 사용합니다.

관리되는 마켓플레이스 제한

플러그인 소스에 대한 엄격한 제어가 필요한 조직의 경우 관리자는 관리되는 설정에서 strictKnownMarketplaces 설정을 사용하여 사용자가 추가할 수 있는 플러그인 마켓플레이스를 제한할 수 있습니다. 단일 실행을 위해 플러그인, 에이전트 및 MCP 서버를 사이드로드하는 CLI 플래그를 거부하려면 disableSideloadFlags와 쌍을 이룹니다. 컨텍스트 설치 제안으로 나타날 수 있는 마켓플레이스의 플러그인을 허용 목록으로 지정하려면 pluginSuggestionMarketplaces를 설정합니다.

strictKnownMarketplaces는 플러그인이 오는 마켓플레이스와 일치하므로 사용자는 여전히 허용된 마켓플레이스에서 command 소스를 가진 플러그인을 설치할 수 있습니다. 명령 소스도 차단하려면 disableCommandPluginSources를 설정합니다.

strictKnownMarketplaces가 관리되는 설정에서 구성되면 제한 동작은 값에 따라 달라집니다:

일반적인 구성

공식 Anthropic 마켓플레이스를 포함한 모든 마켓플레이스 추가 비활성화:

{
  "strictKnownMarketplaces": []
}

Claude Code는 claude.ai에서 동기화된 플러그인을 마켓플레이스가 아닌 계정에서 다운로드하므로 이 잠금은 이를 포함하지 않습니다. 이를 중지하려면 관리되는 설정에서 syncClaudeAiPlugins를 false로 설정하거나 claude.ai에서 조직의 Skills를 끕니다.

공식 Anthropic 마켓플레이스만 허용합니다. 단일 저장소 항목에 대한 일치는 정확하므로 이 항목은 동일한 저장소의 ref 또는 path 변형을 포함하지 않습니다:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "anthropics/claude-plugins-official"
    }
  ]
}

이 항목을 사용하면 Claude Code는 이미 등록된 공식 마켓플레이스를 사용 가능하게 유지하고 새 머신에서 Claude Code를 처음 대화형으로 시작할 때 마켓플레이스를 자동으로 등록합니다.

자동 등록은 모든 머신을 포함하지 않습니다. 가장 일반적으로 누락되는 경우:

• 머신의 첫 번째 대화형 시작 전에 실행되는 비대화형 환경.
• 마켓플레이스를 차단한 정책(예: 빈 배열 잠금)에서 Claude Code가 이미 대화형으로 실행된 머신. Claude Code는 차단된 시도를 기록하고 정책이 변경된 후 다시 시도하지 않습니다.

이러한 머신에서 동일한 managed-settings.json의 extraKnownMarketplaces에 마켓플레이스를 추가하여 Claude Code가 자동으로 등록하도록 하거나 claude plugin marketplace add anthropics/claude-plugins-official을 실행합니다.

특정 마켓플레이스만 허용:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

owner-wildcard 항목을 사용하여 GitHub 조직 아래의 모든 마켓플레이스 저장소를 허용합니다. Owner 와일드카드는 Claude Code v2.1.223 이상이 필요합니다.

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/*"
    }
  ]
}

호스트에 대한 정규식 패턴 일치를 사용하여 내부 git 서버의 모든 마켓플레이스 허용. 이는 GitHub Enterprise Server 또는 자체 호스팅 GitLab 인스턴스에 권장되는 방법입니다:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

경로에 대한 정규식 패턴 일치를 사용하여 특정 디렉터리의 파일 시스템 기반 마켓플레이스 허용:

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

pathPattern으로 모든 파일 시스템 경로를 허용하면서 hostPattern으로 네트워크 소스를 제어하려면 ".*"를 pathPattern으로 사용합니다.

제한 작동 방식

제한은 네트워크 또는 파일 시스템 작업이 발생하기 전에 확인됩니다. 확인은 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트 시 실행됩니다. 마켓플레이스가 정책 구성 전에 추가되었고 해당 소스가 더 이상 허용 목록과 일치하지 않으면 Claude Code는 해당 마켓플레이스에서 플러그인을 설치하거나 업데이트하기를 거부합니다. 동일한 적용이 blockedMarketplaces에도 적용됩니다.

두 목록이 적용되는 위치는 설정 위치에 따라 다릅니다:

• Claude.ai 관리 콘솔: Claude Code는 서버 관리 설정을 읽는 세션에서 두 목록을 모두 적용합니다. claude.ai는 또한 조직의 누군가가 claude.ai에서 git 저장소의 새 마켓플레이스를 추가하거나 Claude Desktop 앱의 Code 탭 외부에서 사용자 정의에서 추가할 때 이를 확인합니다. 이는 구성원이 자신의 계정을 위해 추가한 마켓플레이스와 조직 설정 > 플러그인 아래의 전체 조직을 위해 추가된 마켓플레이스를 포함합니다. claude.ai는 허용 목록이 허용하지 않거나 차단 목록이 명명하는 저장소를 거부합니다. 목록을 설정하기 전에 두 위치 중 하나에서 추가된 마켓플레이스를 다시 확인하지 않으며 업로드된 플러그인을 확인하지 않습니다.
• 관리 설정 파일, OS 수준 정책 또는 기타 관리 소스: Claude Code는 해당 소스를 읽는 위치에서 두 목록을 모두 적용합니다. claude.ai는 이를 읽지 않습니다.

GitHub 소유자 아래의 모든 마켓플레이스 저장소를 차단하려면 blockedMarketplaces 항목에서 owner-wildcard 형식을 사용합니다: { "source": "github", "repo": "untrusted-org/*" }. Claude Code v2.1.223 이상이 필요합니다. 일치 규칙(차단 목록과 허용 목록 간에 다름)은 Owner 와일드카드를 참조하세요.

사용자가 Claude Code가 복제하는 https:// 저장소 URL(예: 단순 github.com 또는 gitlab.com 저장소 URL)을 추가할 때 Claude Code는 blockedMarketplaces의 url 항목에 대해서도 확인합니다. Claude Code는 항목이 동일한 URL을 명명하면 추가를 차단합니다. 해당 비교에서 Claude Code는 .git 접미사 및 사용자가 # 뒤에 추가하는 모든 ref를 무시합니다. Claude Code v2.1.232 이상이 필요합니다. v2.1.232 이전에는 Claude Code가 호스팅된 marketplace.json 파일로 가져온 URL에 대해서만 url 항목과 일치했습니다.

허용 목록은 owner-wildcard github 항목을 제외하고 대부분의 소스 유형에 대해 정확한 일치를 사용합니다. 마켓플레이스가 허용되려면 지정된 모든 필드가 일치해야 합니다:

• GitHub 소스의 경우: repo는 필수이며 단일 저장소를 명명하거나 owner-wildcard 형식 owner/*를 사용하여 해당 소유자 아래의 모든 저장소를 포함합니다. 와일드카드 항목이 일치하는 방식(대소문자 규칙 포함)은 Owner 와일드카드를 참조하세요. 단일 저장소 항목의 경우 ref는 정확히 일치하거나 마켓플레이스 소스 및 허용 목록 항목 모두에서 없어야 하며 동일한 규칙이 path에 적용됩니다
• URL 소스의 경우: 전체 URL이 정확히 일치해야 합니다
• hostPattern 소스의 경우: 마켓플레이스 호스트가 정규식 패턴과 일치합니다
• pathPattern 소스의 경우: 마켓플레이스의 파일 시스템 경로가 정규식 패턴과 일치합니다

허용 목록의 정확한 일치는 후행 슬래시, .git 접미사 또는 ssh:// 및 https:// 체계만 다른 URL을 다른 값으로 취급합니다. 조직의 마켓플레이스를 둘 이상의 URL 형식으로 복제할 수 있는 경우 https://, ssh:// 및 user@host:path 형식이 모두 일치하도록 리터럴 URL보다 hostPattern 항목을 선호합니다.

claude.ai에서 호스팅되는 마켓플레이스는 호스트로 일치합니다: claude.ai와 일치하는 hostPattern 항목은 strictKnownMarketplaces 및 blockedMarketplaces에서 이를 관리합니다. 허용 목록에서 이러한 항목은 구성원의 개인 claude.ai 업로드를 허용하지 않습니다. Claude Code v2.1.273 이상이 필요합니다.

strictKnownMarketplaces는 관리되는 설정에서 설정되므로 개별 사용자 및 프로젝트 구성은 이러한 제한을 재정의할 수 없습니다.

전체 구성 세부 정보(지원되는 모든 소스 유형 및 extraKnownMarketplaces와의 비교 포함)는 strictKnownMarketplaces 참조를 참조하세요.

버전 해석 및 릴리스 채널

플러그인 버전은 캐시 경로 및 업데이트 감지를 결정합니다. 해석된 버전이 사용자가 이미 가지고 있는 것과 일치하면 /plugin update 및 자동 업데이트는 플러그인을 건너뜁니다. git 기반 소스의 경우 version을 생략하면 Claude Code는 소스의 해석된 커밋 SHA를 사용하므로 사용자는 해당 커밋이 변경될 때마다 업데이트를 받습니다. 이는 내부 또는 활발하게 개발 중인 플러그인에 대한 가장 간단한 설정입니다. 전체 해석 순서(예: archive 소스 포함)는 버전 관리를 참조하세요.

릴리스 채널 설정

플러그인에 대한 "stable" 및 "latest" 릴리스 채널을 지원하려면 동일한 저장소의 다양한 refs 또는 SHA를 가리키는 두 개의 마켓플레이스를 설정할 수 있습니다. 그런 다음 관리되는 설정을 통해 각 사용자 그룹에 자신의 마켓플레이스를 제공할 수 있습니다:

• 각 그룹의 장치에 별도의 엔드포인트 관리 설정(예: 관리 설정 파일 또는 MDM 프로필)을 배포합니다. Claude Code가 관리되는 소스를 결합하는 방식은 그룹별 파일 또는 프로필이 마켓플레이스를 읽는 장치에도 적용되는지 여부를 나타냅니다.
• 그룹당 하나의 Claude 앱 게이트웨이 정책을 정의합니다. 게이트웨이는 일치 규칙이 사용자에게 맞는 첫 번째 정책을 적용하므로 각 사용자가 자신의 그룹 정책에 도달하도록 정책을 정렬합니다. 그룹 정책의 extraKnownMarketplaces는 catch-all 정책의 맵과 병합하지 않고 대체하므로 그룹이 필요한 모든 마켓플레이스를 그룹의 정책에 나열합니다.

관리 콘솔의 서버 관리 설정은 조직의 모든 사용자에게 적용되므로 그룹별 할당을 수행할 수 없습니다.

예제

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

사용자 그룹에 채널 할당

릴리스 채널 설정 아래에 설명된 그룹별 엔드포인트 관리 설정 또는 게이트웨이 정책을 통해 각 마켓플레이스를 적절한 사용자 그룹에 할당합니다. 예를 들어 stable 그룹은 다음을 받습니다:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

early-access 그룹은 대신 latest-tools를 받습니다:

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

의존성 버전 고정

플러그인은 의존성에 대한 semver 범위를 제한하여 의존성 업데이트가 종속 플러그인을 손상시키지 않도록 할 수 있습니다. {plugin-name}--v{version} git 태그 규칙, 범위 구문 및 동일한 의존성에 대한 여러 제약 조건이 어떻게 결합되는지에 대해서는 플러그인 의존성 버전 제한을 참조하세요.

플러그인 이름 바꾸기 또는 제거

플러그인의 name은 안정적인 식별자입니다. 사용자는 enabledPlugins, pluginConfigs 및 /plugin install 명령에서 이를 참조하므로 변경하면 모든 기존 설치가 손상됩니다. UI에 표시되는 레이블을 설치를 손상시키지 않고 변경하려면 displayName을 설정하고 name을 변경하지 않은 상태로 유지합니다.

플러그인의 name을 변경하거나 plugins 배열에서 플러그인을 제거해야 하는 경우 최상위 renames 항목을 추가하여 기존 사용자가 plugin-not-found 오류를 보는 대신 마이그레이션하도록 합니다. 자동 마이그레이션에는 Claude Code v2.1.193 이상이 필요합니다. 각 이전 이름을 현재 이름으로 매핑하거나 플러그인이 더 이상 존재하지 않으면 null로 매핑합니다. 다음 예제는 formatter를 code-formatter로 이름을 바꾸고 legacy-linter가 제거되었음을 기록합니다:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

사용자가 설정에 여전히 이전 이름이 있는 상태로 Claude Code를 시작하면 Claude Code는 renames 맵을 따릅니다:

• 항목이 새 이름을 가리키면 Claude Code는 플러그인을 새 이름으로 로드하고 "acme-tools" 마켓플레이스에서 "code-formatter"로 이름이 바뀌었습니다와 같은 한 줄 알림을 표시합니다. 그런 다음 enabledPlugins 및 pluginConfigs 모두에 대해 사용자, 프로젝트 및 로컬 설정 범위에서 이전 키를 새 키로 다시 작성하므로 알림이 한 번 나타납니다.
• null 항목의 경우 Claude Code는 이전 키를 삭제하고 알림은 플러그인이 마켓플레이스에서 제거되었음을 보고합니다.
• 이름이 바뀐 플러그인이 github 또는 npm과 같은 원격 소스를 사용하면 Claude Code는 이름 바꾸기 후 plugin-cache-miss를 보고하고 사용자는 새 이름으로 가져오기 위해 한 번 /plugin install을 실행해야 합니다.

renames를 추가 전용 기록으로 취급합니다. 모든 사용자가 마이그레이션했을 것으로 예상한 후에도 이전 항목을 제자리에 유지합니다. Claude Code는 체인을 따르므로 나중에 code-formatter를 formatter-pro로 이름을 바꾸면 첫 번째 항목을 편집하는 대신 두 번째 항목을 추가합니다. 여전히 원본 formatter가 활성화된 사용자는 두 항목을 모두 통해 formatter-pro로 해석됩니다.

맵을 편집한 후 claude plugin validate .를 실행합니다. 체인이 사이클을 형성하거나 null 또는 plugins에 나열된 이름으로 종료되지 않는 항목을 거부합니다.

이전 버전의 Claude Code는 renames 필드를 무시하고 이전 이름에 대해 plugin-not-found를 보고합니다.

검증 및 테스트

마켓플레이스를 공유하기 전에 테스트합니다. 검증은 파일 구조를 확인합니다. 플러그인이 현실적인 프롬프트에서 Claude의 동작을 변경하는지 테스트하려면 새 버전을 게시하기 전에 claude plugin eval을 사용하여 평가 스위트를 실행합니다.

마켓플레이스 디렉토리에서 JSON 구문을 검증합니다:

claude plugin validate .

또는 Claude Code 내에서:

/plugin validate .

테스트를 위해 마켓플레이스를 추가합니다:

/plugin marketplace add ./path/to/marketplace

모든 것이 작동하는지 확인하기 위해 테스트 플러그인을 설치합니다:

/plugin install test-plugin@marketplace-name

전체 플러그인 테스트 워크플로우는 플러그인을 로컬에서 테스트를 참조하세요. 기술적 문제 해결은 플러그인 참조를 참조하세요.

CLI에서 마켓플레이스 관리

Claude Code는 스크립팅 및 자동화를 위한 비대화형 claude plugin marketplace 하위 명령어를 제공합니다. 이는 대화형 세션 내에서 사용 가능한 /plugin marketplace 명령어와 동일합니다.

플러그인 마켓플레이스 추가

GitHub 저장소, git URL, 원격 URL 또는 로컬 경로에서 마켓플레이스를 추가합니다.

claude plugin marketplace add <source> [options]

인수:

• <source>: GitHub owner/repo 단축형, git URL, marketplace.json 파일에 대한 원격 URL 또는 로컬 디렉터리 경로. 분기 또는 태그에 고정하려면 GitHub 단축형에 @ref를 추가하거나 git URL에 #ref를 추가합니다

URL은 스킴을 포함해야 합니다. Claude Code v2.1.196부터 gitlab.example.com/team/plugins와 같이 스킴 없이 입력된 호스트는 잘못된 owner/repo 단축형으로 거부되며, 오류 메시지에서 https://를 추가하거나 로컬 경로의 경우 ./를 사용하도록 지시합니다. 이전 버전에서는 이를 GitHub 저장소 경로로 잘못 읽고 GitHub 찾을 수 없음 오류로 클론 시간에 실패합니다.

옵션:

GitHub에서 owner/repo 단축형을 사용하여 마켓플레이스 추가:

claude plugin marketplace add acme-corp/claude-plugins

@ref를 사용하여 특정 분기 또는 태그에 고정:

claude plugin marketplace add acme-corp/claude-plugins@v2.0

비 GitHub 호스트의 git URL에서 추가:

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

marketplace.json 파일을 직접 제공하는 원격 URL에서 추가:

claude plugin marketplace add https://example.com/marketplace.json

테스트를 위해 로컬 디렉터리에서 추가:

claude plugin marketplace add ./my-marketplace

마켓플레이스를 프로젝트 범위에서 선언하여 .claude/settings.json을 통해 팀과 공유:

claude plugin marketplace add acme-corp/claude-plugins --scope project

모노레포의 경우 플러그인 콘텐츠를 포함하는 디렉터리로 체크아웃 제한:

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

claude plugin marketplace list의 From claude.ai: 섹션에 인쇄된 이름으로 claude.ai에서 호스팅되는 마켓플레이스 추가:

claude plugin marketplace add --claudeai claudeai-organization-library

--claudeai를 사용하면 명령어는 --scope와 --sparse를 거부합니다. 마켓플레이스는 계정에 대해 호스팅되며 설정 파일에 선언되지 않으므로 프로젝트의 .claude/settings.json을 통해 공유할 수 없습니다.

플러그인 마켓플레이스 목록

구성된 모든 마켓플레이스를 나열합니다.

claude plugin marketplace list [options]

옵션:

--json을 사용하면 각 항목에는 name, source, 마켓플레이스가 저장된 로컬 캐시 경로가 있는 installLocation 필드 및 소스별 필드가 포함됩니다: GitHub 소스의 경우 repo, git 및 URL 소스의 경우 url, 로컬 소스의 경우 path. GitHub 및 git 소스는 마켓플레이스가 고정된 분기 또는 태그로 추가된 경우 ref 필드도 포함합니다.

추가된 claude.ai 마켓플레이스는 로컬 클론이 없으므로 해당 항목은 installLocation 대신 claude.ai 식별자인 marketplaceId와 organizationUuid를 포함합니다.

플러그인이 claude.ai 계정에서 동기화되는 터미널 세션에서 텍스트 목록은 추가한 마켓플레이스 이상으로 계정에 대해 claude.ai가 나열하는 항목의 이름을 지정하는 From claude.ai: 섹션으로 끝납니다. 그 중 하나를 추가하려면 claude.ai에서 추가를 참조하세요. --json 출력은 구성된 마켓플레이스만 포함하고 해당 섹션을 제외합니다. Claude Code v2.1.273 이상 필요합니다.

플러그인 마켓플레이스 제거

구성된 마켓플레이스를 제거합니다. 별칭 rm도 허용됩니다.

claude plugin marketplace remove <name> [options]

인수:

• <name>: claude plugin marketplace list에 표시된 마켓플레이스 이름을 제거합니다. 이는 add에 전달한 소스가 아니라 marketplace.json의 name입니다

옵션:

플러그인 마켓플레이스 업데이트

소스에서 마켓플레이스를 새로 고쳐 새 플러그인 및 버전 변경을 검색합니다. 분기 또는 태그 ref로 추가된 마켓플레이스는 저장소의 기본 분기가 아니라 해당 ref의 최신 커밋으로 업데이트됩니다.

claude plugin marketplace update [name]

인수:

• [name]: claude plugin marketplace list에 표시된 마켓플레이스 이름을 업데이트합니다. 생략하면 모든 마켓플레이스를 업데이트합니다

remove와 update 모두 시드 관리 마켓플레이스에 대해 실행할 때 실패합니다. 이는 읽기 전용입니다. 모든 마켓플레이스를 업데이트할 때 시드 관리 항목은 건너뛰고 다른 마켓플레이스는 여전히 업데이트됩니다. 시드 제공 플러그인을 변경하려면 관리자에게 시드 이미지를 업데이트하도록 요청합니다. 컨테이너에 대한 플러그인 사전 채우기를 참조하세요.

문제 해결

마켓플레이스가 로드되지 않음

증상: 마켓플레이스를 추가할 수 없거나 플러그인을 볼 수 없습니다

해결책:

• 마켓플레이스 URL이 액세스 가능한지 확인합니다
• .claude-plugin/marketplace.json이 지정된 경로에 있는지 확인합니다
• claude plugin validate . 또는 /plugin validate .를 사용하여 JSON 구문이 유효한지 확인합니다. skill, agent 및 command frontmatter를 확인하려면 매니페스트 없이 플러그인 또는 디렉터리 검증을 참조하세요
• 개인 저장소의 경우 액세스 권한이 있는지 확인합니다

마켓플레이스 검증 오류

마켓플레이스 디렉터리에서 claude plugin validate . 또는 /plugin validate .를 실행하여 문제를 확인합니다. 마켓플레이스 디렉터리를 가리킬 때 검증자는 marketplace.json에서 스키마 오류, 중복 플러그인 이름 및 소스 경로 순회를 확인합니다. source가 로컬 경로인 각 항목에 대해 해당 플러그인의 plugin.json도 검증하고 항목의 version이 plugin.json의 버전과 일치하지 않을 때 경고합니다. 플러그인의 plugin.json에서 발견된 문제는 항목 인덱스 형식인 plugins[2] plugin.json →으로 접두사가 붙습니다.

Claude Code v2.1.196부터 항목별 통과는 다음을 포함합니다:

• source가 .인 플러그인 포함
• marketplace.json이 .claude-plugin 디렉터리 외부에 있을 때 실행되며, 파일 자체의 디렉터리에 대해 소스를 해석합니다
• 파일의 다른 부분에 스키마 오류가 있을 때도 각 항목의 문제를 보고합니다

이전 버전은 마켓플레이스 루트의 플러그인을 건너뛰고 .claude-plugin/marketplace.json에서만 내려갑니다.

마켓플레이스 디렉터리에서 Claude Code는 플러그인의 skill, agent, command 또는 hook 파일을 열지 않습니다. 이러한 파일의 오류를 찾으려면 매니페스트 없이 플러그인 또는 디렉터리 검증을 참조하세요. 아래 표는 마켓플레이스 디렉터리에서 가장 일반적인 오류와 각각의 원인 및 해결책을 나열합니다:

경고(차단하지 않음):

• Marketplace has no plugins defined: plugins 배열에 최소한 하나의 플러그인 추가
• No marketplace description provided: 사용자가 마켓플레이스를 이해하도록 돕기 위해 최상위 description 추가
• Plugin name "x" is not kebab-case: 소문자, 숫자 및 하이픈만 사용하도록 이름을 바꿉니다(예: my-plugin). Claude Code는 다른 형식을 허용하지만 claude.ai 마켓플레이스 동기화는 이를 거부합니다.
• Marketplace name "x" is reserved in Claude Desktop: 마켓플레이스의 이름이 org, org-provisioned 또는 unknown입니다(모든 대소문자). Claude Code는 이러한 이름을 허용하지만 Claude Desktop의 관리형 마켓플레이스 동기화는 전체 마켓플레이스를 거부합니다. 마켓플레이스의 이름을 바꿉니다. v2.1.221 이전에는 claude plugin validate가 이 검사를 실행하지 않았습니다.
• Marketplace name "x" is not accepted by Claude Desktop 또는 Plugin name "x" is not accepted by Claude Desktop: Claude Desktop은 문자 또는 숫자로 시작하는 최대 128자의 이름을 허용하며 문자, 숫자, ., _ 및 -로 구성됩니다. Claude Code는 다른 형식을 허용하지만 Claude Desktop의 관리형 마켓플레이스 동기화는 이름 검사에 실패한 마켓플레이스를 거부하고 이름이 실패한 플러그인 항목을 자동으로 삭제합니다. 마켓플레이스 또는 플러그인의 이름을 바꿉니다. v2.1.221 이전에는 claude plugin validate가 이러한 검사를 실행하지 않았습니다.

매니페스트 없이 플러그인 또는 디렉터리 검증

frontmatter가 구문 분석되지 않는 skill, agent 및 command 파일을 찾으려면 claude plugin validate를 실행하고 이들을 보유한 디렉터리의 이름을 지정합니다. Claude Code는 이름을 지정한 디렉터리 외부를 보지 않습니다. plugin.json이 있는 플러그인에 대한 한 번의 실행을 제외한 모든 실행에는 Claude Code v2.1.233 이상이 필요합니다.

이름을 지정할 디렉터리 선택

Claude Code는 이름을 지정한 디렉터리에 따라 다른 파일을 확인합니다. 첫 번째 열에서 확인하려는 항목을 찾고 해당 행의 명령을 실행합니다:

skill이 루트 `SKILL.md`인 플러그인 확인

플러그인 디렉터리에 대해 claude plugin validate를 실행하면 Claude Code는 플러그인 루트의 SKILL.md를 확인하지 않습니다. 플러그인이 skills라는 이름의 디렉터리에 있을 때 명령을 두 번 실행합니다:

• 플러그인의 루트 SKILL.md를 확인하려면 해당 skills 디렉터리의 이름을 지정합니다.
• 나머지를 확인하려면 플러그인 디렉터리의 이름을 지정합니다.

플러그인이 plugins/와 같은 다른 이름 아래에 있을 때 skills 디렉터리 실행을 사용할 수 없으며 루트 SKILL.md를 확인하는 실행이 없습니다.

symlink 뒤의 파일 확인

claude plugin validate를 실행하면 Claude Code는 이름을 지정한 디렉터리 내의 symlink를 따르지 않습니다. 링크가 있는 위치에 따라 수행하는 작업이 달라집니다:

• 플러그인 또는 .claude 루트 아래의 연결된 skills, agents 또는 commands 디렉터리: Claude Code는 그 안의 아무것도 읽지 않았다고 경고합니다.
• skills, agents 또는 commands 디렉터리 내의 연결된 항목: Claude Code는 이를 건너뛰고 디렉터리별로 건너뛴 항목 수를 경고합니다.
• 이름을 지정한 skills, agents 또는 commands 디렉터리 자체가 symlink이거나 그 부모 .claude 디렉터리가 symlink인 경우: Claude Code는 오류를 보고하고 그 안의 아무것도 확인하지 않습니다. 대신 실제 디렉터리의 이름을 지정합니다.

두 가지 skill 경우에 실행은 경고와 함께 통과합니다. 연결된 파일을 확인하려면 다시 실행하고 이들을 직접 보유한 디렉터리의 이름을 지정합니다:

• skills 디렉터리가 형제 플러그인의 skill에 연결된 플러그인: 형제 플러그인의 디렉터리의 이름을 지정합니다.
• ~/.claude/skills 또는 .claude/skills의 symlinked skill 항목: Claude Code는 세션에서 항목을 따릅니다. 이를 확인하려면 실제 폴더를 보유한 skills라는 디렉터리의 이름을 지정합니다.

검증 결과 읽기

깨끗한 실행은 Validation passed로 끝납니다.

No manifest found in directory는 Claude Code가 거기에서 plugin.json 또는 marketplace.json을 찾지 못했고 그 아래에서 조사하는 디렉터리에 skill, agent 또는 command 파일이 없음을 의미합니다. 대신 파일을 보유한 skills, agents 또는 commands 디렉터리의 이름을 지정합니다.

Claude Code가 이러한 실행에서 보고하는 두 가지 오류와 각각의 해결책:

• YAML frontmatter failed to parse: ...: skill, agent 또는 command 파일의 frontmatter 블록에서 YAML을 수정합니다. 이를 수행할 때까지 세션은 파일에서 frontmatter 필드를 읽지 않습니다
• Invalid JSON syntax: ... on hooks/hooks.json: JSON 구문을 수정합니다. 이를 수행할 때까지 세션은 해당 파일의 hook 없이 플러그인을 로드합니다. Claude Code는 플러그인 실행에서만 이 오류를 보고합니다

플러그인 실행에서 Claude Code는 플러그인 루트의 CLAUDE.md에 대해서도 경고합니다. plugin.json의 component path fields를 통해 설정한 경로의 경우 Claude Code는 각 경로가 존재하는지 확인하지만 거기의 파일을 읽지 않습니다.

플러그인 설치 실패

증상: 마켓플레이스가 나타나지만 플러그인 설치가 실패합니다

해결책:

• 플러그인 소스 URL이 액세스 가능한지 확인합니다
• 플러그인 디렉터리에 필수 파일이 포함되어 있는지 확인합니다
• GitHub 소스의 경우 저장소가 공개이거나 액세스 권한이 있는지 확인합니다
• 플러그인 소스를 수동으로 복제/다운로드하여 테스트합니다
• 소스가 ref와 sha를 모두 고정하는 경우 삭제된 업스트림 분기 또는 태그는 대부분의 git 호스트(GitHub, GitLab 및 Bitbucket 포함)에서 설치를 차단하지 않습니다. AWS CodeCommit과 같이 SHA로 커밋을 가져오기를 지원하지 않는 서버에서는 ref가 여전히 존재해야 하고 고정된 커밋이 이로부터 도달 가능해야 합니다. 설치가 계속 실패하면 고정된 커밋이 저장소에 여전히 존재하는지 확인합니다

개인 저장소 인증 실패

증상: 개인 저장소에서 플러그인을 설치할 때 인증 오류

해결책:

수동 설치 및 업데이트의 경우:

• git 공급자로 인증되었는지 확인합니다(예: GitHub의 경우 gh auth status 실행).
• 자격 증명 도우미가 구성되었는지 확인합니다: git config --global credential.helper
• git ls-remote <marketplace-url>을 실행하여 git이 자체적으로 인증할 수 있는지 테스트합니다. git이 사용자 이름 또는 암호를 요청하면 먼저 자격 증명을 저장합니다: GitHub over HTTPS의 경우 gh auth setup-git을 실행하고, SSH 원격의 경우 ssh-agent에 키를 로드합니다

백그라운드 자동 업데이트의 경우:

• 백그라운드 새로 고침은 구성된 git 자격 증명 도우미를 사용하지만 절대 프롬프트하지 않으므로 도우미는 저장된 자격 증명으로 응답할 수 있어야 합니다. ssh-agent에 로드된 키가 있는 SSH 원격도 인증합니다
• 도우미가 프롬프트해야 하면 백그라운드 업데이트가 조용히 실패하고 기존 체크아웃이 제자리에 유지됩니다. 먼저 도우미에 로그인하여 호스트에 대한 자격 증명을 보유하도록 합니다. GitHub의 경우 gh auth login을 실행한 다음 gh auth setup-git을 실행합니다
• 확인이 새 커밋을 찾거나 원격에 도달하거나 인증할 수 없으면 Claude Code는 동일한 자격 증명으로 마켓플레이스를 다시 복제합니다. 다시 복제는 대규모 저장소에서 시간 초과될 수 있습니다
• CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1을 설정하여 백그라운드 확인이 원격에 도달하거나 인증할 수 없을 때 기존 체크아웃을 유지합니다
• 대규모 저장소에서 다시 복제 시간이 초과되면 CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS를 사용하여 제한을 늘립니다
• 또는 자격 증명을 사용하는 /plugin marketplace update <name>으로 개인 마켓플레이스를 수동으로 업데이트합니다

v2.1.280 이전에는 백그라운드 확인이 자격 증명 도우미 없이 실행되었고 HTTPS를 통해 개인 저장소에 인증할 수 없었습니다.

마켓플레이스 업데이트가 오프라인 환경에서 실패합니다

증상: 오프라인 또는 에어갭 환경에서 백그라운드 마켓플레이스 새로 고침이 원격에 도달할 수 없고 Claude Code가 성공할 수 없는 다시 복제를 반복적으로 시도합니다.

원인: 백그라운드 새로 고침은 마켓플레이스의 원격에서 새 커밋을 확인하고, 확인이 원격에 도달할 수 없으면 Claude Code는 마켓플레이스를 다시 복제하려고 시도합니다. 오프라인에서 복제는 동일한 방식으로 실패하고 기존 체크아웃은 제자리에 유지됩니다. v2.1.274 이전에는 새로 고침이 기존 체크아웃에서 git pull을 실행했고, pull이 실패하면 체크아웃을 옆으로 이동하여 다시 복제했으며, 그 후 최선의 노력으로 복원했습니다.

새로 고침은 시작 후 백그라운드에서 실행되므로 시작을 지연시키지 않습니다. 각 세션은 여전히 실패한 시도를 반복하고, 각 git 작업은 120초 시간 초과를 기다릴 수 있습니다.

해결책: CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1을 설정하여 확인이 원격에 도달할 수 없을 때 다시 복제 시도를 건너뛰고 기존 체크아웃을 계속 사용합니다:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

완전히 오프라인 배포의 경우 저장소에 절대 도달할 수 없으므로 대신 CLAUDE_CODE_PLUGIN_SEED_DIR을 사용하여 빌드 시간에 플러그인 디렉터리를 사전 채웁니다.

Git 작업 시간 초과

증상: 플러그인 설치 또는 마켓플레이스 업데이트가 Git clone timed out after 120s와 같은 시간 초과 오류로 실패합니다.

원인: Claude Code는 플러그인 저장소 복제 및 마켓플레이스 업데이트를 포함한 모든 git 작업에 120초 시간 초과를 사용합니다. 대규모 저장소 또는 느린 네트워크 연결이 이 제한을 초과할 수 있습니다.

해결책: CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 환경 변수를 사용하여 시간 초과를 늘립니다. 값은 밀리초 단위입니다:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5분

상대 경로가 있는 플러그인이 URL 기반 마켓플레이스에서 실패합니다

증상: URL을 통해 마켓플레이스를 추가했습니다(예: https://example.com/marketplace.json). 하지만 "./plugins/my-plugin"과 같은 상대 경로 소스가 있는 플러그인이 its marketplace entry path does not stay inside the marketplace directory 오류로 설치되지 않습니다. 이미 설치된 플러그인이 Plugin source path refused 오류로 로드되지 않습니다. 두 메시지 모두 오류 참조 항목이 있습니다.

원인: URL 기반 마켓플레이스를 추가하면 marketplace.json 파일 자체만 다운로드됩니다. Claude Code는 해당 서버에서 플러그인 파일을 상대 경로로 가져오지 않습니다. 마켓플레이스 항목의 상대 경로는 다운로드되지 않은 원격 서버의 파일을 참조합니다.

해결책:

• 외부 소스 사용: 플러그인 항목을 상대 경로 이외의 플러그인 소스로 변경합니다:

  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  

• Git 기반 마켓플레이스 사용: 마켓플레이스를 Git 저장소에서 호스팅하고 git URL로 추가합니다. Git 기반 마켓플레이스는 전체 저장소를 복제하므로 상대 경로가 올바르게 작동합니다.

설치 후 파일을 찾을 수 없음

증상: 플러그인이 설치되지만 파일 참조가 실패합니다. 특히 플러그인 디렉터리 외부의 파일

원인: Claude Code는 플러그인을 제자리에 로드하지 않는 한 캐시 디렉터리에 복사합니다. command source in link mode는 제자리에 로드되고, 상대 경로 소스도 마켓플레이스에서 로컬 디렉터리로 추가된 경우 제자리에 로드됩니다. 복사된 플러그인의 디렉터리 외부의 파일을 참조하는 경로(예: ../shared-utils)는 해당 파일이 복사되지 않기 때문에 작동하지 않습니다.

해결책: symlink 및 디렉터리 재구성을 포함한 해결 방법은 플러그인 캐싱 및 파일 해석을 참조하세요.

추가 디버깅 도구 및 일반적인 문제는 디버깅 및 개발 도구를 참조하세요.

참고 항목

• 미리 빌드된 플러그인 검색 및 설치 - 기존 마켓플레이스에서 플러그인 설치
• 플러그인 - 자신의 플러그인 생성
• 플러그인 참조 - 완전한 기술 사양 및 스키마
• 플러그인 설정 - 플러그인 구성 옵션
• strictKnownMarketplaces 참조 - 관리되는 마켓플레이스 제한