조직 마켓플레이스 plugin relevance 제안

기준일: 2026-07-26
공식 기준: Recommend plugins for your org

개요

조직 플러그인 마켓플레이스 운영자는 marketplace.json 플러그인 항목에 relevance 블록을 넣고, managed settings에서 마켓플레이스를 allowlist하면, 사용자 세션이 선언 신호와 맞을 때 Claude Code가 설치 제안을 띄웁니다.

제안은 마켓플레이스별 opt-in입니다. 관리자가 allowlist에 넣기 전에는 공식 Anthropic 마켓플레이스 포함 어떤 marketplace의 relevance도 제안을 만들지 않습니다. Claude Code 내장 제안 1개는 allowlist와 무관합니다. spinnerTipsEnabled: false면 그 tip과 marketplace 선언 tip 모두 비활성.

• 최소 버전: v2.1.152+ (relevance 필드; 구버전은 무시)
• 대상: 마켓플레이스 운영자·엔터프라이즈 관리자. 설치만 필요하면 Discover plugins

핵심 개념

항목	내용
신호 매칭	사용자 머신 로컬. 네트워크 없음. 매칭 신호/값을 Anthropic·운영자에 보고하지 않음
표시 위치	Spinner tip / 세션 시작 알림(cwd, v2.1.153+) / /plugin Discover 핀(v2.1.154+)
자동 설치	없음. 사용자 확인 필수
관리 키	pluginSuggestionMarketplaces + (공식 제외) extraKnownMarketplaces 또는 strictKnownMarketplaces

상세

동작

marketplace.json 플러그인 항목의 relevance에 topic과 signals. 신호 예: working directory, Claude가 읽은 파일.

미설치 + 신호 매치 시:

1. Spinner tip — “Working with topic? Install the plugin plugin” + /plugin install 명령
2. Session-start (v2.1.153+) — cwd 매치 시 plugin suggestion: <name>@<marketplace> · /plugin
3. Discover 탭 (v2.1.154+) — “suggested for this directory” 등 주석으로 상단 핀

spinner tip·세션 시작 알림은 spinner-tips 시스템. spinnerTipsEnabled: false 또는 spinnerTipsOverride + excludeDefault면 비활성. Discover 핀은 tip 설정과 독립.

relevance 추가 예

.tf 읽기 또는 terraform 실행 시 terraform-helpers 제안:

{
  "name": "acme-corp-plugins",
  "owner": { "name": "Acme Platform Team" },
  "plugins": [
    {
      "name": "terraform-helpers",
      "source": "./plugins/terraform-helpers",
      "description": "Acme conventions and helpers for Terraform",
      "relevance": {
        "topic": "Terraform",
        "signals": {
          "cli": ["terraform"],
          "filesRead": ["**/*.tf"]
        }
      }
    }
  ]
}

신호가 안 맞으면 일반 Discover 항목으로만 표시되고 spinner tip은 안 뜹니다.

필드 레퍼런스

relevance

필드	타입	설명
topic	string	선택. spinner “Working with topic?” 문구. 기본은 플러그인 이름 하이픈 세그먼트 대문자화. 세션 시작 알림은 미사용. 최대 64자
signals	object	제안 가능 조건. 최소 1개 신호 필요

relevance.signals

필드	설명
cwd (v2.1.153+)	워킹 디렉터리 glob (절대 경로 + git 루트 상대). / 정규화, 대소문자 무시. infra/infra//infra/** 동일. 세션 시작에 매치 가능한 유일한 신호. 최대 10 패턴 × 256자
cli	세션 중 Claude가 실행한 셸 명령 이름. 모든 OS. 호출당 선행 env 할당·sudo 뒤 첫 토큰만. cd infra && terraform plan → cd. exact match. 최대 10 × 64자
hosts	Bash 명령 속 http(s):// URL 호스트명만. scheme/port/path 없음. 대소문자 무시 exact. 최대 20 × 128자
filesRead (v2.1.153+)	Claude가 읽은 파일 경로 glob. write/edit·auto-loaded CLAUDE.md도 기록에 포함. 최대 10 × 256자
manifestDeps	읽은 package manifest 의존성. { "file": "regex", "pattern": "regex" }. file은 경로 끝 앵커 권장 ([/\\\\]package\\.json$). Windows 백슬래시. 512KB 초과 파일 스킵. 최대 10. file 대소문자 무시, pattern 구분

cli/hosts/filesRead/manifestDeps는 세션 이력 필요 → spinner·Discover만. 세션 시작은 cwd만.

package.json에 stripe 의존 시 예:

{
  "name": "stripe-helpers",
  "source": "./plugins/stripe-helpers",
  "relevance": {
    "topic": "Stripe",
    "signals": {
      "manifestDeps": [
        {
          "file": "[/\\\\]package\\.json$",
          "pattern": "\"stripe\"\\s*:"
        }
      ]
    }
  }
}

relevance/signals 아래 알 수 없는 필드는 로드 시 무시(구 클라이언트 호환). claude plugin validate가 경고.

managed settings에서 활성화

relevance만으로는 부족. 관리자가 pluginSuggestionMarketplaces에 마켓플레이스 이름을 넣어야 합니다. 공식 외 마켓플레이스는 같은 managed settings에 extraKnownMarketplaces 또는 strictKnownMarketplaces로 소스도 선언. allowlist 이름과 다른 소스로 등록된 마켓플레이스는 무시(이름 도용 방지).

{
  "extraKnownMarketplaces": {
    "acme-corp-plugins": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  },
  "pluginSuggestionMarketplaces": ["acme-corp-plugins"]
}

공식:

{
  "pluginSuggestionMarketplaces": ["claude-plugins-official"]
}

사용자에게 보이는 내용

Spinner:

Working with Terraform? Install the terraform-helpers plugin:
/plugin install terraform-helpers@acme-corp-plugins

세션 시작:

plugin suggestion: terraform-helpers@acme-corp-plugins · /plugin

플러그인당 spinner tip + 세션 시작 합쳐 3세션에 최대 1회, 설치 후 반복 없음. 세션 시작 알림은 2회 표시 후 중단. Discover 핀은 플러그인당 1회(이후 정상 순서). v2.1.152는 spinner만, 153+ 세션 시작, 154+ Discover.

검증

claude plugin validate ./my-marketplace

알 수 없는 키 경고, non-object relevance 오류, hosts에 scheme/port/path 포함 시 거부.

체크리스트

• Claude Code v2.1.152+ (필요 표면별 153/154)
• marketplace.json에 topic·signals를 넣었다
• managed pluginSuggestionMarketplaces (+ 비공식 시 소스 선언)를 설정했다
• 신호 매칭이 로컬 전용·자동 설치 없음을 팀에 안내했다
• claude plugin validate를 돌렸다

다음 단계

• Plugin marketplaces
• Plugin hints (CLI)
• Settings

기준일

• 문서 작성·동기화 기준일: 2026-07-26
• 원문: https://code.claude.com/docs/en/plugin-relevance