마켓플레이스 호스팅 및 유지 관리

​

마켓플레이스 호스팅

​

저장소의 모든 사람을 위해 마켓플레이스 등록

​

URL 호스팅 마켓플레이스에서 상대 경로 항목 피하기

​

공유 디렉터리에서 플러그인을 제자리에서 편집

​

플러그인 파일을 Git LFS에서 제외

​

심볼릭 링크로 마켓플레이스 내 파일 공유

• 플러그인 자체 디렉터리 내: 심볼릭 링크는 캐시에서 상대 심볼릭 링크로 유지되므로 런타임에 복사된 대상으로 계속 해결됩니다.
• 동일한 마켓플레이스 내 다른 곳: 심볼릭 링크가 역참조됩니다. 대상의 콘텐츠가 캐시에 복사됩니다. 이를 통해 메타 플러그인의 skills/ 디렉터리가 마켓플레이스의 다른 플러그인으로 정의된 스킬에 연결될 수 있습니다.
• 마켓플레이스 외부: 심볼릭 링크는 보안상 건너뜁니다.

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

조직 설정을 통해 배포

• 마켓플레이스 저장소: github.com 및 gitlab.com에서 비공개 또는 내부여야 합니다
• 플러그인 소스: 각 플러그인 소스는 github, url 또는 git-subdir 유형이거나 ./로 시작하는 상대 경로여야 합니다
• 최상위 bin/ 디렉터리: claude.ai는 이를 가진 플러그인을 거부하고 마켓플레이스의 나머지를 동기화합니다. 오류 메시지는 Plugin contains a top-level bin/ directory로 시작합니다. 실행 파일을 scripts/와 같은 다른 디렉터리에 유지하고 훅 또는 MCP 서버 구성에서 ${CLAUDE_PLUGIN_ROOT}/scripts/<name>으로 참조하세요

​

비공개 마켓플레이스에 대한 액세스 부여

• GitHub owner/repo: Claude Code는 ssh -T git@github.com을 프로브하고 프로브가 성공하면 SSH를 통해 복제합니다. 프로브가 실패하거나 SSH 복제 자체가 실패하면 HTTPS를 통해 복제합니다. GitHub SSH 키가 없는 머신의 사용자는 CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1을 설정하여 프로브를 건너뛰고 HTTPS를 통해 복제할 수 있습니다.
• git@host:path.git: SSH.
• https://example.com/repo.git: HTTPS.

• SSH: 키는 암호 프롬프트 없이 작동해야 합니다(예: ssh-agent에 로드됨). 호스트는 이미 known_hosts에 있어야 합니다.
• HTTPS: Claude Code는 사용자의 git 자격 증명 도우미를 활성화 상태로 두지만 프롬프트를 금지합니다. 도우미가 이미 저장한 자격 증명은 작동합니다. 요청해야 하는 자격 증명은 실패합니다. GitHub에서 gh auth login 다음 gh auth setup-git을 실행하면 자격 증명이 저장됩니다.

​

git 호스트 계정이 없는 사용자 제공

• archive: HTTPS를 통해 다운로드된 zip. 사용자는 git이나 계정이 필요하지 않으며 URL에 대한 네트워크 액세스만 필요합니다. Claude Code v2.1.224 이상이 필요합니다. 각 아카이브를 sha256으로 고정하여 Claude Code가 변경된 다운로드를 거부하도록 합니다. 다운로드와 함께 자격 증명을 보내려면 아카이브 다운로드 인증을 참조하세요.
• 공개 git 저장소: Claude Code는 항목이 https:// URL을 제공할 때 자격 증명 없이 HTTPS를 통해 공개 url 또는 git-subdir 소스를 복제합니다. github 소스 또는 owner/repo로 작성된 git-subdir 소스의 경우 GitHub SSH 키가 없는 사용자는 CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1을 설정합니다.

​

백그라운드 자동 업데이트가 자격 증명으로 수행하는 작업

• SSH 원격: ssh-agent에 로드된 키가 확인을 인증합니다.
• 저장된 자격 증명이 있는 HTTPS 원격: 프롬프트 없이 저장된 자격 증명을 제공할 수 있는 도우미가 확인을 인증합니다. Git Credential Manager, macOS Keychain 도우미 및 git-credential-store는 호스트에 대한 자격 증명을 보유한 후 이런 방식으로 작동합니다.
• 프롬프트가 필요한 HTTPS 원격 도우미: 도우미는 백그라운드에서 응답할 수 없습니다. 업데이트가 조용히 실패하고 기존 체크아웃이 제자리에 남아 있으므로 사용자의 플러그인은 마지막 동기화된 상태에서 계속 작동합니다.

• 체크아웃이 최신 상태입니다: Claude Code는 그대로 둡니다.
• 확인이 새 커밋을 찾거나 원격에 도달하거나 인증할 수 없어 실패합니다: Claude Code는 마켓플레이스를 다시 복제하고 기존 체크아웃을 새 복제로 바꿉니다. 해당 복제가 실패하면 기존 체크아웃이 제자리에 남아 있습니다. 다시 복제는 큰 저장소에서 시간 초과될 수 있습니다.

• 자격 증명 저장: 먼저 자격 증명 도우미에 로그인하여 호스트에 대한 자격 증명을 보유하도록 합니다. GitHub의 경우 gh auth login을 실행한 다음 gh auth setup-git을 실행합니다.
• 실패 시 체크아웃 유지: 사용자가 CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1을 설정하면 Claude Code는 백그라운드 확인이 원격에 도달하거나 인증할 수 없을 때 다시 복제를 시도하지 않고 기존 체크아웃을 유지합니다. 플러그인은 마지막 동기화된 상태에서 계속 작동합니다.

​

전체 회사에 롤아웃

• git 계정이 필요하지 않은 항목 소스: git 호스트 계정이 없는 사용자 제공
• 사전 채워진 플러그인 디렉터리: 컨테이너 및 CI 시드, 또한 git 호스트 계정이 없는 사용자를 제공합니다
• claude.ai 조직 설정: 조직 설정을 통해 배포, 사용자의 git 자격 증명이 관련되지 않습니다

​

사용자를 최신 상태로 유지

​

자동 업데이트 켜기

• 사용자에게 켜도록 지시: 각 사용자는 /plugin에서 마켓플레이스로 이동하여 마켓플레이스를 선택한 후 자동 업데이트 활성화를 선택합니다.
• 관리자에게 설정하도록 요청: 관리자가 관리 설정의 마켓플레이스 extraKnownMarketplaces 항목에서 "autoUpdate": true를 설정하면 해당 설정을 받는 모든 사용자에게 켜집니다. 업데이트 정책 설정을 참조하십시오.

​

새 버전 출시

• 각 릴리스에서 version 증가: 사용자는 문자열이 변경될 때까지 캐시된 복사본에 유지됩니다. "version": "1.0.0"을 설정하고 변경하지 않고 새 커밋을 푸시하면 사용자는 이를 받지 못합니다.
• version 생략: 사용자는 대신 커밋을 추적합니다. plugin.json과 마켓플레이스 항목 모두에서 version을 제외합니다.

​

사용자를 한 버전에 유지

• 플러그인 항목의 ref 및 sha: ref는 분기 또는 태그의 이름이고 sha는 github, url 또는 git-subdir 소스의 커밋 이름입니다. 플러그인 소스를 참조하십시오.
• 추가 명령의 #<ref>: your-org/your-marketplace#stable을 추가하는 사용자는 카탈로그의 해당 분기 또는 태그를 받습니다. 동시에 두 개의 릴리스 라인의 경우 릴리스 채널 실행을 참조하십시오.
• <plugin>--v<version> 태그: 종속성의 버전 범위는 이러한 태그에 대해 확인됩니다. 다른 사용자가 의존하는 플러그인 출시를 참조하십시오.

​

명령 소스의 명령 변경

• 더 이상 백그라운드 실행 없음: 해당 사용자에 대해 명령의 세션당 한 번 실행이 중지되므로 도구의 새 출력이 사용자에게 도달하지 않습니다.
• /plugin 오류 탭의 항목: 항목은 새 명령과 실행할 claude plugin update 명령을 표시합니다.

​

릴리스 채널 실행

{
  "name": "stable-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "stable" } }
  ]
}

{
  "name": "latest-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "latest" } }
  ]
}

​

플러그인 이름 변경 또는 제거

​

이름 변경 맵을 사용하여 사용자 마이그레이션

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

• 이름이 변경된 항목: 플러그인이 새 이름으로 로드됩니다. claude plugin list와 /plugin 아래의 플러그인 세부 정보에는 한 번 Renamed to "code-formatter" in the "your-marketplace" marketplace가 표시되며, Claude Code는 사용자, 프로젝트 및 로컬 설정 범위의 enabledPlugins 및 pluginConfigs에서 이전 키를 새 키로 다시 작성합니다.
• null 항목: 이전 키가 해당 범위에서 삭제되고 사용자는 Removed from the "your-marketplace" marketplace를 봅니다.
• 관리되는 설정에서 활성화됨: 플러그인은 여전히 새 이름으로 로드되지만, Claude Code는 관리되는 설정을 다시 작성할 수 없으므로 관리자가 해당 위치의 enabledPlugins을 업데이트할 때까지 알림이 반복됩니다.

​

사용자 머신에서 제거된 플러그인 제거

1. 사용자가 마켓플레이스에서 설치한 항목을 항목 및 renames 맵과 비교하고, 나열되지 않거나 이름이 변경되지 않은 플러그인을 제거된 것으로 취급합니다.
2. 사용자, 프로젝트 및 로컬 범위에서 각 제거된 플러그인을 제거합니다. 관리되는 설정만 설치한 플러그인은 제자리에 유지됩니다.
3. /plugin의 Flagged 제목 아래에 각 제거된 플러그인을 Removed from marketplace 상태로 나열합니다.

​

아카이브 다운로드 인증

• 마켓플레이스의 url 소스: extraKnownMarketplaces 항목과 같이 마켓플레이스를 등록한 url 소스입니다.
• 플러그인의 항목: Claude Code v2.1.238 이상에서는 source 옆의 플러그인의 marketplace.json 항목에 설정할 수 있습니다.

​

플러그인 항목에 headersHelper 추가

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

​

headersHelper 명령 작성

• 명령 텍스트: 최대 500자의 인쇄 가능한 ASCII, 4개 이상의 공백 실행 없음.
• 출력: stdout에 헤더 이름 및 문자열 값의 JSON 객체 하나를 인쇄한 후 10초 내에 종료 0.
• 셸 및 작업 디렉터리: Claude Code는 sh를 통해 또는 Windows에서 cmd.exe를 통해 명령을 실행합니다. 작업 디렉터리는 구성 디렉터리이며 ~/.claude 또는 CLAUDE_CONFIG_DIR입니다. 상대 경로가 사용자의 프로젝트가 아닌 해당 디렉터리에 대해 해결되므로 절대 경로 또는 PATH의 명령을 제공하세요.
• Claude Code가 제거하는 변수: 명령이 marketplace.json 항목 또는 프로젝트의 .claude/settings.json 또는 .claude/settings.local.json에 설정되면 Claude Code는 환경에서 자격 증명처럼 보이는 이름의 모든 변수를 제거합니다(MCP headersHelper에 적용하는 동일한 규칙). ANTHROPIC_API_KEY 및 MY_REGISTRY_TOKEN 모두 제거되므로 명령이 파일 또는 자격 증명 저장소에서 자격 증명을 읽도록 합니다. 이 제거는 사용자 설정, --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로 마켓플레이스를 추가한 후 첫 번째 가져오기에서 설정되지 않습니다. 해당 가져오기가 이름을 제공하기 때문입니다.

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

​

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

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

​

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

​

명령을 요청하는 대신 거부하는 설치 및 업데이트

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

​

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

​

다른 플러그인에 의존 및 권장

• 버전 범위: 종속성은 semver 범위를 전달할 수 있습니다.
• 교차 마켓플레이스 종속성: 다른 마켓플레이스의 종속성은 마켓플레이스가 allowCrossMarketplaceDependenciesOn에 해당 마켓플레이스를 나열할 때만 설치됩니다.

​

마켓플레이스가 할 수 없는 것 해결

• 사용자가 설치하는 다른 것 제한: 마켓플레이스 허용 목록은 관리 설정 strictKnownMarketplaces입니다. 사용자가 설치할 수 있는 것 제한을 참조하세요.
• 사용자가 요청하지 않고 플러그인 설치 또는 활성화: 항목 필드가 플러그인을 설치하지 않습니다. 관리 enabledPlugins는 플릿에 대해 그렇게 합니다. 플러그인 사전 설치 및 요구를 참조하세요.
• 다른 사용자에게 다른 항목 표시: 항목은 대상 필드를 전달하지 않으며 마켓플레이스를 추가하는 모든 사용자는 전체 카탈로그를 봅니다. 다른 대상을 위해 별도의 마켓플레이스를 호스팅하세요.
• 플러그인을 더 이상 사용되지 않음으로 표시: 더 이상 사용되지 않음 상태가 없습니다. 옵션은 항목을 제거하고 renames에서 이름을 null로 매핑하며 선택적으로 forceRemoveDeletedPlugins를 설정하는 것입니다.
• 사용자를 위해 자동 업데이트 켜기: 각 사용자는 /plugin의 마켓플레이스 아래에서 켜거나 관리자가 관리 설정에서 autoUpdate를 설정합니다. 자동 업데이트 켜기를 참조하세요.
• git 자격 증명 전달: 마켓플레이스 필드가 git 토큰을 보유하지 않습니다. git 호스팅 마켓플레이스 또는 플러그인에 대한 액세스는 비공개 마켓플레이스에 대한 액세스 부여에 따라 사용자의 git 설정을 따릅니다. archive 소스의 경우 항목은 대신 headers 또는 headersHelper를 설정할 수 있습니다.

​

다음 단계

• 마켓플레이스 참조: marketplace.json 필드, 소스 유형 및 유효성 검사 메시지
• 조직을 위한 플러그인 관리: 조직의 머신 전체에서 마켓플레이스를 요구, 제한 또는 시드
• 플러그인 종속성: 플러그인에 의존하는 플러그인이 버전을 해결할 수 있도록 릴리스 태그
• 플러그인 문제 해결: 마켓플레이스에서 추가 또는 업데이트할 때 사용자가 보는 오류