CLI에서 플러그인 추천하기

CLI 또는 SDK를 유지 관리하는 경우, 도구가 Claude Code 사용자에게 플러그인 설치를 유도할 수 있습니다. CLI가 Claude Code 내부에서 실행 중임을 감지하면, 한 줄의 <claude-code-hint /> 태그를 stderr에 작성합니다. Claude Code는 모델이 출력을 보기 전에 Bash 및 PowerShell 도구 출력에서 해당 줄을 제거한 후, 사용자에게 일회성 설치 프롬프트를 표시합니다. 이 페이지는 플러그인이 claude-plugins-official 또는 Anthropic의 공식 마켓플레이스 이름 중 하나인 다른 마켓플레이스에 나열된 경우에만 적용됩니다. 커뮤니티 마켓플레이스인 claude-community는 해당하지 않습니다.

플러그인을 게시하려면 플러그인 게시 및 배포를 참조하세요.

힌트 내보내기

CLAUDECODE 또는 CLAUDE_CODE_CHILD_SESSION이 설정된 경우에만 태그를 내보내므로, 사용자가 CLI를 직접 실행할 때는 나타나지 않습니다. Claude Code는 Bash 및 PowerShell 도구를 통해 실행하는 명령과 훅 명령에서 CLAUDECODE=1을 설정합니다. v2.1.172 이상에서는 CLAUDE_CODE_CHILD_SESSION=1도 설정합니다. 변수는 이를 전달하는 프로세스가 다릅니다:

CLAUDECODE: 모든 Claude Code 버전에서 설정됩니다. IDE 확장 프로그램도 통합 터미널에서 설정하므로, CLAUDECODE만으로 게이트하면 사용자가 해당 터미널 중 하나에서 CLI를 직접 실행할 때도 태그가 내보내집니다.
CLAUDE_CODE_CHILD_SESSION: Claude Code 자체가 시작하는 서브프로세스에서만 설정됩니다. v2.1.172 이상이 필요한 경우 사용하세요.

환경 변수 참조에 세부 정보가 있습니다. 다음 예제는 가장 광범위한 도달을 위해 CLAUDECODE로 게이트하고 공식 마켓플레이스의 example-cli라는 플러그인에 대한 힌트를 내보냅니다:

if (process.env.CLAUDECODE) {
  process.stderr.write(
    '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
  )
}

import os, sys

if os.environ.get("CLAUDECODE"):
    print(
        '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
        file=sys.stderr,
    )

if os.Getenv("CLAUDECODE") != "" {
    fmt.Fprintln(os.Stderr,
        `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
}

if [ -n "$CLAUDECODE" ]; then
  printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
fi

공식 마켓플레이스에서 플러그인의 이름으로 example-cli를 바꾸세요. Claude Code가 각 플러그인에 대해 한 번씩 프롬프트하므로 모든 호출에서 힌트를 내보낼 수 있습니다. 내보내기를 확인하려면 터미널에서 CLAUDECODE=1 example-cli를 실행하고 태그 줄이 stderr에 나타나는지 확인한 후, 변수 없이 example-cli를 실행하고 추가 항목이 인쇄되지 않는지 확인하세요.

힌트 형식

태그는 자체 줄을 차지해야 합니다. Claude Code는 줄 중간에 포함된 태그를 무시합니다. 태그는 세 가지 속성을 사용하며, 모두 필수입니다:

속성	설명
`v`	프로토콜 버전. `1`이 유일하게 지원되는 값입니다.
`type`	힌트 종류. `plugin`이 유일하게 지원되는 값입니다.
`value`	`name@marketplace` 형식의 플러그인 식별자

값은 큰따옴표로 묶거나 따옴표 없이 사용할 수 있습니다. 따옴표 없는 값은 공백을 포함할 수 없습니다. Claude Code는 v 또는 type이 인식되지 않을 때도 줄을 출력에서 제거합니다.

프롬프트가 나타나는 시기 확인

프롬프트는 대화형 터미널 세션에서만 나타납니다. claude -p 실행, 서브에이전트 실행, 훅 명령 출력에서는 태그가 제거되고 프롬프트가 표시되지 않습니다. 다음 확인 사항도 모두 통과해야 합니다:

공식 및 설치 가능: value가 Claude Code가 공식 마켓플레이스의 로컬 복사본에서 찾은 플러그인을 지정하고, 아직 설치되지 않았으며, 정책이 차단하지 않습니다.
분석 켜짐: Claude Code의 분석이 꺼진 세션(예: DISABLE_TELEMETRY, DO_NOT_TRACK 또는 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC이 설정된 세션)이나 Amazon Bedrock과 같은 타사 제공자의 세션에서는 프롬프트가 표시되지 않습니다. 여기서 자동 원격 분석 옵트아웃이 적용됩니다.
빈도 제한: 세션당 한 번의 프롬프트, 사용자의 답변과 관계없이 플러그인당 한 번의 프롬프트, 그리고 해당 머신에서 100개의 플러그인에 대해 프롬프트가 표시된 후에는 없습니다.
꺼지지 않음: 사용자가 아니오, 플러그인 설치 힌트를 다시 표시하지 않기를 선택하지 않았습니다.
로컬, 참석 세션: 세션의 작업 공간이 클라우드나 원격 머신이 아닌 로컬이고, 세션이 무인으로 실행되지 않습니다. 예를 들어 --cloud로 시작된 세션, 원격 제어를 제공하는 세션, 또는 에이전트 팀 팀원은 프롬프트를 표시하지 않습니다.

사용자가 보는 내용 미리보기

프롬프트가 나타나는 시기 확인의 확인 사항이 통과하면, Claude Code는 다음과 같은 플러그인 추천 대화 상자를 표시합니다:

─────────────────────────────────────────────────────────────
  Plugin recommendation

    The example-cli command suggests installing a plugin.

    Plugin: example-cli
    Marketplace: claude-plugins-official
    Description: Official integration for example-cli deployments

    Would you like to install it?
    ❯ 1. Yes, install
      2. No
      3. No, and don't show plugin installation hints again

─────────────────────────────────────────────────────────────

대화 상자는 Claude가 실행한 셸 명령의 첫 번째 단어를 지정하므로 사용자가 불일치를 발견할 수 있습니다. 각 답변은 하나의 효과를 가집니다:

예, 설치: 사용자 범위에서 플러그인을 설치합니다.
아니오, 플러그인 설치 힌트를 다시 표시하지 않기: 해당 사용자에 대한 향후 힌트 프롬프트를 끕니다.
30초 동안 답변 없음: 아니오로 계산됩니다.

다음 단계

플러그인 게시 및 배포: 힌트가 필요한 공식 마켓플레이스를 포함한 각 마켓플레이스로의 경로
플러그인 명령 참조: 세션 외부에서 동일한 플러그인을 설치하는 셸 명령

플러그인

플러그인 사용

플러그인 만들기

마켓플레이스 실행

조직의 플러그인 관리

문제 해결

참고

CLI에서 플러그인 추천하기

힌트 내보내기

힌트 형식

프롬프트가 나타나는 시기 확인

사용자가 보는 내용 미리보기

다음 단계

​힌트 내보내기

​힌트 형식

​프롬프트가 나타나는 시기 확인

​사용자가 보는 내용 미리보기

​다음 단계

힌트 내보내기

힌트 형식

프롬프트가 나타나는 시기 확인

사용자가 보는 내용 미리보기

다음 단계