1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# CLI에서 플러그인 추천하기

6 

7> CLI에서 한 줄 마커를 내보내어 Claude Code가 사용자에게 공식 플러그인 설치를 권유하도록 합니다.

8 

9CLI 또는 SDK를 유지 관리하고 공식 Anthropic 마켓플레이스에 플러그인이 있다면, 도구가 Claude Code 사용자에게 해당 플러그인을 설치하도록 권유할 수 있습니다. CLI는 Claude Code 내부에서 실행 중임을 감지할 때 stderr에 한 줄 마커를 작성합니다. Claude Code는 마커를 읽고 출력에서 제거한 후 사용자에게 일회성 설치 프롬프트를 표시합니다.

10 

11Claude Code는 힌트 줄을 명령 출력에서 제거한 후 모델로 전송하므로 마커는 대화에 나타나지 않으며 토큰 사용량에 계산되지 않습니다. 이 프로토콜은 추가 명령이 필요하지 않으며 Claude Code 외부에서 CLI를 실행하는 사용자에게 출력되는 내용을 변경하지 않습니다.

12 

13이 페이지는 CLI 및 SDK 유지 관리자를 위한 것입니다. 플러그인 설치를 찾고 있다면 [플러그인 발견 및 설치](/ko/discover-plugins)를 참조하세요.

14 

15<h2 id="how-it-works">

16 작동 방식

17</h2>

18 

19Claude Code는 Bash 및 PowerShell 도구를 통해 실행하는 모든 명령과 [hook](/ko/hooks) 명령에 대해 [`CLAUDECODE`](/ko/env-vars) 환경 변수를 `1`로 설정합니다. CLI가 해당 변수를 감지하면 자체 종료 `<claude-code-hint />` 태그를 stderr에 작성합니다. hook 명령에서 힌트 태그는 제거되고 무시됩니다. Bash 및 PowerShell 도구 출력만 설치 프롬프트를 트리거합니다.

20 

21Claude Code가 명령 출력을 받으면 다음을 수행합니다:

22 

231. 힌트 줄을 스캔하고 출력이 모델에 도달하기 전에 제거합니다

242. 힌트가 공식 Anthropic 마켓플레이스의 플러그인을 대상으로 하는지 확인합니다

253. 플러그인이 이미 설치되지 않았으며 이전에 프롬프트되지 않았는지 확인합니다

264. 힌트를 내보낸 명령의 이름을 지정하는 설치 프롬프트를 사용자에게 표시합니다

27 

28Claude Code는 플러그인을 자동으로 설치하지 않습니다. 사용자가 항상 확인합니다.

29 

30<h2 id="emit-the-hint">

31 힌트 내보내기

32</h2>

33 

34`CLAUDECODE` 환경 변수에서 내보내기를 제어하여 마커가 일반 사용자의 터미널에 나타나지 않도록 합니다. 그런 다음 태그를 stderr에 자체 줄로 작성합니다.

35 

36다음 예제는 공식 마켓플레이스에서 `example-cli`라는 플러그인에 대한 힌트를 내보냅니다:

37 

38<CodeGroup>

39 ```javascript Node.js theme={null}

40 if (process.env.CLAUDECODE) {

41 process.stderr.write(

42 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',

43 )

44 }

45 ```

46 

47 ```python Python theme={null}

48 import os, sys

49 

50 if os.environ.get("CLAUDECODE"):

51 print(

52 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',

53 file=sys.stderr,

54 )

55 ```

56 

57 ```go Go theme={null}

58 if os.Getenv("CLAUDECODE") != "" {

59 fmt.Fprintln(os.Stderr,

60 `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)

61 }

62 ```

63 

64 ```shell Shell theme={null}

65 [ -n "$CLAUDECODE" ] &&

66 printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2

67 ```

68</CodeGroup>

69 

70공식 마켓플레이스에서 플러그인의 이름으로 `example-cli`를 바꿉니다.

71 

72<h2 id="choose-where-to-emit">

73 내보낼 위치 선택

74</h2>

75 

76힌트를 내보낼 코드 경로를 제어합니다. Claude Code는 플러그인별로 중복 제거하므로 모든 호출에서 내보내는 것은 단점이 없습니다. 잘 작동하는 접점은 다음과 같습니다:

77 

78| 배치 | 작동하는 이유 |

79| :-------------- | :--------------------------------------- |

80| `--help` 출력 | Claude는 종종 익숙하지 않은 CLI를 탐색할 때 도움말을 실행합니다 |

81| 알 수 없는 하위 명령 오류 | Claude가 인터페이스에 대해 혼동하는 순간에 도달합니다 |

82| 로그인 또는 인증 성공 | 사용자가 이미 설정 마음가짐에 있습니다 |

83| 첫 실행 환영 메시지 | 자연스러운 온보딩 순간입니다 |

84 

85<h2 id="what-the-user-sees">

86 사용자가 보는 것

87</h2>

88 

89힌트가 모든 검사를 통과하면 Claude Code는 다음과 같은 프롬프트를 표시합니다:

90 

91```text theme={null}

92─────────────────────────────────────────────────────────────

93 플러그인 추천

94 

95 example-cli 명령이 플러그인 설치를 제안합니다.

96 

97 플러그인: example-cli

98 마켓플레이스: claude-plugins-official

99 example-cli 배포를 위한 공식 통합

100 

101 설치하시겠습니까?

102 ❯ 1. 예, example-cli 설치

103 2. 아니오

104 3. 아니오, 플러그인 설치 힌트를 다시 표시하지 않기

105 

106─────────────────────────────────────────────────────────────

107```

108 

109프롬프트는 힌트를 생성한 명령의 이름을 지정하므로 사용자가 도구와 권장하는 플러그인 간의 불일치를 발견할 수 있습니다. 사용자가 30초 이내에 응답하지 않으면 프롬프트는 **아니오**로 해제됩니다.

110 

111프롬프트 빈도는 제한됩니다:

112 

113* **플러그인당 한 번**: 프롬프트가 표시된 후 Claude Code는 플러그인을 기록하고 사용자의 답변에 관계없이 다시 프롬프트하지 않습니다.

114* **세션당 한 번**: 머신의 모든 CLI에서 Claude Code 세션당 최대 하나의 힌트 프롬프트가 나타납니다.

115 

116**예**를 선택하면 플러그인이 사용자 범위로 설치됩니다. **아니오, 플러그인 설치 힌트를 다시 표시하지 않기**를 선택하면 사용자에 대한 모든 향후 힌트 프롬프트가 비활성화됩니다.

117 

118<h2 id="hint-format">

119 힌트 형식

120</h2>

121 

122힌트는 세 개의 필수 속성이 있는 자체 종료 태그입니다.

123 

124```text theme={null}

125<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />

126```

127 

128| 속성 | 필수 | 설명 |

129| :------ | :- | :------------------------------ |

130| `v` | 예 | 프로토콜 버전. `1`은 유일하게 지원되는 값입니다 |

131| `type` | 예 | 힌트 종류. `plugin`은 유일하게 지원되는 값입니다 |

132| `value` | 예 | `name@marketplace` 형식의 플러그인 식별자 |

133 

134속성 값은 큰따옴표로 인용하거나 인용하지 않을 수 있습니다. 인용하지 않은 값은 공백을 포함할 수 없습니다. 이스케이프 시퀀스는 지원되지 않습니다.

135 

136<h2 id="requirements">

137 요구 사항

138</h2>

139 

140Claude Code는 힌트에 대해 조치를 취하기 전에 두 가지 조건을 적용합니다. 두 검사 중 하나라도 실패한 힌트는 삭제됩니다:

141 

142* **자체 줄**: 태그는 자체 줄을 차지해야 합니다. 예를 들어 로그 문 내부에 줄 중간에 포함된 태그는 무시됩니다. 줄의 선행 및 후행 공백은 허용됩니다.

143* **공식 마켓플레이스**: `value`는 `claude-plugins-official`과 같은 Anthropic 제어 마켓플레이스의 플러그인을 참조해야 합니다. 다른 마켓플레이스를 가리키는 힌트는 자동으로 삭제됩니다.

144 

145힌트 줄은 버전 또는 유형이 인식되지 않을 때도 항상 모델에 도달하기 전에 출력에서 제거되므로 마커는 토큰 사용량에 계산되지 않습니다.

146 

147나머지 지침은 권장되지만 적용되지 않습니다. Claude Code는 CLI가 이를 따르는지 관찰할 수 없습니다:

148 

149* **stderr에 작성**: stderr는 `example-cli deploy | jq`와 같은 셸 파이프라인에서 태그를 제외합니다. Claude Code는 두 스트림을 모두 스캔하므로 stdout도 작동합니다.

150* **`CLAUDECODE`에서 제어**: `CLAUDECODE` 환경 변수가 설정된 경우에만 내보냅니다. 이렇게 하면 마커가 CLI를 직접 실행하는 사용자에게 나타나지 않습니다.

151 

152<h2 id="get-your-plugin-into-the-official-marketplace">

153 공식 마켓플레이스에 플러그인 추가

154</h2>

155 

156힌트 프로토콜은 공식 Anthropic 마켓플레이스 `claude-plugins-official`에 나열된 플러그인에 대해서만 적용됩니다. Anthropic은 자신의 재량에 따라 해당 마켓플레이스를 큐레이션하며, 앱 내 제출 양식은 플러그인을 [커뮤니티 마켓플레이스](/ko/plugins#submit-your-plugin-to-the-community-marketplace)에 추가합니다. 힌트 프로토콜은 이를 확인하지 않습니다. Anthropic 파트너 담당자와 함께 작업 중인 경우 그들에게 연락하여 공식 마켓플레이스 목록을 조정하세요.

157 

158<h2 id="see-also">

159 참고 항목

160</h2>

161 

162* [플러그인 만들기](/ko/plugins): CLI가 권장하는 플러그인 빌드

163* [플러그인 마켓플레이스 만들기 및 배포](/ko/plugin-marketplaces): 공식 마켓플레이스 외부에서 플러그인 호스팅

164* [환경 변수](/ko/env-vars): `CLAUDECODE` 및 관련 변수에 대한 전체 참조