Appearance
如果你的 CLI 或 SDK 已在官方 Anthropic 市场发布插件，可以通过向 stderr 输出一行 <claude-code-hint> 自闭合标签，让 Claude Code 向用户显示一次性的安装提示。标签只在 CLAUDECODE 环境变量被设置时发出，Claude Code 会从输出中剥离该行，不会传给模型，不消耗 token。每个插件只提示一次，每个会话最多弹出一条提示。用户确认后才会安装，永不自动安装。
Claude Code CLI 插件推荐提示配置方法
从你的 CLI 输出一行标记，让 Claude Code 主动提示用户安装你的官方插件。
如果你维护一个 CLI 或 SDK 并且已经在 Anthropic 官方市场中发布了插件，可以在工具检测到自己运行在 Claude Code 内部时，向 stderr 写入一行标记。Claude Code 读取到该标记后，会将其从输出中剥离，并向用户显示一次性的安装提示。
Claude Code 在将命令输出发送给模型之前会移除 hint 行，因此该标记永远不会出现在对话中，也不会计入 token 使用量。该协议不需要额外的命令，也不会改变你的 CLI 在非 Claude Code 环境下的输出。
本文面向 CLI 和 SDK 维护者。如果你是想安装插件的用户，请查阅发现与安装插件。
工作原理
Claude Code 在通过 Bash 和 PowerShell 工具运行的每条命令以及钩子命令中，都会将环境变量 CLAUDECODE 设置为 1。当你的 CLI 检测到该变量时，它将一个自闭合的 <claude-code-hint /> 标签写入 stderr。在钩子命令中，hint 标签会被剥离并忽略。只有 Bash 和 PowerShell 工具的输出才会触发安装提示。
当 Claude Code 收到命令输出时，它会：
- 扫描并移除 hint 行，确保输出到达模型前已被清理
- 检查 hint 是否指向官方 Anthropic 市场中的插件
- 检查该插件尚未安装且之前未被提示过
- 向用户显示安装提示，并注明发出 hint 的命令
Claude Code 从不自动安装插件，用户必须确认。
怎么发出 Hint 标记
将发出逻辑置于 CLAUDECODE 环境变量的判断之后，确保标记永远不会出现在普通用户终端中。然后将标签独占一行写入 stderr。
以下示例为官方市场中的 example-cli 插件发出 hint：
javascript
if (process.env.CLAUDECODE) {
process.stderr.write(
'<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
)
}python
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,
)go
if os.Getenv("CLAUDECODE") != "" {
fmt.Fprintln(os.Stderr,
`<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
}shell
[ -n "$CLAUDECODE" ] &&
printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2将 example-cli 替换为你插件的官方市场名称。
选择触发时机
你可以控制哪些代码路径发出 hint。Claude Code 会按插件去重，因此在每个调用点都发出也没有负面影响。以下是一些高效的触发点：
| 触发位置 | 为什么有效 |
|---|---|
--help 输出 | Claude 在探索不熟悉的 CLI 时经常运行帮助 |
| 未知子命令错误 | 在 Claude 对你的接口感到困惑时触发 |
| 登录或认证成功 | 用户已经进入配置心态 |
| 首次运行的欢迎消息 | 自然的引导时机 |
用户看到的提示界面
当 hint 通过所有检查后，Claude Code 会显示类似下面的提示：
text
─────────────────────────────────────────────────────────────
Plugin Recommendation
The example-cli command suggests installing a plugin.
Plugin: example-cli
Marketplace: claude-plugins-official
Official integration for example-cli deployments
Would you like to install it?
❯ 1. Yes, install example-cli
2. No
3. No, and don't show plugin installation hints again
─────────────────────────────────────────────────────────────提示中会标注发出 hint 的命令，方便用户识别工具与推荐插件是否匹配。如果用户 30 秒内未响应，提示自动视为 No。
提示频次有限制：
- 每插件仅一次：提示显示后，Claude Code 会记录该插件，无论用户如何回答都不会再次提示。
- 每会话仅一条：同一台机器上所有 CLI 发出的 hint，每个 Claude Code 会话最多只会显示一条提示。
选择 Yes 将插件安装到用户作用域。选择 No, and don't show plugin installation hints again 将禁用该用户未来的所有 hint 提示。
Hint 标签格式
hint 是一个自闭合标签，包含三个必需属性。
text
<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />| 属性 | 必需 | 描述 |
|---|---|---|
v | 是 | 协议版本。当前仅支持 1 |
type | 是 | hint 种类。当前仅支持 plugin |
value | 是 | 插件标识符，格式为 name@marketplace |
属性值可以用双引号引起来，也可以不加引号。不加引号时不能包含空白字符。不支持转义序列。
必要条件
Claude Code 在处理 hint 前会检查两个条件，不满足的 hint 会被丢弃：
- 独占一行：标签必须单独占一行。嵌入在行中（例如日志语句内）的标签会被忽略。行首和行尾的空格允许。
- 官方市场：
value必须指向 Anthropic 控制的市场（如claude-plugins-official）。指向其他市场的 hint 会被静默丢弃。
hint 行始终会在输出到达模型前被移除，即使版本或类型无法识别，因此该标记永远不会计入 token 使用量。
以下建议是推荐但非强制要求。Claude Code 无法监督你的 CLI 是否遵守：
- 写入 stderr：stderr 可避免标签进入 shell 管道（例如
example-cli deploy | jq）。Claude Code 会同时扫描两个输出流，所以 stdout 也可以工作。 - 依赖
CLAUDECODE：仅在环境变量CLAUDECODE被设置时发出。防止标记出现在直接运行 CLI 的用户终端中。
如何将插件纳入官方市场
hint 协议仅对列入 Anthropic 官方市场 claude-plugins-official 中的插件生效。该市场由 Anthropic 自行审核管理，应用内提交表单将插件添加到社区市场而非官方市场。如果你有 Anthropic 合作伙伴的联系方式，请与他们协调官方市场 listing。
参见
常见问题
为什么我的 hint 没有被 Claude Code 识别？
检查以下几点：1. 标签是否独占一行（前后允许空格）。2. 环境变量 CLAUDECODE 是否已设置为 1（只有通过 Bash/PowerShell 工具执行的命令才会设置该变量）。3. value 是否指向 claude-plugins-official 市场中的插件。4. 该插件此前是否已经对该用户提示过（每个插件只提示一次）。
hint 标签可以写入 stdout 吗？会不会计入 token？
可以写入 stdout，Claude Code 会同时扫描 stdout 和 stderr。无论写入哪个流，hint 行都会在到达模型前被剥离，不计入 token 使用量。但推荐写入 stderr，以避开 shell 管道。
用户选择了“不再显示插件安装提示”后，还能恢复吗？
目前没有公开的恢复方法。一旦用户选择该选项，Claude Code 会禁用该用户未来所有 hint 提示（包括你的和其他 CLI 的）。建议在提示中提醒用户此操作的后果。